Dokumentacja

Faktury OSS

Zarządzanie fakturami OSS należącymi do użytkownika

Definicja

Obiekt OssInvoice zawiera następujące klucze:

ParametrTyp danychWymaganyOpis
idintegerTylko do odczytuID Faktury OSS
numberstringNieNumer faktury OSS. Domyślnie generowany na podstawie Następny numer faktury OSS
countrystringNieKraj klienta (pole alpha_2 z listy obsługiwanych krajów)
client_emailstringNieAdres e-mail klienta
client_first_namestringTakImię klienta
client_last_namestringTakNazwisko klienta
client_streetstringNieUlica klienta
client_street_numberstringNieNumer budynku klienta
client_flat_numberstringNieNumer mieszkania klienta
client_post_codestringNieKod pocztowy klienta
client_citystringNieMiasto klienta
service_datestringNieData świadczenia usługi RRRR-MM-DD
issue_datestringNieData wystawienia faktury RRRR-MM-DD
payment_datestringNieData płatności RRRR-MM-DD
advance_priceintegerNieWartość zaliczek w groszach
servicesarray of ServicesTakLista pozycji na fakturze (i link do services)
service_typestringTakRodzaj usługi:
  • electronic – Usługa elektroniczna
  • broadcasting – Usługa nadawcza
  • telecommunications – Usługa telekomunikacyjna
sale_typestringTakTyp usługi:
  • service – Usługa
  • merchandise – Towar
service_place_primarystringTakSposób ustalenia miejsca świadczenia usługi
service_place_secondarystringNieSposób ustalenia miejsca świadczenia usługi
currencystringTakWaluta
recipient_signaturestringNieImię i nazwisko Odbiorcy
seller_signaturestringNieImię i nazwisko Sprzedawcy
commentsstringNieUwagi
net_priceintegerNieRazem netto w groszach
tax_priceintegerNieWartość VAT w groszach
gross_priceintegerNieRazem brutto w groszach
check_duplicate_numberbooleanNieCzy sprawdzać duplikacje numeru faktury true lub false

Services

Obiekt service zawiera następujące klucze:

ParametrTyp danychWymaganyOpis
namestringTakNazwa pozycji
tax_ratestringTakStawka VAT (lista obsługiwanych stawek)
unitstringNieJednostka miary
quantityintegerNieIlość
unit_net_priceintegerNieCena netto za sztukę w groszach
net_priceintegerNieWartość netto w groszach
gross_priceintegerNieWartość brutto w groszach
tax_priceintegerNieWartość podatku VAT w groszach
additional_priceintegerNieWartość kosztów zmieniających w groszach
flat_rate_tax_symbolstringW przypadku korzystania z ryczałtu ewidencjonowanegoDostępne stawki:
  • 2
  • 3
  • 5.5
  • 8.5
  • 17
  • 20
lista obsługiwanych stawek

Listowanie faktur OSS

GET /v3/oss_invoices.json

Akcja listowania zwraca odpowiedź zawierającą tablicę obiektów pod kluczem entities oraz informacje pomocnicze dotyczące stronicowania. Domyślne sortowanie dla zwracanej tablicy odbywa się malejąco przy użyciu pola issue_date.

Dodatkowo, na zbiorze danych można wykonywać nastepujące operacje:

Przykład akcji listowania:

Przykład curl

curl -H "X-inFakt-ApiKey: 49206c6f766520496e66616b74203a3e" \
  https://api.infakt.pl/v3/oss_invoices.json

Przykładowa odpowiedź


{
  "metainfo": {
      "count": 10,
      "total_count": 10,
      "next": "https://api.infakt.pl/api/v3/oss_invoices.json?offset=10",
      "previous": "https://api.infakt.pl/api/v3/oss_invoices.json?offset=0"
  },
  "entities":  [{
    "id": 42,
    "number": "1/OSS/05/2021",
    "country": "AT",
    "currency": "EUR",
    "additional_price": 0,
    "comments": ""
    ...
  }, {
    "id": 43,
    "number": "2/OSS/05/2021",
    "country": "DE",
    "currency": "EUR",
    "additional_price": 0,
    "comments": ""
    ...
  }]
}

