Self-billing factuur ontvangen via de API

Self-billing documenten ontvangen: ERS-inkomend, SMP-capabilities, btw pass-through en verwerkingsflow.

Als leverancier ontvang je self-billing facturen van je kopers (ERS inkomend). De koper stelt de factuur op namens jou en stuurt deze via het Peppol-netwerk. Functioneel is het een inkomende Peppol-factuur; juridisch en inhoudelijk is het self-billing. In je eigen administratie verwerk je die als verkoopfactuur, niet als inkoopfactuur. Dit artikel beschrijft welke registratie je nodig hebt en hoe je de ontvangen documenten verwerkt.

Hoe komen self-billing facturen binnen?

Self-billing facturen gebruiken dezelfde receive-flow als andere inkomende Peppol-facturen. Er is geen aparte transportstroom. De PSB stuurt een webhook-notificatie en je downloadt het document via de download-API. Het verschil zit in de herkenning (InvoiceTypeCode / profiel), de SMP-registratie per variant en hoe je ERP het document boekt.

De ontvangstflow:

  1. De koper verstuurt een self-billing factuur (InvoiceTypeCode 389) of self-billing creditnota (261) 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 het document en boekt het als verkoopfactuur in je administratie
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 andere inkomende Peppol-facturen. Beide routes dekken self-billing:

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

Of via het generic-downloadpad:

GET /api/v1/{partyId}/generic/{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 BIS Self-Billing 3.0 herken je het document ook aan de eigen CustomizationID en ProfileID (zie Self-billing overzicht).

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

BTW pass-through

Bedragen, percentages en btw-categorieën worden overgenomen zoals ze in de UBL zijn aangeleverd. De PSB berekent of wijzigt btw niet. Btw-logica en controles horen in het ontvangende ERP- of boekhoudsysteem.

Integratiemapping: boeken als verkoopfactuur

De ontvangende applicatie moet self-billing herkennen (onder meer InvoiceTypeCode 389/261, en bij BIS ook CustomizationID/ProfileID) en het document correct als verkoopfactuur boeken. Boek het niet als inkoopfactuur: jij bent de leverancier die de factuur ontvangt die de koper namens jou 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 of GET /api/v1/{partyId}/generic/{documentId}/download. 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, en boek het document als verkoopfactuur.

Wijzigt de PSB de btw op een ontvangen self-billing factuur?

Nee. De PSB neemt btw-bedragen, percentages en categorieën over uit de UBL (pass-through). Berekening en controle van btw gebeurt in je eigen ERP of boekhoudsysteem.


Of je als leverancier NLCIUS of BIS Self-Billing 3.0 ontvangt, hangt af van wat de koper verstuurt. Alleen bij BIS Self-Billing 3.0 is extra SMP-registratie met capability selfbilling nodig; bij de NLCIUS-variant volstaat je bestaande ontvangstregistratie. Bij twijfel: registreer voor beide.

PSB-tutorials: self-billing verzenden, self-billing ontvangen, voorbeeld UBL BIS Self-Billing.

Bekijk de API-documentatie