Każda integracja z API prędzej czy później napotka błędy. Awaria sieci, nieosiągalny serwer, nieprawidłowo sformatowany dokument: to normalna część pracy z API. PSB API komunikuje błędy za pomocą standardowych kodów statusu HTTP i ustrukturyzowanych odpowiedzi JSON. Ponadto PSB posiada wbudowany mechanizm ponawiania, który automatycznie obsługuje tymczasowe błędy podczas dostarczania dokumentów.

W tym artykule dowiesz się, jakie kody statusu zwraca PSB, jak interpretować odpowiedzi błędów, kiedy można bezpiecznie ponowić żądanie i jak działa automatyczny mechanizm ponawiania PSB.

PSB API używa standardowych kodów statusu HTTP do wskazania wyniku żądania. Kody statusu dzielą się na dwie kategorie: błędy klienta (4xx), które musisz naprawić samodzielnie, oraz błędy serwera (5xx), które możesz ponowić.

Przy błędzie 4xx problem leży w samym żądaniu. Ponowne wysłanie z tymi samymi danymi da ten sam rezultat. Napraw przyczynę przed ponowną próbą.

Wyjątek od zasady „tylko 5xx można ponawiać”: 429 Too Many Requests wskazuje na ograniczenie liczby żądań i można go ponowić. Poczekaj i uwzględnij nagłówek Retry-After przed ponownym wysłaniem żądania.

Błąd 5xx wskazuje na tymczasowy problem po stronie serwera. Samo żądanie może być poprawne. Razem z 429 są to jedyne kody statusu, przy których ponowienie ma sens.

Uwaga: endpoint wysyłki akceptuje maksymalnie 24 MB na żądanie, włącznie z narzutem HTTP. Ładunki przekraczające ten limit są odrzucane przez serwer WWW z HTTP 500 zamiast 413, ponieważ odrzucenie następuje przed walidacją na poziomie aplikacji. Pamiętaj o tym przy załącznikach zakodowanych w base64: dodają one około 33% do rozmiaru pliku.

Przy błędzie 4xx odpowiedź zawiera treść JSON opisującą problem. Te informacje pomagają szybko zidentyfikować przyczynę.

{
  "error": "Validation failed",
  "message": "The supplied document is not valid UBL 2.1",
  "details": [
    "cbc:InvoiceTypeCode is missing"
  ]
}

Przy błędzie 5xx odpowiedź nie zawsze jest ustrukturyzowana. Opieraj logikę ponawiania na kodzie statusu HTTP, a nie na treści body.

Nie każdy błąd zasługuje na ponowienie. Zasada jest prosta: tylko kody statusu 5xx i timeouty sieciowe warto ponawiać. Przy błędach 4xx musisz zmodyfikować żądanie przed ponownym wysłaniem.

Zalecaną strategią ponawiania jest exponential backoff: zacznij od krótkiego czasu oczekiwania i podwajaj go przy każdej kolejnej próbie.

Wskazówka: dodaj niewielki losowy rozrzut (jitter) do czasu oczekiwania. Jeśli wielu klientów ponawia żądania jednocześnie po awarii, jitter zapobiega ich jednoczesnym trafieniu na serwer.

Zawsze łącz logikę ponawiania z headerem X-EConnect-DocumentId. Dołączając ten sam documentId przy każdej próbie, PSB gwarantuje, że dokument nigdy nie zostanie przetworzony dwukrotnie. Jeśli PSB otrzyma documentId, który został już przetworzony, zwraca 409 Conflict jako potwierdzenie.

Zobacz Idempotency: zapobieganie podwójnym wysyłkom, aby uzyskać pełne wyjaśnienie i przykłady kodu.

Oprócz logiki ponawiania, którą implementujesz samodzielnie, PSB posiada własny mechanizm ponawiania dostarczania dokumentów. Jeśli PSB próbuje dostarczyć fakturę lub zamówienie do odbiorcy, a ta strona zwraca błąd 5xx, PSB automatycznie wznawia dostarczanie.

PSB wykonuje do 8 prób ponawiania rozłożonych na około 35 godzin. Przy każdej próbie PSB publikuje zdarzenie, dzięki czemu możesz śledzić postęp:

Jeśli skonfigurowano webhook dla tych tematów, przy każdej próbie otrzymujesz powiadomienie. Po InvoiceSentError lub OrderSentError wymagane jest ręczne działanie: skontaktuj się z odbiorcą lub eskaluj przez eConnect Support.

Wskazówka: subskrybuj tematy InvoiceSentRetry i InvoiceSentError za pomocą webhooka. Dzięki temu natychmiast wykryjesz problemy z dostarczaniem i możesz działać proaktywnie.

Dla webhooków PSB stosuje oddzielny harmonogram ponawiania. Jeśli Twój endpoint webhookowy jest nieosiągalny lub nie zwraca kodu statusu 2xx, PSB ponawia dostarczanie zdarzenia.

PSB oczekuje odpowiedzi 2xx od Twojego endpointu w ciągu 100 sekund. Każda inna odpowiedź (lub timeout) liczy się jako nieudana próba. Dlatego przetwarzaj przychodzące webhooki jak najszybciej, potwierdź odbiór odpowiedzią 200 OK i wykonuj ciężkie przetwarzanie asynchronicznie w procesie w tle.

Uwaga: jeśli Twój endpoint jest nieosiągalny przez dłuższy czas, PSB przestaje ponawiać po 5 dniach. Pominięte zdarzenia można nadal pobrać za pomocą endpointu batch. Zobacz Batch hooks, aby uzyskać więcej informacji.

W przypadku integracji uzyskujących dostęp do PSB z chronionej sieci (zapora ogniowa, proxy, lista dozwolonych), należy zezwolić na podstawowe nazwy hostów i nazwy hostów failover. everbinding.nl to starszy domen eConnect, aktywnie używany do failover PSB.

Umieść wszystkie cztery nazwy hostów na białej liście na porcie 443 (HTTPS). Bez nazw hostów failover poprawne połączenie PSB może stać się nieosiągalne podczas zdarzenia awaryjnego, podczas gdy PSB sama działa.