Když faktura pro Vaši organizaci přijde přes Peppol nebo jinou síť, PSB dokument uloží a odešle notifikaci na Váš webhook. V tomto článku se dozvíte, jak tuto notifikaci přijmete, dokument stáhnete a nastavíte správu stavu.

Přijetí faktury probíhá ve čtyřech krocích:

1. Notifikace: PSB odešle webhook event InvoiceReceived na Váš endpoint
2. Stažení: stáhnete dokument přes PurchaseInvoice endpoint
3. Zpracování: zpracujete fakturu ve vlastním systému
4. Vyčištění (volitelné): odstraníte dokument z PSB

Pro přijímání faktur potřebujete webhook, který naslouchá na topic InvoiceReceived. Zaregistrujte ho přes Hook API:

POST /api/v1/hook

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

Jakmile faktura přijde, Váš endpoint obdrží POST požadavek s JSON payloadem. Tento payload obsahuje mimo jiné documentId a partyId, pomocí kterých dokument stáhnete.

Tip: Nastavte si také webhook na topic InvoiceReceivedError, abyste dostávali notifikace, pokud se při přijetí něco pokazí.

Použijte documentId z webhook payloadu pro stažení faktury:

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

Odpověď obsahuje XML dokument (standardně v původním formátu). Chcete dokument v jiném formátu? Použijte parametr targetDocumentTypeId:

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

PSB dokument automaticky transformuje na zadaný formát před vrácením.

PSB uchovává přijaté dokumenty podle tohoto schématu:

Doporučuje se stahovat dokumenty ihned po přijetí a ukládat je ve vlastním systému. Nespoléhejte se na PSB jako dlouhodobé úložiště.

Po zpracování můžete dokument manuálně odstranit:

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

Tím se dokument definitivně odstraní z PSB. Audit trail zůstává k dispozici.

Po přijetí můžete aktualizovat stav zpracování nákupní faktury. To je relevantní zejména pokud chcete odesílat Invoice Responses (stavové zprávy) odesílateli. Přečtěte si článek Odeslání Invoice Response.

PSB automaticky odešle MLS zprávu (Message Level Status) zpět odesílateli po přijetí dokumentu. Tím se potvrdí, že dokument byl přijat a doručen. Jako integrátor nemusíte na to nic konfigurovat: PSB to řeší zcela. Pokud sami odesíláte dokumenty, dostáváte MLS feedback přes webhook topic MessageLevelStatusReceived. Viz Nastavení webhooků pro konfiguraci.

Pokud nemůžete konfigurovat webhooky (například v on-premise prostředí bez příchozího internetového provozu), můžete faktury získávat i přes polling:

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

Tento endpoint vrátí seznam dostupných nákupních faktur. Webhooky jsou však vždy preferovanou metodou díky zpracování v reálném čase a nižší zátěži na API.

Pozor: U on-premise integrací zvažte i reverse webhook (HTTPS inbound hook), prostřednictvím kterého PSB pushuje dokumenty bez toho, aby Váš systém musel být přímo dostupný z internetu.

• Zpracovávejte idempotentně: PSB může ve výjimečných případech doručit event vícekrát. Na Vaší straně zkontrolujte, zda jste dokument již zpracovali, dříve než ho znovu importujete.
• Stahujte okamžitě: stahujte dokumenty co nejdříve po webhook notifikaci. 90denní retence je záchranná síť, ne strategie úložiště.
• Logujte documentId: uchovejte PSB documentId ve vlastním systému pro účely sledování a případného troubleshootingu.
• Konvertujte formát: pokud potřebujete specifický XML formát, použijte targetDocumentTypeId při stahování místo vlastní konverze.
• Webhook retries: pokud je váš endpoint dočasně nedostupný, PSB opakuje doručení notifikace po dobu až 5 dní. Delší výpadek? Použijte batch hooky jako fallback pro získání zmeškaných dokumentů.

Podívejte se na kompletní PurchaseInvoice endpointy a modely odpovědí na psb.econnect.eu.