Możliwe kody odpowiedzi:

Kod odpowiedziOpis
200Zapytanie zostało wykonane poprawnie
401Brak autoryzacji lub uprawnień do danego zasobu

Podgląd

GET /v3/oss_invoices/{id}.json

Dodatkowo, na zbiorze danych można wykonywać nastepujące operacje:

Przykład curl

curl -H "X-inFakt-ApiKey: 49206c6f766520496e66616b74203a3e" \
https://api.infakt.pl/v3/oss_invoices/42.json
          

Przykładowa odpowiedź


{
  "id": 42,
  "number": "1/OSS/05/2021",
  "country": "AT",
  "client_email": "clientemail@example.com",
  "client_first_name": "Boyer",
  "client_last_name": "Schumm",
  "client_street": "Marquis Plaza",
  "client_street_number": "3016",
  "client_flat_number": null,
  "client_post_code": "22-222",
  "client_city": "Lilyville",
  "service_date": "2021-08-01",
  "issue_date": "2021-08-01",
  "payment_date": "2021-08-01",
  "service_type": null,
  "service_place_primary": "185 Jaqueline Inlet",
  "service_place_secondary": "Labadie, Bergstrom and Bahringer",
  "currency": "EUR",
  "seller_signature": "seller_signature",
  "recipient_signature": "multi-byte auxiliary facilitate Chair solid",
  "comments": "haptic SSL HDD Ohio Future",
  "net_price": 100000,
  "tax_price": 20000,
  "gross_price": 120000,
  "advance_price": 0,
  "sale_type": "merchandise",
  "services": [
      {
          "id": 1964,
          "unit": "kg",
          "quantity": 4.0,
          "name": "Prod - 1",
          "net_price": 100000,
          "tax_price": 20000,
          "unit_net_price": 25000,
          "additional_price": 0,
          "gross_price": 120000,
          "tax_rate": 20.0
      }
  ]
}
            
          

Możliwe kody odpowiedzi:

Kod odpowiedziOpis
200Zapytanie zostało wykonane poprawnie
401Brak autoryzacji lub uprawnień do danego zasobu
404Zasób nie został odnaleziony

Tworzenie

POST /v3/oss_invoices.json

Tworzenie

curl -H "X-inFakt-ApiKey: 49206c6f766520496e66616b74203a3e" \
  -H "Content-Type: application/json" \
  -X POST \
  -d  '{"oss_invoice": {
          "country": "AT",
          "number": "2021-09-10T12:48:45.187Z",
          "check_duplicate_number": false,
          "client_email": "clientemail@example.com",
          "client_first__name": "Boyer",
          "client_last_name": "Schumm",
          "client_street": "Marquis Plaza",
          "client_street_number": "3016",
          "client_flat_number": "",
          "client_post_code": "22-222",
          "client_city": "South Harryville",
          "sale_type": "merchandise",
          "currency": "EUR",
          "issue_date": "01-08-2021",
          "service_date": "01-08-2021",
          "payment_date": "01-08-2021",
          "service_place_primary": "185 Jaqueline Inlet",
          "service_place_secondary": "Labadie, Bergstrom and Bahringer",
          "recipient_signature": "multi-byte auxiliary facilitate Chair solid",
          "seller_signature": "seller_signature",
          "comments": "haptic SSL HDD Ohio Future",
          "advance_price": 1212,
          "services": [
               {
                "name": "Prod - 1",
                "tax_rate": 20,
                "unit_net_price": 25000,
                "unit": "kg",
                "quantity": 4,
                "additional_price": 300,
                "flat_rate_tax_symbol": "5.5"
            },
            {
                "name": "Prod - 2",
                "tax_rate": 20,
                "net_price": 25000,
                "unit": "kg",
                "quantity": 3,
                "additional_price": 200
            },
            {
                "name": "Prod - 3",
                "tax_rate": 20,
                "gross_price": 25000,
                "unit": "kg",
                "quantity": 3,
                "additional_price": 0
            }
          ]
      }
  }'
