API

Faktury OSS

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

Definicja

Obiekt OssInvoice zawiera następujące klucze:

Parametr	Typ danych	Wymagany	Opis
id	integer	Tylko do odczytu	ID Faktury OSS
number	string	Nie	Numer faktury OSS. Domyślnie generowany na podstawie Następny numer faktury OSS
country	string	Nie	Kraj klienta (pole `alpha_2` z listy obsługiwanych krajów)
client_email	string	Nie	Adres e-mail klienta
client_name	string	Nie	Nazwa klienta
client_street	string	Nie	Ulica klienta
client_street_number	string	Nie	Numer budynku klienta
client_flat_number	string	Nie	Numer mieszkania klienta
client_post_code	string	Nie	Kod pocztowy klienta
client_city	string	Nie	Miasto klienta
service_date	string	Nie	Data świadczenia usługi `RRRR-MM-DD`
issue_date	string	Nie	Data wystawienia faktury `RRRR-MM-DD`
payment_date	string	Nie	Data płatności `RRRR-MM-DD`
advance_price	integer	Nie	Wartość zaliczek w groszach
services	array of Services	Tak	Lista pozycji na fakturze (i link do services)
service_type	string	Tak	Rodzaj usługi: `electronic` – Usługa elektroniczna `broadcasting` – Usługa nadawcza `telecommunications` – Usługa telekomunikacyjna
sale_type	string	Tak	Typ usługi: `service` – Usługa `merchandise` – Towar
service_place_primary	string	Tak	Sposób ustalenia miejsca świadczenia usługi
service_place_secondary	string	Nie	Sposób ustalenia miejsca świadczenia usługi
currency	string	Tak	Waluta
recipient_signature	string	Nie	Imię i nazwisko Odbiorcy
seller_signature	string	Nie	Imię i nazwisko Sprzedawcy
comments	string	Nie	Uwagi
net_price	integer	Nie	Razem netto w groszach
tax_price	integer	Nie	Wartość VAT w groszach
gross_price	integer	Nie	Razem brutto w groszach
check_duplicate_number	boolean	Nie	Czy sprawdzać duplikacje numeru faktury `true` lub `false`

Services

Obiekt service zawiera następujące klucze:

Parametr	Typ danych	Wymagany	Opis
name	string	Tak	Nazwa pozycji
tax_rate	string	Tak	Stawka VAT (lista obsługiwanych stawek)
quantity	integer	Nie	Ilość
unit_net_price	integer	Nie	Cena netto za sztukę w groszach
net_price	integer	Nie	Wartość netto w groszach
gross_price	integer	Nie	Wartość brutto w groszach
tax_price	integer	Nie	Wartość podatku VAT w groszach
additional_price	integer	Nie	Wartość kosztów zmieniających w groszach
flat_rate_tax_symbol	string	W przypadku korzystania z ryczałtu ewidencjonowanego	Dostę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 odpowiedzi	Opis
200	Zapytanie zostało wykonane poprawnie
401	Brak autoryzacji lub uprawnień do danego zasobu

Podgląd

GET /v3/oss_invoices/{id}.json

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

częściowe odpowiedzi

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_name": "Boyer - 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,
          "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 odpowiedzi	Opis
200	Zapytanie zostało wykonane poprawnie
401	Brak autoryzacji lub uprawnień do danego zasobu
404	Zasó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_name": "Boyer - 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,
                "quantity": 4,
                "additional_price": 300,
                "flat_rate_tax_symbol": "5.5"
            },
            {
                "name": "Prod - 2",
                "tax_rate": 20,
                "net_price": 25000,
                "quantity": 3,
                "additional_price": 200
            },
            {
                "name": "Prod - 3",
                "tax_rate": 20,
                "gross_price": 25000,
                "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 odpowiedzi	Opis
201	Zasób został poprawnie utworzony
422	Zwracany 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 odpowiedzi	Opis
204	Zwracany po poprawnym usunięciu zasobu.
401	Brak 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.

Parametr	Typ danych	Wymagany	Opis
date	string	Nie	Data 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 odpowiedzi	Opis
204	Zwracany po poprawnym usunięciu zasobu.
401	Brak autoryzacji lub uprawnień do danego zasobu

Pobranie faktury OSS w formacie pdf

GET /v3/oss_invoices/{id}/pdf.json

Parametr	Typ danych	Wymagany	Opis
locale	string	Nie	Ję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.

Parametr	Typ danych	Wymagany	Opis
recipient	string	Nie	Adres email odbiorcy
send_copy	boolean	Nie	Czy wysłać na adres email właściciela konta?
locale	string	Nie	Ję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 odpowiedzi	Opis
202	Faktura została przekazana do wysłania
422	Zwracany wraz z informacją o błędach w przypadku problemów przy wysyłce.

Dokumentacja

Faktury OSS

Definicja

Services

Listowanie faktur OSS

Przykład curl

Przykładowa odpowiedź

Podgląd

Przykład curl

Przykładowa odpowiedź

Tworzenie

Tworzenie

Usuwanie

Usuwanie

Następny numer faktury OSS

Pobranie następnego numeru faktury

Przykładowa odpowiedź

Pobranie faktury OSS w formacie pdf

Pobranie faktury OSS w formacie pdf

Wysłanie faktury OSS via email

Wysłanie faktury via email