Self-billing factuur verzenden via API

Als koper kun je via de PSB API een self-billing factuur opstellen en verzenden namens je leverancier. Dit artikel beschrijft stap voor stap hoe je dat doet voor beide varianten: de NLCIUS-variant en Peppol BIS Self-Billing 3.0.

Vooraf: capabilities controleren

Controleer altijd eerst of de leverancier het gewenste self-billing formaat kan ontvangen:

GET /api/v1/queryRecipientParty?identifier={schemeID}:{leverancierKvK} HTTP/1.1
Host: psb.econnect.eu
Authorization: Bearer {access_token}

Zoek in de response naar het ondersteunde profiel. Bij NLCIUS is dat het standaard factuurprofiel; bij BIS Self-Billing 3.0 het specifieke self-billing profiel.

Variant 1: NLCIUS (vereenvoudigd)

Dit is de eenvoudigste manier om een self-billing factuur te versturen. Je gebruikt dezelfde CustomizationID en ProfileID als bij een reguliere NLCIUS-factuur, maar wijzigt het InvoiceTypeCode naar 389:

<Invoice xmlns="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2">
  <CustomizationID>urn:cen.eu:en16931:2017#compliant#urn:fdc:nen.nl:nlcius:v1.0</CustomizationID>
  <ProfileID>urn:fdc:peppol.eu:2017:poacc:billing:01:1.0</ProfileID>
  <ID>SB-2026-001</ID>
  <IssueDate>2026-03-05</IssueDate>
  <InvoiceTypeCode>389</InvoiceTypeCode>
  <!-- AccountingSupplierParty = de leverancier (ontvanger van de factuur) -->
  <AccountingSupplierParty>
    <Party>
      <EndpointID schemeID="0106">87654321</EndpointID>
      <PartyName><Name>Leverancier B.V.</Name></PartyName>
      ...
    </Party>
  </AccountingSupplierParty>
  <!-- AccountingCustomerParty = de koper (opsteller van de factuur) -->
  <AccountingCustomerParty>
    <Party>
      <EndpointID schemeID="0106">12345678</EndpointID>
      <PartyName><Name>Koper B.V.</Name></PartyName>
      ...
    </Party>
  </AccountingCustomerParty>
  ...
</Invoice>

Verzend het document via het SalesInvoice-endpoint:

POST /api/v1/{partyId}/salesInvoice/send HTTP/1.1
Host: psb.econnect.eu
Authorization: Bearer {access_token}
Content-Type: application/xml
X-EConnect-DocumentId: {uuid}

De PSB herkent automatisch het InvoiceTypeCode 389 en routeert het document als self-billing factuur naar de leverancier.

Tip: Voor een self-billing creditnota gebruik je InvoiceTypeCode 261 in plaats van 389.

Variant 2: BIS Self-Billing 3.0

Bij deze variant gebruik je het specifieke self-billing profiel met eigen identifiers:

<Invoice xmlns="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2">
  <CustomizationID>urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:selfbilling:3.0</CustomizationID>
  <ProfileID>urn:fdc:peppol.eu:2017:poacc:selfbilling:3.0</ProfileID>
  <ID>SB-2026-001</ID>
  <IssueDate>2026-03-05</IssueDate>
  <InvoiceTypeCode>389</InvoiceTypeCode>
  <AccountingSupplierParty>
    <Party>
      <EndpointID schemeID="0106">87654321</EndpointID>
      <PartyName><Name>Leverancier B.V.</Name></PartyName>
      ...
    </Party>
  </AccountingSupplierParty>
  <AccountingCustomerParty>
    <Party>
      <EndpointID schemeID="0106">12345678</EndpointID>
      <PartyName><Name>Koper B.V.</Name></PartyName>
      ...
    </Party>
  </AccountingCustomerParty>
  ...
</Invoice>

Verzend BIS Self-Billing documenten via het Generic endpoint:

POST /api/v1/{partyId}/generic/send HTTP/1.1
Host: psb.econnect.eu
Authorization: Bearer {access_token}
Content-Type: application/xml
X-EConnect-DocumentId: {uuid}

De PSB detecteert het self-billing profiel op basis van de CustomizationID en routeert het document naar de leverancier, mits die geregistreerd is voor het BIS Self-Billing 3.0-profiel.

Verschil in rollen

Let op het verschil in partijrollen bij self-billing. Dit is een veelvoorkomende bron van verwarring:

UBL-element

Bij reguliere factuur

Bij self-billing factuur

AccountingSupplierParty

De verzender (leverancier)

De ontvanger (leverancier)

AccountingCustomerParty

De ontvanger (koper)

De verzender (koper)

De AccountingSupplierParty is altijd de leverancier, ook als de koper de factuur opstelt. De koper vult zijn eigen gegevens in bij AccountingCustomerParty.

Idempotency

Gebruik altijd de X-EConnect-DocumentId-header om dubbele verzending te voorkomen. De regels zijn identiek aan die voor reguliere facturen: minimaal 6 tekens, bij voorkeur een UUID, nooit het factuurnummer. Lees meer in het artikel Idempotency.

Foutafhandeling

Veelvoorkomende fouten bij self-billing:

Fout

Oorzaak

Oplossing

Validatiefout

InvoiceTypeCode ontbreekt of is onjuist

Controleer dat InvoiceTypeCode 389 of 261 is

Ontvanger niet gevonden

Leverancier niet geregistreerd voor self-billing

Controleer via queryRecipientParty; bij BIS Self-Billing moet de leverancier apart geregistreerd zijn

409 Conflict

Document met dit ID is al verwerkt

Geen actie nodig

HTTP 500 bij grote payload

Request overschrijdt de 24 MB webserver-limiet (inclusief overhead)

Verklein embedded PDF-bijlagen; houd rekening met ~33% base64-overhead

Webhook-notificaties

Na verzending ontvang je dezelfde webhook-events als bij reguliere facturen:

InvoiceSent bij succesvolle aflevering
InvoiceSentRetry bij een nieuwe poging (max 8 retries)
InvoiceSentError als aflevering definitief mislukt

Veelgestelde vragen

Welk endpoint gebruik ik voor NLCIUS self-billing versus BIS Self-Billing 3.0?

Voor NLCIUS met InvoiceTypeCode 389 of 261 en de gebruikelijke NLCIUS-profielen stuur je naar POST /api/v1/{partyId}/salesInvoice/send met XML-body en optioneel X-EConnect-DocumentId. Voor BIS Self-Billing 3.0 met de bijbehorende CustomizationID en ProfileID gebruik je POST /api/v1/{partyId}/generic/send; de PSB herkent het profiel uit het document.

Hoe zitten de rollen van leverancier en koper in het UBL?

AccountingSupplierParty is altijd de leverancier (in self-billing de partij die de factuur "ontvangt"), en AccountingCustomerParty is de koper die het document namens de leverancier opstelt en verzendt. Die verwisseling ten opzichte van een normale verkoopfactuur is een veelvoorkomende fout bij implementatie.

Hoe voorkom ik dubbele self-billing-verzending en wat bij grote bijlagen?

Gebruik dezelfde idempotency-regels als bij reguliere facturen: stuur X-EConnect-DocumentId met een UUID, geen factuurnummer. Payloads groter dan circa 24 MB (inclusief overhead) worden door de webserver afgewezen; verklein embedded base64-PDF's of splits de aanlevering, rekening houdend met ongeveer 33% overhead door base64.

Wil je het document eerst valideren voordat je het verstuurt? Gebruik de Validate API om je self-billing factuur te controleren zonder dat deze daadwerkelijk wordt verzonden.

Probeer het in de API

Gerelateerd