Keď faktúra pre Vašu organizáciu príde cez Peppol alebo inú sieť, PSB dokument uloží a odošle notifikáciu na Váš webhook. V tomto článku sa dozviete, ako túto notifikáciu prijmete, dokument stiahnete a nastavíte správu stavu.

Prijatie faktúry prebieha v štyroch krokoch:

1. Notifikácia: PSB odošle webhook event InvoiceReceived na Váš endpoint
2. Stiahnutie: stiahnete dokument cez PurchaseInvoice endpoint
3. Spracovanie: spracujete faktúru vo vlastnom systéme
4. Vyčistenie (voliteľné): odstránite dokument z PSB

Na prijímanie faktúr potrebujete webhook, ktorý počúva na topic InvoiceReceived. Zaregistrujte ho cez Hook API:

POST /api/v1/hook

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

Akonáhle faktúra príde, Váš endpoint obdrží POST požiadavku s JSON payloadom. Tento payload obsahuje okrem iného documentId a partyId, pomocou ktorých dokument stiahnete.

Tip: Nastavte si tiež webhook na topic InvoiceReceivedError, aby ste dostávali notifikácie, ak sa pri prijatí niečo pokazí.

Použite documentId z webhook payloadu na stiahnutie faktúry:

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

Odpoveď obsahuje XML dokument (štandardne v pôvodnom formáte). Chcete dokument v inom formáte? Použite parameter targetDocumentTypeId:

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

PSB dokument automaticky transformuje na zadaný formát pred vrátením.

PSB uchováva prijaté dokumenty podľa tejto schémy:

Odporúča sa sťahovať dokumenty ihneď po prijatí a ukladať ich vo vlastnom systéme. Nespoliehajte sa na PSB ako dlhodobé úložisko.

Po spracovaní môžete dokument manuálne odstrániť:

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

Tým sa dokument definitívne odstráni z PSB. Audit trail zostáva k dispozícii.

Po prijatí môžete aktualizovať stav spracovania nákupnej faktúry. To je relevantné najmä ak chcete odosielať Invoice Responses (stavové správy) odosielateľovi. Prečítajte si článok Odoslanie Invoice Response.

PSB automaticky odošle MLS správu (Message Level Status) späť odosielateľovi po prijatí dokumentu. Tým sa potvrdí, že dokument bol prijatý a doručený. Ako integrátor nemusíte na to nič konfigurovať: PSB to rieši úplne. Ak sami odosielate dokumenty, dostávate MLS feedback cez webhook topic MessageLevelStatusReceived. Pozri Nastavenie webhookov pre konfiguráciu.

Ak nemôžete konfigurovať webhooky (napríklad v on-premise prostredí bez prichádzajúceho internetového prenosu), môžete faktúry získavať aj cez polling:

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

Tento endpoint vráti zoznam dostupných nákupných faktúr. Webhooky sú však vždy preferovanou metódou vďaka spracovaniu v reálnom čase a nižšej záťaži na API.

Pozor: Pri on-premise integráciách zvážte aj reverse webhook (HTTPS inbound hook), prostredníctvom ktorého PSB pushuje dokumenty bez toho, aby Váš systém musel byť priamo dostupný z internetu.

• Spracovávajte idempotentne: PSB môže vo výnimočných prípadoch doručiť event viackrát. Na Vašej strane skontrolujte, či ste dokument už spracovali, predtým než ho znovu importujete.
• Sťahujte okamžite: sťahujte dokumenty čo najskôr po webhook notifikácii. 90-dňová retencia je záchranná sieť, nie stratégia úložiska.
• Logujte documentId: uchovajte PSB documentId vo vlastnom systéme na účely sledovania a prípadného troubleshootingu.
• Konvertujte formát: ak potrebujete špecifický XML formát, použite targetDocumentTypeId pri sťahovaní namiesto vlastnej konverzie.
• Webhook retries: ak je váš endpoint dočasne nedostupný, PSB opakuje doručenie notifikácie po dobu až 5 dní. Dlhší výpadok? Použite batch hooky ako fallback na získanie zmeškaných dokumentov.

Pozrite si kompletné PurchaseInvoice endpointy a modely odpovedí na psb.econnect.eu.