Wprowadzenie
KSeF rozstrzyga, czy faktura została przyjęta, asynchronicznie, więc samo wywołanie wysyłki to nie koniec: Notaly odpytuje KSeF za Ciebie i wypycha ostateczny wynik na Twój endpoint jako podpisany webhook — invoice.accepted (z numerem KSeF i UPO), invoice.rejected albo invoice.error. Każdy webhook jest podpisany HMAC i ponawiany z narastającym opóźnieniem, dzięki czemu budujesz niezawodną automatyzację zamówienie → faktura bez własnego pollingu.
Dlaczego webhooki pasują do KSeF
KSeF to krajowa platforma e-fakturowania Ministerstwa Finansów. Gdy wysyłasz fakturę FA(3), platforma zwraca status submitted i przetwarza dokument później. Samodzielne odpytywanie o wynik oznacza pisanie własnego workera w tle; webhook odwraca ten układ, więc wynik przychodzi do Ciebie w chwili, gdy jest znany.
Jakie zdarzenia otrzymasz
Notaly wysyła trzy główne zdarzenia. invoice.accepted oznacza, że KSeF przyjął fakturę, a payload zawiera numer KSeF, UPO i bezwzględny adres PDF. invoice.rejected oznacza odrzucenie, a pole error niesie kod. invoice.error obejmuje błędy po stronie Notaly, na przykład zgłoszenie, które nie mogło dotrzeć do KSeF.
Podpis HMAC
Każda dostawa jest podpisana HMAC, więc możesz zweryfikować, że żądanie naprawdę przyszło z Notaly i nie zostało zmodyfikowane. Zweryfikuj podpis na endpointzie, zanim zaufasz treści, i odrzucaj dostawy, które nie przechodzą kontroli.
Ponowienia i idempotencja
Gdy Twój endpoint jest nieosiągalny albo zwraca błąd, Notaly ponawia dostawę z narastającym opóźnieniem. To znaczy, że handler musi być idempotentny: dwukrotne zastosowanie tego samego zdarzenia invoice.accepted nie może utworzyć dwóch rekordów. Użyj identyfikatora zdarzenia albo faktury jako klucza deduplikacji.
Minimalny handler
Przy invoice.accepted zapisz numer KSeF i UPO przy fakturze i pokaż klientowi PDF. Przy invoice.rejected odczytaj kod błędu, popraw dane i wyślij ponownie. Trzymaj handler szybki, weryfikuj HMAC i zwracaj 2xx dopiero po zapisaniu wyniku.
FAQ
Po co mi webhooki do KSeF? KSeF przetwarza faktury asynchronicznie. Wywołanie wysyłki zwraca status submitted, a ostateczny wynik przychodzi później jako webhook.
Skąd wiem, że webhook jest prawdziwy? Notaly podpisuje każdy webhook HMAC, więc możesz zweryfikować podpis przed zaufaniem payloadowi.
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