Peppol-integratie voor uw app: e-facturen verzenden via KRONENWERK

U integreert Peppol-verzending in uw applicatie via KRONENWERK door het factuurconcept aan te maken met POST /invoices/drafts, de factuur in het product te laten uitreiken en verzenden, en invoice.issued op uw webhook-endpoint te ontvangen. KRONENWERK is geen Peppol Access Point. Het verzendt en ontvangt via Peppol door middel van een geaccrediteerde toegangspuntaanbieder (Storecove) zodra de onderneming is verbonden in Instellingen → Verzending, en productieverzending hangt af van dat account en de configuratie ervan. De functie is ONDERSTEUND MET BEPERKINGEN.

Wat Peppol is, voor een integrator

Peppol is een vierhoeks-afleveringsnetwerk: uw onderneming (hoek 1) geeft een document aan haar toegangspunt (hoek 2), dat via het SML/SMP-register het toegangspunt van de ontvanger (hoek 3) opzoekt en aflevert bij de ontvangende onderneming (hoek 4). Documenten zijn gestructureerde UBL volgens Peppol BIS Billing 3.0, een implementatie van EN 16931. Deelnemers worden geadresseerd met identificatiecodes zoals een btw-nummer onder een schema uit de codelijsten van OpenPeppol, die in het netwerk verplicht zijn en regelmatig worden bijgewerkt (v9.7 op 2 juli 2026). Het mechanisme wordt uitgelegd op Peppol, de identificatiecodes op Peppol-identificatiecodes, en de praktische kant op verzenden en ontvangen via Peppol.

Voor een ontwikkelaar is het gevolg eenvoudig: u praat nooit rechtstreeks met het netwerk. Iemands toegangspunt doet dat, en de vraag is wiens. Een eigen toegangspunt bouwen betekent OpenPeppol-lidmaatschap, accreditatie, een AS4-gateway en SMP-publicatie. KRONENWERK gebruiken betekent dat het toegangspunt dat van Storecove is, dat de verbinding aan de onderneming toebehoort, en dat uw code alleen met de KRONENWERK-API praat.

De flow: concept, uitreiken, verzenden, webhook

1. Uw app maakt de klant aan met POST /customers. Geef de klant een land en een btw-identificatienummer: de Peppol-deelnemersidentificatie van een Belgische ontvanger wordt afgeleid van zijn ondernemings- of btw-nummer, en een klant zonder zo'n nummer kan op het netwerk niet worden geadresseerd.
2. Uw app start het concept met POST /invoices/drafts en een Idempotency-Key. Het antwoord is een concept in de toestand DRAFT met het nummeringsvoorstel van de verkoper en de betalingsvoorwaarden van de klant.
3. Een persoon reikt het concept uit in het product. KRONENWERK berekent het fiscale oordeel, controleert het btw-identificatienummer via VIES, genereert Peppol BIS Billing 3.0 UBL voor een Belgische verkoper, valideert die en verbruikt het nummer. Op dat moment wordt invoice.issued in de wachtrij gezet voor uw endpoint.
4. De factuur wordt vanuit het product verzonden. Verzending is een afzonderlijke, geauditeerde handeling op de uitgereikte factuur, geen neveneffect van het uitreiken: de landenmodule benoemt het kanaal (Peppol voor België), de verbonden toegangspuntaanbieder draagt het document, en het resultaat wordt bij de factuur vastgelegd. Als het resultaat onbekend is — een time-out nadat het verzoek is vertrokken — weigert het product opnieuw te verzenden totdat een reconciliatieaanroep aan de andere kant heeft gevraagd of die het document heeft. Een onbekend resultaat opnieuw proberen is hoe één factuur er twee wordt.
5. Uw app ontvangt invoice.issued, verifieert KRONENWERK-Signature, dedupliceert op KRONENWERK-Event-Id, en slaat invoiceId en number op. Later volgen invoice.paid of invoice.cancelled.

Wat een ontwikkelaar moet configureren

