Wanneer een factuur voor jouw organisatie binnenkomt via Peppol of een ander netwerk, slaat de PSB het document op en stuurt een notificatie naar je webhook. In dit artikel lees je hoe je die notificatie ontvangt, het document downloadt en het statusbeheer inricht.

Het ontvangen van een factuur verloopt in vier stappen:

1. Notificatie: de PSB stuurt een webhook-event InvoiceReceived naar je endpoint
2. Download: je haalt het document op via het PurchaseInvoice-endpoint
3. Verwerking: je verwerkt de factuur in je eigen systeem
4. Opruiming (optioneel): je verwijdert het document uit de PSB

Om facturen te ontvangen heb je een webhook nodig die luistert op het topic InvoiceReceived. Registreer deze via de Hook API:

POST /api/v1/hook

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

Zodra een factuur binnenkomt, ontvangt je endpoint een POST-request met een JSON-payload. Deze payload bevat onder andere het documentId en de partyId waarmee je het document kunt ophalen.

Tip: Stel ook een webhook in op het topic InvoiceReceivedError om notificaties te ontvangen als er iets misgaat bij de ontvangst.

Voor het downloaden zijn er twee endpoints, afhankelijk van het documenttype waarvoor je hook is geregistreerd:

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

De response bevat het XML-document (standaard in het originele formaat). Wil je het document in een ander formaat ontvangen? Gebruik de targetDocumentTypeId-parameter (werkt op beide endpoints):

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

De PSB transformeert het document automatisch naar het opgegeven formaat voordat het wordt geretourneerd.

Of er een PDF beschikbaar is, hangt af van het bron-document:

On-demand PDF-generatie vanuit een gestructureerd UBL-document is op de PSB nog niet beschikbaar; alleen de embedded PDF wordt geretourneerd als die aanwezig is. Dit staat op de roadmap. Tot die tijd is de aanbeveling dat de afzender de PDF embed in UBL of dat de afnemer de PDF zelf rendert uit de gestructureerde data.

De PSB bewaart ontvangen documenten volgens dit schema:

Het is aan te raden om documenten direct na ontvangst op te halen en in je eigen systeem op te slaan. Vertrouw niet op de PSB als langetermijnopslag.

Na verwerking kun je het document handmatig verwijderen:

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

Dit verwijdert het document definitief uit de PSB. De audittrail blijft beschikbaar.

Na ontvangst kun je de verwerkingsstatus van een inkoopfactuur bijwerken. Dit is met name relevant als je Invoice Responses (statusberichten) wilt versturen naar de afzender. Lees hiervoor het artikel Invoice Response verzenden.

De PSB stuurt automatisch een MLS-bericht (Message Level Status) terug naar de verzendende partij na ontvangst van een document. Dit bevestigt dat het document is ontvangen en afgeleverd. Als integrator hoef je hier niets voor te configureren: de PSB regelt dit volledig. Als je zelf documenten verstuurt, ontvang je MLS-feedback via het webhook-topic MessageLevelStatusReceived. Zie Webhooks instellen voor de configuratie.

Als je geen webhooks kunt configureren (bijvoorbeeld in een on-premise omgeving zonder inkomend internetverkeer), kun je facturen ook ophalen via polling:

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

Dit endpoint retourneert een lijst van beschikbare inkoopfacturen. Webhooks zijn echter altijd de voorkeursmethode vanwege de real-time verwerking en lagere belasting op de API.

Let op: Overweeg bij on-premise integraties ook de reverse webhook (HTTPS inbound hook), waarmee de PSB documenten pusht zonder dat jouw systeem direct bereikbaar hoeft te zijn vanuit het internet.

• Verwerk idempotent: de PSB kan in uitzonderlijke gevallen een event meerdere keren bezorgen. Controleer aan jouw kant of je een document al hebt verwerkt voordat je het opnieuw importeert.
• Dedupliceer op documentinhoud: gebruik Invoice/ID + sender partyId + issueDate uit het opgehaalde XML als deduplicatie-sleutel. Dit vangt ook duplicaten op die via een ander netwerk dan de PSB binnenkomen.
• Download direct: haal documenten zo snel mogelijk op na de webhook-notificatie. De 90-dagenretentie is een vangnet, geen opslagstrategie.
• Log het documentId: bewaar het PSB documentId in je eigen systeem voor tracering en eventuele troubleshooting.
• Formaat converteren: als je een specifiek XML-formaat nodig hebt, gebruik dan targetDocumentTypeId bij het downloaden in plaats van zelf te converteren.
• Webhook-retries: als je endpoint tijdelijk onbereikbaar is, probeert de PSB de notificatie tot 5 dagen opnieuw te bezorgen. Langdurige uitval? Gebruik batch hooks als fallback om gemiste documenten alsnog op te halen.

Bekijk de volledige PurchaseInvoice-endpoints en response-modellen op psb.econnect.eu.