Self-billing factuur ontvangen via de API

Self-billing documenten ontvangen: SMP-capabilities en verwerkingsflow.

Als leverancier ontvang je self-billing facturen van je kopers. De koper stelt de factuur op namens jou en stuurt deze via het Peppol-netwerk. Dit artikel beschrijft welke registratie je nodig hebt en hoe je de ontvangen documenten verwerkt.

Hoe komen self-billing facturen binnen?

Self-billing facturen worden op dezelfde manier afgeleverd als reguliere inkoopfacturen. De PSB stuurt een webhook-notificatie en je kunt het document downloaden via het PurchaseInvoice-endpoint. Het verschil zit in de registratie en het documenttype.

De ontvangstflow:

  1. De koper verstuurt een self-billing factuur (InvoiceTypeCode 389) via de PSB
  2. Het Peppol-netwerk routeert het document naar jouw Access Point
  3. De PSB stuurt een InvoiceReceived-event naar je webhook
  4. Je downloadt en verwerkt het document
SMP-registratie

Om self-billing facturen te kunnen ontvangen moet je organisatie geregistreerd zijn in de Peppol SMP. Welke registratie je nodig hebt, hangt af van de variant:

NLCIUS-variant

Als je al geregistreerd bent voor het ontvangen van reguliere NLCIUS-facturen, hoef je niets extra's te doen. Self-billing facturen met InvoiceTypeCode 389 worden afgeleverd via hetzelfde profiel. De PSB herkent automatisch het documenttype.

BIS Self-Billing 3.0

Voor het BIS Self-Billing 3.0-profiel is een aparte registratie nodig. Dit profiel heeft een eigen CustomizationID en ProfileID, en vereist een specifieke SMP-configuratie.

Configureer de self-billing capability via de Peppol config API:

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

{
  "selfBilling": {
    "state": "on"
  }
}

Zonder deze registratie kunnen kopers die het BIS Self-Billing 3.0-profiel gebruiken je niet vinden via een Peppol SMP-lookup.

Webhook configureren

Gebruik hetzelfde topic als voor reguliere inkoopfacturen:

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

Self-billing facturen komen binnen als InvoiceReceived-events. Je kunt ze onderscheiden van reguliere facturen door het InvoiceTypeCode in het XML-document te controleren: 389 voor een self-billing factuur, 261 voor een self-billing creditnota.

Document downloaden en verwerken

Download het document op dezelfde manier als een reguliere inkoopfactuur:

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

Optioneel kun je met targetDocumentTypeId het document in een ander formaat opvragen als je eigen systeem dat vereist.

Self-billing factuur herkennen

Na het downloaden kun je in het XML-document controleren of het een self-billing factuur betreft:

<!-- InvoiceTypeCode 389 = self-billing factuur -->
<InvoiceTypeCode>389</InvoiceTypeCode>

<!-- InvoiceTypeCode 261 = self-billing creditnota -->
<InvoiceTypeCode>261</InvoiceTypeCode>

Bij een self-billing factuur is de AccountingSupplierParty jouw organisatie (de leverancier), terwijl de AccountingCustomerParty de koper is die de factuur heeft opgesteld.

Invoice Response terugsturen

Na ontvangst kun je een Invoice Response terugsturen naar de koper om de verwerking te bevestigen of de factuur af te wijzen. De flow is identiek aan die voor reguliere facturen:

POST /api/v1/{partyId}/purchaseInvoice/{documentId}/response HTTP/1.1
Host: psb.econnect.eu
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "status": "AP",
  "clarificationCode": "NON",
  "actionCode": "NOA"
}

Zie Invoice Response verzenden voor het volledige overzicht van statuscodes en clarification codes.

Retentie

De retentieregels voor self-billing documenten zijn dezelfde als voor reguliere inkoopfacturen: 90 dagen bewaard na ontvangst, 7 dagen na download. Haal documenten tijdig op en sla ze op in je eigen systeem.

Veelgestelde vragen
Heb ik aparte webhooks nodig voor self-billing?

Nee, self-billing gebruikt hetzelfde topic als reguliere inkoopfacturen: InvoiceReceived. Je onderscheidt self-billing in je verwerking door in het XML het InvoiceTypeCode te lezen (389 voor factuur, 261 voor creditnota).

Welke SMP-registratie heb ik voor NLCIUS versus BIS Self-Billing 3.0?

Ontvang je al NLCIUS-inkoopfacturen, dan volstaat die registratie ook voor NLCIUS-self-billing met code 389 of 261. Voor BIS Self-Billing 3.0 is een aparte capability nodig; zet selfBilling.state op on via PUT /api/v1/peppol/config, anders vinden kopers je niet voor dat profiel in de SMP.

Hoe download ik een binnengekomen self-billing factuur en kan ik het formaat wijzigen?

Gebruik GET /api/v1/{partyId}/purchaseInvoice/{documentId}/download zoals bij elke inkoopfactuur. Met de queryparameter targetDocumentTypeId kun je een ander doelformaat opvragen als je bronsysteem dat nodig heeft. Controleer na download in het XML welke partij leverancier en welke koper is volgens AccountingSupplierParty en AccountingCustomerParty.


Of je als leverancier NLCIUS of BIS Self-Billing 3.0 ontvangt, hangt af van wat de koper verstuurt. Zorg ervoor dat je de juiste SMP-registratie hebt voor de varianten die je kopers gebruiken. Bij twijfel: registreer voor beide.

Bekijk de API-documentatie

Gerelateerd