Invoice Response ontvangen via hooks

Wanneer een ontvanger de status van jouw factuur terugkoppelt via een Invoice Response (statusbericht), stuurt de PSB een notificatie naar je webhook. Zo weet je als verzender of een factuur is goedgekeurd, afgekeurd, of dat de ontvanger aanvullende informatie nodig heeft. Dit artikel beschrijft hoe je die notificaties opvangt en verwerkt.

Hoe werkt het?

Na het versturen van een factuur kan de ontvanger via het Peppol-netwerk statusberichten terugsturen. De PSB koppelt elk binnengekomen Invoice Response automatisch aan je oorspronkelijke factuur en publiceert een webhook-event.

De flow:

Jij verstuurt een factuur via de PSB
De ontvanger verwerkt de factuur en stuurt een Invoice Response
De PSB ontvangt het response-bericht en koppelt het aan jouw factuur
Je webhook ontvangt een InvoiceResponseReceived-event

Webhook configureren

Registreer een hook op het topic InvoiceResponseReceived:

POST /api/v1/hook

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

De webhook-payload bevat het documentId van de oorspronkelijke factuur en het responseDocumentId van het Invoice Response-bericht.

Invoice Response downloaden

Haal het volledige Invoice Response-bericht op via de API:

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

Het bericht bevat de statuscode, eventuele clarification codes en een optionele toelichting van de ontvanger.

Statuscodes interpreteren

De ontvangen statuscode geeft aan in welk stadium de factuur zich bij de ontvanger bevindt:

Code

Naam

Wat betekent dit voor jou als verzender?

Acknowledge

Factuur is ontvangen en leesbaar

In Process

Factuur wordt verwerkt, nog geen oordeel

Under Query

De ontvanger heeft vragen, actie nodig

Rejected

Factuur is afgewezen, corrigeer en verstuur opnieuw

Accepted

Factuur is goedgekeurd, betaling volgt

Fully Paid

Factuur is betaald

Bij de statussen UQ en RE is het belangrijk om de meegestuurde Reason code en Action code te lezen. Deze geven aan wat er mis is en welke actie de ontvanger van je verwacht. Zie het artikel Invoice Response verzenden voor een overzicht van alle Reason- en Action codes.

Vereisten voor het ontvangen van responses

Om Invoice Responses te kunnen ontvangen als verzender moet je organisatie geregistreerd zijn in de Peppol SMP met de invoiceResponse-capability. Zonder deze registratie kan het Access Point van de ontvanger het response-bericht niet afleveren.

Controleer en activeer de capability:

PUT /api/v1/peppol/config HTTP/1.1
Host: psb.econnect.eu
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "invoiceResponse": {
    "state": "on"
  }
}

Verwerking in je eigen systeem

Enkele aanbevelingen voor het verwerken van Invoice Responses:

Koppel aan de factuur: gebruik het documentId uit de payload om de response te koppelen aan de juiste factuur in je eigen administratie.
Toon de status: maak de factuurstatus zichtbaar voor je gebruikers. Een "goedgekeurd" of "afgekeurd"-indicator voorkomt onnodige nabelvragen.
Reageer op afwijzingen: bij status RE is het gebruikelijk om de factuur te corrigeren en een nieuwe versie te sturen. Let op: gebruik hiervoor een nieuw X-EConnect-DocumentId, want het gaat om een nieuw document.
Bewaar de audit trail: sla elke ontvangen Invoice Response op als onderdeel van de factuurhistorie.

Veelgestelde vragen

Welke webhook en velden gebruik ik om een Invoice Response binnen te krijgen?

Registreer een hook op het topic InvoiceResponseReceived. De payload bevat het documentId van je oorspronkelijke verzonden factuur en het responseDocumentId van het statusbericht. Zo koppel je het antwoord in je systeem aan de juiste verkoopfactuur.

Hoe haal ik het volledige Invoice Response-XML op?

Gebruik GET /api/v1/{partyId}/salesInvoice/{documentId}/response/{responseDocumentId}/download met het documentId van de factuur en het responseDocumentId uit de webhook. In het bericht staan de statuscode en eventuele clarification-informatie van de ontvanger.

Wat moet ik doen bij status RE en waarom een nieuw X-EConnect-DocumentId?

Bij RE (Rejected) moet je de factuur corrigeren en opnieuw versturen; de Reason- en Action codes geven aan wat er mis is. Voor die nieuwe versie gebruik je een nieuw X-EConnect-DocumentId, omdat het om een nieuw document gaat en idempotency per documentId werkt.

Invoice Responses zijn optioneel in het Peppol-netwerk. Niet elke ontvanger stuurt ze. Maar wanneer ze wel worden gebruikt, bieden ze waardevolle inzichten in het factuurproces.

Probeer het in de API

Gerelateerd