Gdy faktura dla Państwa organizacji dociera przez Peppol lub inną sieć, PSB zapisuje dokument i wysyła powiadomienie na webhook. W tym artykule opisano, jak odebrać powiadomienie, pobrać dokument i skonfigurować zarządzanie statusem.

Odbiór faktury przebiega w czterech krokach:

1. Powiadomienie: PSB wysyła zdarzenie webhook InvoiceReceived na Państwa endpoint
2. Pobieranie: pobranie dokumentu przez endpoint PurchaseInvoice
3. Przetwarzanie: przetworzenie faktury we własnym systemie
4. Czyszczenie (opcjonalne): usunięcie dokumentu z PSB

Do odbierania faktur potrzebny jest webhook nasłuchujący na topicu InvoiceReceived. Należy go zarejestrować przez Hook API:

POST /api/v1/hook

{
  "action": "https://mijn-systeem.nl/webhook/invoices#mijnSecretKey",
  "topics": ["InvoiceReceived"]
}

Gdy faktura dotrze, Państwa endpoint otrzymuje żądanie POST z payloadem JSON. Ten payload zawiera m.in. documentId i partyId, za pomocą których można pobrać dokument.

Wskazówka: warto również skonfigurować webhook na topicu InvoiceReceivedError, aby otrzymywać powiadomienia w przypadku problemów z odbiorem.

Należy użyć documentId z payloadu webhooka, aby pobrać fakturę:

GET /api/v1/{partyId}/purchaseInvoice/{documentId}/download HTTP/1.1
Host: psb.econnect.eu
Authorization: Bearer {access_token}

Odpowiedź zawiera dokument XML (domyślnie w oryginalnym formacie). Chcą Państwo otrzymać dokument w innym formacie? Należy użyć parametru targetDocumentTypeId:

GET /api/v1/{partyId}/purchaseInvoice/{documentId}/download?targetDocumentTypeId={URN}

PSB automatycznie transformuje dokument do określonego formatu przed jego zwróceniem.

PSB przechowuje otrzymane dokumenty według następującego schematu:

Zaleca się pobieranie dokumentów natychmiast po otrzymaniu i przechowywanie ich we własnym systemie. Nie należy polegać na PSB jako magazynie długoterminowym.

Po przetworzeniu można ręcznie usunąć dokument:

DELETE /api/v1/{partyId}/purchaseInvoice/{documentId} HTTP/1.1
Host: psb.econnect.eu
Authorization: Bearer {access_token}

Powoduje to definitywne usunięcie dokumentu z PSB. Ślad audytu pozostaje dostępny.

Po otrzymaniu można zaktualizować status przetwarzania faktury zakupowej. Jest to szczególnie istotne, gdy chce się wysyłać Invoice Response (komunikaty statusowe) do nadawcy. Szczegóły opisano w artykule Wysyłanie Invoice Response.

PSB automatycznie wysyła wiadomość MLS (Message Level Status) z powrotem do nadawcy po otrzymaniu dokumentu. Potwierdza to, że dokument został odebrany i dostarczony. Jako integrator nie musisz niczego konfigurować: PSB obsługuje to w całości. Jeśli sam wysyłasz dokumenty, otrzymujesz informacje zwrotne MLS przez topic webhooka MessageLevelStatusReceived. Zobacz Konfiguracja webhooków w celu konfiguracji.

Jeśli nie można skonfigurować webhooków (np. w środowisku on-premise bez ruchu przychodzącego z internetu), faktury można również pobierać przez polling:

GET /api/v1/{partyId}/purchaseInvoice HTTP/1.1
Host: psb.econnect.eu
Authorization: Bearer {access_token}

Ten endpoint zwraca listę dostępnych faktur zakupowych. Webhooki są jednak zawsze preferowaną metodą ze względu na przetwarzanie w czasie rzeczywistym i mniejsze obciążenie API.

Uwaga: przy integracjach on-premise warto również rozważyć reverse webhook (HTTPS inbound hook), dzięki któremu PSB wysyła dokumenty bez konieczności bezpośredniej dostępności Państwa systemu z internetu.

• Przetwarzanie idempotentne: w wyjątkowych przypadkach PSB może dostarczyć zdarzenie wielokrotnie. Należy sprawdzić po swojej stronie, czy dokument został już przetworzony, zanim zostanie ponownie zaimportowany.
• Natychmiastowe pobieranie: dokumenty należy pobierać jak najszybciej po powiadomieniu webhook. 90-dniowa retencja to siatka bezpieczeństwa, a nie strategia przechowywania.
• Rejestrowanie documentId: PSB documentId należy przechowywać we własnym systemie w celu śledzenia i ewentualnego rozwiązywania problemów.
• Konwersja formatu: jeśli potrzebny jest określony format XML, należy użyć targetDocumentTypeId podczas pobierania zamiast samodzielnej konwersji.
• Ponawianie webhooków: jeśli Twój endpoint jest tymczasowo nieosiągalny, PSB ponawia dostarczanie powiadomienia przez maksymalnie 5 dni. Dłuższy przestój? Użyj batch hooków jako fallbacku, aby pobrać utracone dokumenty.

Pełne endpointy PurchaseInvoice i modele odpowiedzi dostępne są na psb.econnect.eu.