Dokumenty sprzedaży można tworzyć na dwa sposoby. Żądanie synchroniczne POST /invoices.json tworzy fakturę od razu i zwraca ją w odpowiedzi. Żądanie asynchroniczne POST /async/invoices.json przyjmuje tę samą treść, dodaje zlecenie do kolejki i zwraca tylko identyfikator zadania invoice_task_reference_number.
Wynik zadania odczytuje się przez GET /async/{kind}/status/{invoice_task_reference_number}.json albo z webhooka async_invoice_creation_success lub async_invoice_creation_error. Etap przetwarzania podaje pole processing_code:
processing_code |
Znaczenie |
|---|---|
100 |
zlecenie przyjęte |
120 |
zlecenie czeka w kolejce |
140 |
zlecenie jest przetwarzane |
201 |
faktura utworzona; invoice_uuid wskazuje fakturę |
200 |
akcja wykonana (np. oznaczenie faktury jako opłaconej) |
422 |
błąd; szczegóły są w invoice_errors |
Kiedy wybrać kolejkę
Kolejka nadaje numery faktur po kolei, więc równoległe zlecenia nie kolidują w numeracji. Integracja nie czeka na utworzenie dokumentu: może wysłać wiele zleceń w krótkim czasie, a wyniki sprawdzić później. Tryb asynchroniczny sprawdza się w sklepach internetowych i systemach, które wystawiają faktury masowo lub równolegle. Pojedynczą fakturę wystawianą na żądanie użytkownika prościej utworzyć synchronicznie.
Ograniczenia
- Kolejka nie przyspiesza wystawienia pojedynczej faktury. Wynik jest dostępny później niż w trybie synchronicznym.
- Kod
201w odpowiedzi naPOST /async/...oznacza tylko przyjęcie zlecenia. Faktura może nie powstać, np. z powodu błędu walidacji (processing_code: 422). - W kolejce można tworzyć faktury VAT, zaliczkowe, końcowe, korygujące, marża, korygujące marża, OSS, korygujące OSS i wewnętrzne, a także dowody wewnętrzne, utargi dzienne i raporty fiskalne. Faktury zaliczkowe i końcowe w procedurze marży tworzy się tylko synchronicznie.
- Wysyłka do KSeF to osobny proces. Też działa w tle, ale ma własne statusy (patrz KSeF w inFakcie).