https://api.infakt.pl/v3/oss_invoices.json

Aby wystawić fakturę od wartości brutto podajemy gross_price i nie podajemy unit_net_price ani net_price. System wyliczy odpowiednio pozostałe wartości dla pozycji.
Jeśli unit_net_price lub net_price zostaną przekazane w parametrach zapytania dla pozycji, wartości na fakturze są zawsze liczone od wartości netto.
Cena netto, brutto i kwota podatku dla całości FV zostanie automatycznie wyliczona.

Możliwe kody odpowiedzi:

Kod odpowiedziOpis
201Zasób został poprawnie utworzony
422Zwracany wraz z informacją o błędach w przypadku problemów z zasobem.

Usuwanie

DELETE /v3/oss_invoices/{id}.json

Usuwanie

curl -H "X-inFakt-ApiKey: 49206c6f766520496e66616b74203a3e" \
    -X DELETE \
    https://api.infakt.pl/v3/oss_invoices/42.json

Możliwe kody odpowiedzi:

Kod odpowiedziOpis
204Zwracany po poprawnym usunięciu zasobu.
401Brak autoryzacji lub uprawnień do danego zasobu

Następny numer faktury OSS

GET /v3/oss_invoices/next_number.json

Następny numer faktury jest nadawany na podstawie daty wystawienia faktury. W procesie wyboru kolejnego numeru faktury są brane pod uwagę tylko faktury z danego miesiąca.

ParametrTyp danychWymaganyOpis
datestringNieData wystawienia w formacie RRRR-MM-DD

Pobranie następnego numeru faktury

curl -H "X-inFakt-ApiKey: 49206c6f766520496e66616b74203a3e" \
    https://api.infakt.pl/v3/oss_invoices/next_number.json

Przykładowa odpowiedź

{
  "next_number": "5/OSS/05/2022",
  "invoice_date": "2022-05-05",
}

Możliwe kody odpowiedzi:

Kod odpowiedziOpis
204Zwracany po poprawnym usunięciu zasobu.
401Brak autoryzacji lub uprawnień do danego zasobu

Pobranie faktury OSS w formacie pdf

GET /v3/oss_invoices/{id}/pdf.json
ParametrTyp danychWymaganyOpis
localestringNieJęzyk dokumentu: pl – Polski, en – Angielski

Pobranie faktury OSS w formacie pdf

curl -H "X-inFakt-ApiKey: 49206c6f766520496e66616b74203a3e" \
  https://api.infakt.pl/v3/oss_invoices/42/pdf.json?locale=pl
W odpowiedzi zostaje zwrócona faktura w formie pliku PDF.

Wysłanie faktury OSS via email

POST /v3/oss_invoices/{id}/deliver_via_email.json

Przy wysyłce dokumentu pocztą elektroniczną, można podać adres email, na który będzie wysłana faktura. W przypadku, gdy nie zostanie podany – faktura zostanie wysłana na adres email Klienta.

ParametrTyp danychWymaganyOpis
recipientstringNieAdres email odbiorcy
send_copybooleanNieCzy wysłać na adres email właściciela konta?
localestringNieJęzyk dokumentu: pl – Polski, en – Angielski

Wysłanie faktury via email

curl -H "X-inFakt-ApiKey: 49206c6f766520496e66616b74203a3e" \
  -X POST \
  https://api.infakt.pl/v3/oss_invoices/42/deliver_via_email.json

Możliwe kody odpowiedzi:

Kod odpowiedziOpis
202Faktura została przekazana do wysłania
422Zwracany wraz z informacją o błędach w przypadku problemów przy wysyłce.