Przepływ dokumentu i komunikaty statusowe API PSB

Dokument wysyłany przez PSB przechodzi przez ustaloną sekwencję faz przetwarzania — od przesłania do potwierdzonej dostawy lub ostatecznego niepowodzenia. W każdym punkcie przejścia PSB publikuje komunikat statusowy, który można pobrać przez API statusu lub przechwycić za pomocą webhooka.

Sześć faz dokumentu

Submit → Validate → Transform → Route → Acknowledge → Delivered
                                                   ↘ Failed

Faza

Co się dzieje

Typowe tematy

Submit

Dokument został przesłany przez API, hook mailfrom, SFTP pull lub inną metodę przychodzącą.

Pending

Validate

PSB waliduje dokument według schematu i reguł biznesowych (np. NLCIUS, Peppol BIS Billing, DICO).

Validated, *ReceivedError przy błędzie

Transform

Opcjonalna konwersja formatu przez silnik Transform. Krok wewnętrzny.

(wewnętrzny, brak osobnego tematu)

Route

PSB określa miejsce docelowe: Peppol, e-mail, SFTP lub inny kanał.

Routed

Acknowledge

Potwierdzenie od odbierającego punktu dostępu lub kanału.

Acknowledged

Delivered / Failed

Dostarczenie potwierdzone lub ostatecznie zakończone niepowodzeniem po wyczerpaniu wszystkich prób.

*Sent, *SentError

Kody statusu

Status

Znaczenie

Status końcowy?

Pending

Przesłany, walidacja jeszcze nie rozpoczęta

Nie

Validated

Walidacja zakończona sukcesem

Nie

Routed

Miejsce docelowe określone, gotowe do dostarczenia

Nie

Delivered

Dostarczenie potwierdzone przez odbiorcę lub kanał

Tak

Rejected

Odrzucony przez odbiorcę (np. via MLS Reject)

Tak

Failed

Dostarczenie ostatecznie nieudane po wszystkich próbach

Tak

Polityka ponowień przy dostarczaniu dokumentów

Parametr

Wartość

Maksymalna liczba prób

Łączny czas ponowień

~3 dni (około 72 godziny) od pierwszej próby

Kody z możliwością ponowienia

5xx i 429

Bez możliwości ponowienia

4xx (oprócz 429) — natychmiastowy *SentError

Backoff

Eksponencjalny

Polityka ponowień przy dostarczaniu webhooków

Parametr

Wartość

Maksymalna liczba prób

Łączny czas ponowień

~6 dni (około 137 godzin) od pierwszej próby

Backoff

Eksponencjalny

Limit czasu na próbę

100 sekund

Zdarzenie na próbę

HookSentRetry

Zdarzenie po ostatecznym niepowodzeniu

HookSentError

Często zadawane pytania

Jak śledzić status wysłanego dokumentu?

Masz dwie opcje. Przez API statusu (GET …/salesInvoice/{documentId}/status) pobierasz aktualny status. Do monitorowania w czasie rzeczywistym skonfiguruj webhooki na odpowiednich tematach, takich jak InvoiceSent, InvoiceSentRetry i InvoiceSentError.

Jak długo PSB próbuje dostarczyć dokument?

PSB automatycznie ponawia dostarczanie do 8 razy przez około 3 dni (72 godziny). Po ostatecznym niepowodzeniu następuje {DocumentType}SentError i wymagane jest ręczne działanie.

Jak długo PSB próbuje dostarczyć webhook?

PSB próbuje dostarczyć powiadomienie webhook do 12 razy, rozłożonych na około 6 dni (137 godzin). Po ostatecznym niepowodzeniu następuje zdarzenie HookSentError.

Zobacz interaktywną dokumentację API

Powiązane

Przegląd PSB: architektura i możliwości

Obsługa błędów i logika ponowień

Idempotentność: zapobieganie podwójnym przesyłkom