Dokumentacja

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:

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.