Let op wat niet op de lijst staat: geen SMP, geen AS4-certificaat, geen OpenPeppol-lidmaatschap aan uw kant. Let ook op wat de API niet kan: ze kan de onderneming niet met het netwerk verbinden, kan niet verzenden en kan het verzendlogboek niet lezen. Dat zijn instellingen en handelingen die een persoon in het product uitvoert.

Voorbeeldverzoeken

curl -X POST https://kronenwerk.org/api/extern/v1/customers \
  -H "Authorization: Bearer greif_live_…" \
  -H "Idempotency-Key: crm-account-88213" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Voorbeeld BV",
    "street": "Rue de l'"'"'Exemple 12",
    "postalCode": "1000",
    "city": "Bruxelles",
    "country": "BE",
    "vatId": "BE0123456789",
    "email": "invoices@example.be"
  }'

curl -X POST https://kronenwerk.org/api/extern/v1/invoices/drafts \
  -H "Authorization: Bearer greif_live_…" \
  -H "Idempotency-Key: crm-account-88213-2026-09" \
  -H "Content-Type: application/json" \
  -d '{ "customerId": "3f2b…" }'

Het klantantwoord bevat het partnernummer uit de eigen reeks van de onderneming (bijvoorbeeld K-0042) en de velden zoals opgeslagen: id, number, name, contact, email, phone, street, postalCode, city, country, vatId, currency, customer, supplier, archived, createdAt. Naam, straat, postcode en plaats zijn verplicht omdat EN 16931 een adres in onderdelen draagt, en een klant zonder straat is er een aan wie geen document kan worden geadresseerd. De factuur-API wordt volledig beschreven op de pagina over de factuur-API.

Ontvangen via Peppol

In België geldt de verplichting om gestructureerde facturen via Peppol te ontvangen voor btw-geregistreerde ondernemingen zonder drempel, zodat een verbinding die alleen verzendt de helft van de verplichting zou zijn. Zodra de onderneming is verbonden, komen inkomende Peppol-documenten aan bij de toegangspuntaanbieder, worden ze aan KRONENWERK overgedragen, ingelezen als inkoopfacturen en gevalideerd. Uw integratie verneemt ze via de webhook purchase.recorded, die purchaseId, kind, documentNumber, supplierName, supplierId, documentDate, dueDate, currency, netMinor, taxMinor en grossMinor draagt. Het inkomende document zelf wordt niet op de API blootgesteld. De Belgische context staat op de België-hub en de landenpagina België.

Alternatieven, eerlijk vergeleken

Als uw vereiste volledig geautomatiseerde verzending is zonder dat een persoon uitreikt, dan is de API van KRONENWERK dat vandaag niet, en is een rechtstreeks contract met een aanbieder de eerlijke aanbeveling. De Peppol-gids voor ontwikkelaars behandelt wat u in dat geval zou moeten bouwen; Peppol versus nationale netwerken legt uit waar Peppol het kanaal is en waar een nationaal systeem (KSeF, Franse plateformes agréées) dat is.

Hoe KRONENWERK dit afhandelt

ONDERSTEUND MET BEPERKINGEN KRONENWERK genereert bij uitreiking Peppol BIS Billing 3.0 UBL voor Belgische verkopers en verzendt en ontvangt via Peppol door middel van een geaccrediteerde toegangspuntaanbieder (Storecove) zodra de onderneming is verbonden in Instellingen → Verzending. KRONENWERK is zelf geen geaccrediteerd of gecertificeerd Peppol Access Point. Productieverzending hangt af van het Storecove-account en de configuratie van de onderneming, en verzending is een handeling die een persoon na het uitreiken in het product uitvoert. Het aandeel van de API is de klant, het concept, het teruglezen en de webhooks, op het Enterprise-plan. Het Peppol-kanaal is aangesloten voor Belgische verkopers; voor Duitse verkopers produceert het product XRechnung of ZUGFeRD voor e-mail of download en benoemt het geen verzendkanaal, omdat de Duitse wet er geen benoemt. Franse verzending is een ander mechanisme en is NOG NIET GEREED — zie Franse platforms. Productdetails: e-facturatie.