Wprowadzenie
Gdy tworzysz fakturę, odpowiedź POST /invoices zwraca status submitted z numerem referencyjnym KSeF, a ostateczna decyzja — accepted lub rejected — przychodzi później. Status sprawdzisz, odpytując GET /invoices/{id} (który ponownie odpytuje KSeF, dopóki faktura jest w submitted) albo nasłuchując podpisanego webhooka. UPO i numer KSeF przychodzą razem ze statusem accepted.
Statusy
Faktura przechodzi przez niewielki zestaw stanów. draft oznacza, że XML FA(3) został wygenerowany, ale nie wysłany (na przykład KSeF był niedostępny). submitted oznacza, że dotarł do KSeF i jest przetwarzany. accepted oznacza, że KSeF go przyjął i ustawione są numer KSeF oraz UPO. rejected oznacza, że KSeF go odrzucił, a pole error niesie stabilny kod, na przykład ksef_rejected:<kod>.
Sprawdzanie przez odpytywanie
GET /invoices/{id} zwraca ten sam obiekt faktury, który dostałeś przy utworzeniu. Dopóki faktura jest w submitted, to wywołanie dodatkowo sprawdza KSeF i zapisuje decyzję, więc odpytywanie jest sensowną alternatywą dla webhooków, gdy nie chcesz stawiać własnego endpointu. Odpytuj w rozsądnych odstępach — KSeF decyduje asynchronicznie, więc pojedyncze sprawdzenie od razu po wysłaniu zwykle pokaże jeszcze submitted.
Sprawdzanie przez webhook
Jeśli zarejestrujesz endpoint HTTPS, Notaly wypchnie Ci wynik. invoice.accepted niesie numer KSeF, UPO i bezwzględny adres pdfUrl; invoice.rejected niesie kod błędu; invoice.error oznacza, że faktury nie udało się przetworzyć. Każda dostawa jest podpisana HMAC i ponawiana z narastającym opóźnieniem, a dostarczanie jest co najmniej raz, więc deduplikuj po nagłówku X-Webhook-Id.
W panelu
Panel Notaly pokazuje listę faktur ze statusem każdej z nich i pozwala otworzyć XML, PDF oraz — dla faktur zaakceptowanych — UPO. To najszybszy sposób, żeby ręcznie sprawdzić pojedynczy dokument.
FAQ
Skąd wiem, jaki jest ostateczny wynik po wysłaniu? Odpytaj GET /invoices/{id} (ponownie sprawdza KSeF, dopóki faktura jest w submitted) albo nasłuchuj podpisanego webhooka invoice.accepted / invoice.rejected.
Kiedy dostaję UPO? Razem ze statusem accepted — zarówno payload webhooka, jak i obiekt faktury niosą UPO i numer KSeF.
Zastrzeżenie
Notaly nie jest doradcą podatkowym, księgowym ani prawnym. Ten artykuł ma charakter informacyjny, nie stanowi porady podatkowej i może być nieaktualny. Ponosisz odpowiedzialność za własne rozliczenia VAT; w razie potrzeby skonsultuj się z wykwalifikowanym księgowym.
Źródła
Źródło: www.podatki.gov.pl