Publieke API-integratie: sleutels, permissies, velden en acceptatie
Koppel een ERP of kassa aan de publieke API van OrdoGrid: sleutels en Integratie-ID, permissies, prijzen incl. btw, Peppol, veilige herhalingen en acceptatie.
- Bijgewerkt
- Inhoudsverantwoordelijke
- Integratieteam
- Voor
- Integratie-engineers · Solution architects · Financieel verantwoordelijken van een integratie
In één oogopslag
Maak per integratie één bedrijfsgebonden sleutel met de strikt nodige permissies en een stabiele Integratie-ID, koppel de velden zo dat de bedragen tot op de cent met uw bron overeenkomen (ook bij prijzen inclusief btw), controleer elke ontvanger vóór u via Peppol verstuurt, en bewijs herhalingen, afrekening en aflevering met echte facturen vóór de livegang. Er is geen sandbox: elke aanroep werkt op echte gegevens.
Voordat u begint
- Een Business-abonnement met toegang tot de publieke API
- De rol Eigenaar of Beheerder in het OrdoGrid-bedrijf waarvoor de integratie werkt
- Een ondertekende Autorisation Peppol voor het Belgische btw-nummer van het bedrijf, als de integratie via Peppol verstuurt
- Een stabiele bron-ID voor elke factuur, creditnota en betaling
- Verwachte bedragen voor representatieve gevallen, afgesproken met uw controller of accountant
Wat u bereikt
- Een sleutel met minimale permissies en een vastgelegde Integratie-ID
- Een veldkoppeling die uw bedragen tot op de cent reproduceert, afronding inbegrepen
- Een geslaagd acceptatiedossier voor herhalingen, Peppol-aflevering en afrekening
Op deze pagina
Met de publieke API van OrdoGrid (/api/v1) maakt een ERP, een kassa of een facturatiesysteem facturen, creditnota's en betalingen aan in één OrdoGrid-bedrijf en verstuurt het die via Peppol. Dit draaiboek brengt u van de sleutel tot de livegang: permissies, veldkoppeling tot op de cent, verzending via Peppol, herhalingen zonder dubbels en de tests die eerst moeten slagen.
Het is bedoeld voor integratie-engineers en voor de financieel verantwoordelijke die de bedragen goedkeurt. Elke route staat in de API-referentie, zonder login raadpleegbaar, met het OpenAPI-bestand. Het beleid voor herhalingen en incidenten in productie staat in betrouwbare integraties.
Wat de wet vereist, wat wij aanraden, wat OrdoGrid doet
Wat de wet vereist. Sinds 1 januari 2026 moeten ondernemingen die in België gevestigd zijn gestructureerde elektronische facturen uitreiken voor leveringen en diensten aan Belgische btw-plichtige zakelijke klanten, in principe in het Peppol BIS-formaat via het Peppol-netwerk (de verplichting in detail). Die gestructureerde factuur is de wettelijke factuur; een pdf-kopie is optioneel. Een creditnota die een gestructureerde factuur corrigeert, moet ook via Peppol. Kan de klant niet ontvangen, dan moet u de factuur toch uitreiken in een andere vorm, bijvoorbeeld als pdf. De FOD Financiën wijst erop dat Peppol geen dubbels herkent: die vermijden is uw taak.
Wat OrdoGrid doet. De API bouwt de UBL-XML op uit de velden die u stuurt, valideert ze vóór aflevering tegen EN 16931 en Peppol BIS Billing 3.0.21, en archiveert de exacte XML en pdf die verstuurd zijn. OrdoGrid is via een gecertificeerd toegangspunt met Peppol verbonden, en alleen bedrijven met een Belgisch (BE) btw-nummer kunnen versturen. Er is geen sandbox, geen route die een pdf in een factuur omzet en geen API-bewerking die een document e-mailt.
Wat wij aanraden. Eén sleutel per integratie, minimale permissies, een duurzame identiteit voor elke zakelijke gebeurtenis, een ontvangerscontrole vóór elke Peppol-verzending en verwachte bedragen die vóór de livegang zijn goedgekeurd.
Kies het patroon en de permissies
| Uw situatie | Belangrijkste aanroepen | Permissies (scopes) |
|---|---|---|
| ERP reikt facturen uit en verstuurt ze via Peppol | POST /api/v1/invoices, daarna POST /api/v1/peppol/invoices/{id}/send; of één aanroep naar POST /api/v1/peppol/send, met uw eigen pdf als u er een maakt | invoices:write, peppol:send, peppol:read |
| Kassa met voorschotten, latere betalingen en terugbetalingen | POST /api/v1/invoices met prepayments, daarna .../payments en .../refunds | de vorige, plus credit_notes:write en payments:write |
| Creditnota's | POST /api/v1/credit-notes, daarna POST /api/v1/peppol/credit-notes/{id}/send | credit_notes:write, peppol:send |
| Rapportering of afstemming | GET /api/v1/invoices, GET .../payments, GET /api/v1/peppol/documents | invoices:read, peppol:read |
| Leveranciersfacturen naar uw systeem | GET /api/v1/peppol/inbox, GET /api/v1/peppol/documents/{id}/xml | peppol:read |
- Een
write-permissie omvatreadop dezelfde resource en niets anders:peppol:sendomvat geenpeppol:read, dat u nodig hebt voor de ontvangerscontrole, de afleverstatus en de uitgewisselde XML. POST /api/v1/peppol/sendvraagt zowelinvoices:writealspeppol:send.prepaymentsop een nieuwe factuur vragen bovendienpayments:write, anders volgt403 INSUFFICIENT_SCOPE.- De betalingsgeschiedenis en het opzoeken van een beweging vragen
invoices:read, nietpayments:read. - De inbox raakt alleen gevuld als het bedrijf via OrdoGrid ontvangt (Réception Peppol → Activer la réception, Ontvangst activeren).
Maak de sleutel aan en noteer de Integratie-ID
- Integratie-ID
De naamruimte van een sleutel,
integration_idin de API. OrdoGrid bewaart elkeexternal_idper bedrijf, Integratie-ID en documenttype, zodat opzoekingen en de bescherming tegen dubbels alleen records zien die onder dezelfde Integratie-ID zijn aangemaakt. Ze wordt bij het aanmaken vastgelegd, kan niet worden gewijzigd en blijft behouden bij het roteren.
- Open in het profielmenu API-sleutels en klik op Sleutel aanmaken. Alleen een Eigenaar of Beheerder kan dat.
- Geef een Naam die het systeem herkenbaar maakt, bijvoorbeeld
Kassa Mechelen. - Vervang in Integratie-ID de standaardwaarde
defaultdoor een stabiele waarde zoalspos-mechelen(1 tot 80 letters, cijfers,_,.of-). - Vink alleen de Permissies uit de tabel hierboven aan. Laat Vervalt op leeg voor een sleutel zonder vervaldatum, of stem de datum af op uw rotatiebeleid.
- Klik op Sleutel aanmaken, kopieer het geheim onder Kopieer deze sleutel nu naar uw secret manager en klik op Ik heb hem bewaard. Het geheim begint met
ik_live_en wordt maar één keer getoond. - Roep
GET /api/v1/meaan en controleer naam en btw-nummer van het bedrijf,api_key.integration_id,effective_scopes, valuta, betaalmethoden enrate_limit_per_minute. Bewaar het geanonimiseerde antwoord bij uw veldkoppeling.
curl https://ordogrid.com/api/v1/me -H "Authorization: Bearer ik_live_..."
De sleutel werkt ook in de header X-Api-Key. Sessiecookies van de app werken niet op deze API, en de sleutel zelf bepaalt het bedrijf: er is dus geen bedrijfsheader en geen manier om een ander bedrijf te bereiken. De lijst API-sleutels toont de Integratie-ID na het aanmaken niet meer, en de pagina kent geen bewerkactie: om permissies te wijzigen maakt u een nieuwe sleutel met dezelfde Integratie-ID, schakelt u de connector om en trekt u daarna de oude in met Intrekken.
| Situatie | Wat OrdoGrid doet | Integratie-ID | Wat u doet |
|---|---|---|---|
| Roteren | Nieuw geheim met dezelfde naam, permissies, vervaldatum en Integratie-ID; het oude geheim stopt onmiddellijk | Behouden | Zet het nieuwe geheim meteen in gebruik |
| Intrekken, daarna Sleutel aanmaken | De oude sleutel stopt onmiddellijk | default, tenzij u ze opnieuw invult | Vul exact dezelfde Integratie-ID in |
| Badge Vervallen of Ingetrokken | Aanroepen geven 401 API_KEY_EXPIRED of 401 API_KEY_REVOKED | Blijft op de oude sleutel | Maak een nieuwe sleutel met dezelfde Integratie-ID; Roteren behoudt een verstreken vervaldatum |
Koppel elk veld expliciet
| Zakelijk gegeven | API-veld | Regel |
|---|---|---|
| Uw order-, ticket- of contractnummer | external_id | 1 tot 200 tekens; nooit hergebruikt voor een andere zakelijke gebeurtenis |
| Klant | client (inline) of client_id | Een van beide; voor Peppol vat_number en een volledig address |
| Adres | street, city, postal_code, country | Alle vier zijn verplicht. Gebruik bij voorkeur een ISO-code van twee letters, zoals BE. Bekende landnamen in Frans, Nederlands, Engels of Duits worden naar die code omgezet; een onbekende waarde wordt bij het aanmaken geweigerd met 400 INVALID_COUNTRY |
| Factuurnummer | number | Laat het weg: OrdoGrid kent het volgende nummer van de reeks van het bedrijf toe; een gebruikt nummer geeft 409 DOCUMENT_NUMBER_TAKEN |
| Bestelnummer van de klant | purchase_order | Wordt de UBL-BuyerReference |
| Betalingsreferentie | communication | Wordt de UBL-PaymentID, en de BuyerReference als er geen bestelnummer is |
| Regels | items[]: description, quantity, unit_price, vat_rate, vat_type, unit, discount | unit_price is een prijs exclusief btw |
| Prijs inclusief btw | price_basis: "gross", source_unit_price | Zie hieronder |
| Btw-regeling | items[].vat_type, per regel | standard, reverse_charge, cocontractant, intracommunity, exempt (vrijstellingsregeling voor kleine ondernemingen), exempt_art44 (vrijstelling van art. 44), zero_rated, export, margin; een andere waarde geeft UNKNOWN_VAT_TYPE, en een vat_type op documentniveau wordt geweigerd als onbekend veld |
| Geld ontvangen bij het aanmaken | prepayments[] | Alleen facturen; vraagt payments:write |
| Uw eigen pdf | pdf op POST /api/v1/peppol/send, of PUT /api/v1/invoices/{id}/pdf | Wordt byte voor byte verstuurd en moet dus dezelfde bedragen tonen als de gegevens |
| Gecrediteerde factuur (creditnota's) | credit_for_invoice_id, of credit_for_invoice_number voor een factuur die buiten OrdoGrid is uitgereikt | Verplicht bij POST /api/v1/credit-notes; koppelt de creditnota aan de factuur die ze corrigeert |
Omdat de BuyerReference terugvalt op de betalingsreferentie en daarna op het factuurnummer, is de Peppol-regel die een kopers- of orderreferentie vereist (PEPPOL-EN16931-R003) altijd vervuld; stuur toch het bestelnummer van de klant mee als u het hebt. De API kiest de btw-regeling niet: dat doet uw bronsysteem of uw accountant, volgens de btw-regelingen op facturen.
- Stuur alleen gekoppelde velden. Onbekende velden, ook binnen
client,addressenitems, worden geweigerd met een400die ze noemt: een200of201betekent dus dat alles wat u stuurde, is toegepast. - Bedragen zijn decimale strings. EUR, USD en GBP hebben twee decimalen, JPY geen. Te veel decimalen op een beweging worden geweigerd (
INVALID_AMOUNT_PRECISION), nooit afgekapt. Eenheidsprijzen en hoeveelheden behouden hun precisie. - Tijdstippen hebben een tijdzone.
occurred_atvraagt een ISO 8601-offset, zoals2026-10-02T10:15:00+02:00, anders volgtINVALID_OCCURRENCE_TIME. België staat tot 25 oktober 2026 op UTC+2, daarna op UTC+1. Antwoorden schrijven elk tijdstip in UTC, met milliseconden enZ: deze betaling komt terug als2026-10-02T08:15:00.000Z. Zet om naar lokale tijd voor weergave; dagen (issue_date,due_date) blijvenJJJJ-MM-DD. - Geen valutaomrekening. Een beweging moet in de valuta van de factuur staan (
CURRENCY_MISMATCH). De Belgische btw-regels vragen het btw-totaal in euro, ook op een factuur in een andere valuta: spreek de aanpak af met uw accountant voor u zulke facturen automatiseert. - Een betaling is een beweging, geen label. Een betaalde status zonder bijbehorende beweging wordt geweigerd met
PAYMENT_MOVEMENT_REQUIRED.
Prijzen inclusief btw: stuur de prijs die de klant zag
unit_price is altijd een nettoprijs, en prices_include_vat verandert alleen de weergave van de prijzen. Een kassa die "unit_price": "12.50" stuurt met "prices_include_vat": true, rekent dus € 12,50 plus 21 % btw aan.
Stuur in de plaats "price_basis": "gross" en "source_unit_price": "12.50"; unit_price is dan een plaatshouder die de bron niet overschrijft. OrdoGrid berekent het nettobedrag van elke regel als hoeveelheid × prijs inclusief btw ÷ (1 + btw-tarief), afgerond op de cent, en daarna de btw één keer per tarief op het nettototaal. Het verschil tussen uw totaal inclusief btw en netto plus btw is totals.rounding, dat via Peppol als afrondingsbedrag (BT-114) meegaat. totals.gross blijft netto plus btw; totals.payable is wat de klant verschuldigd is vóór voorschotten. Vaste kortingen nemen amount_basis: "net" (standaard) of "gross". Antwoorden splitsen de kortingen exclusief btw: totals.line_discounts, totals.global_discount en hun som totals.discounts, het kortingstotaal op de pdf; global_discount geeft de ingevoerde globale korting terug. Op regels aan 0 % (verlegging van heffing, intracommunautaire leveringen, uitvoer) is de brutoprijs gelijk aan de nettoprijs: stuur daar nettoprijzen. Details: prijzen inclusief btw en afronding.
Versturen via Peppol: controleren, versturen, resultaat lezen
Een gebruiker moet eerst de Autorisation Peppol (Peppol-machtiging) voor het btw-nummer van het bedrijf ondertekenen in het menu Peppol (Peppol instellen in OrdoGrid); anders geven verzendingen 403 PEPPOL_APPROVAL_REQUIRED. Verzendingen tellen mee voor het maandelijkse Peppol-quotum van het abonnement (403 PEPPOL_LIMIT_REACHED, met teller en limiet in details). Ontvangen via OrdoGrid is niet nodig om te versturen, maar de Belgische wet verplicht uw bedrijf ook Peppol-facturen te kunnen ontvangen, via OrdoGrid of een andere dienstverlener.
- Controleer de ontvanger.
GET /api/v1/peppol/participants/BE0123456749geeftregistereden, als die gevonden is, eenparticipant_idzoals0208:0123456749. Belgische bedrijven zijn ingeschreven onder hun ondernemingsnummer (schema 0208): vraag uw klanten geen aparte Peppol-ID.registered: falsebetekent dat geen inschrijving kon worden bevestigd, omdat de klant er niet op staat of omdat de opzoeking mislukte; herhaal ze en zoek zo nodig0208:gevolgd door het ondernemingsnummer op lookup.peppol.org. - Verstuur met
POST /api/v1/peppol/invoices/{id}/send. Optioneel:include_pdf(standaardtrue),attachments(nieuwe bestanden in base64),attachment_ids(bestanden die al bij de factuur horen). - Bewaar
peppol_document_iduit het antwoord, naastdocument_identransmission_state. - Lees het resultaat met
GET /api/v1/peppol/invoices/{id}/status(status,lifecycle,transmission_state). In de app verschijnt het document onder Peppol → Outbox, waar de badge Traité (Verwerkt) aflevering op het netwerk betekent, geen aanvaarding. De meeste documenten komen binnen enkele minuten tot een paar uur aan; duurt het langer dan één werkdag, neem dan contact op met de support van OrdoGrid. - Archiveer de uitgewisselde UBL met
GET /api/v1/peppol/documents/{peppol_document_id}/xmlen de verstuurde pdf met.../pdf. De factuur-ID werkt daar niet.
Staat de klant niet op Peppol, maak de factuur dan met POST /api/v1/invoices, haal de pdf op met GET /api/v1/invoices/{id}/pdf en bezorg ze via uw eigen kanaal, of laat een gebruiker ze in de app versturen met Envoyer (Verzenden). Kan de klant later ontvangen, verstuur oude facturen dan niet opnieuw via Peppol; zie klant niet op Peppol.
| Route | Gebruik | Let op |
|---|---|---|
POST /api/v1/peppol/send | Aanmaken en versturen in één aanroep | "send": false maakt een echte genummerde factuur aan zonder ze te versturen, en vereist toch de machtiging en resterend quotum |
POST /api/v1/peppol/invoices/{id}/send | Een bestaande factuur versturen | Een creditnota-ID geeft 404 |
POST /api/v1/peppol/credit-notes/{id}/send | Een creditnota versturen | Vertrekt als UBL CreditNote (type 381); een factuur-ID geeft 404 |
| Offertes, ontvangstbewijzen | Geen | Geen Peppol-documenten |
Peppol BIS aanvaardt zes soorten bijlagen: pdf, PNG, JPEG, CSV, XLSX en ODS, en de FOD Financiën stelt dat bijlagen met de factuur meereizen, niet apart per e-mail. Neem de attachment_ids uit attachments[] van GET /api/v1/invoices/{id}; laat het veld weg om alle bestanden mee te sturen, of stuur [] om geen enkel bestand mee te sturen. Een ID die met niets overeenkomt, wordt zonder melding genegeerd.
Maak herhalingen veilig
| Mechanisme | Bereik | Looptijd | Identieke herhaling | Andere inhoud |
|---|---|---|---|---|
Header Idempotency-Key | Eén API-sleutel; de POST-bewerkingen die hem documenteren | 24 uur | Oorspronkelijk antwoord, header Idempotent-Replay: true | 409 IDEMPOTENCY_KEY_REUSED |
external_id op facturen en creditnota's | Bedrijf, Integratie-ID, documenttype | Vervalt niet; overleeft rotatie | Eerste volledige antwoord | 409 EXTERNAL_ID_REUSED |
external_id op voorschotten, betalingen, terugbetalingen | Bedrijf en Integratie-ID, over alle facturen heen | Vervalt niet; overleeft rotatie | Oorspronkelijke beweging, 200, "replayed": true | 409 EXTERNAL_ID_REUSED |
Gebruik ze allebei. PATCH, PUT en DELETE herhalen geen antwoord. Voor documenten berekent OrdoGrid een vingerafdruk van de volledige aanmaakbody zoals verstuurd: een gewijzigde notitie of e-mail, een extra optioneel veld, of 8 in plaats van "8" is andere inhoud. Bewaar dus de verstuurde body en herhaal hem ongewijzigd. Voor bewegingen tellen bedrag, valuta, methode, occurred_at (vergeleken in UTC) en reference.
Na een time-out of een verloren antwoord:
- Zoek de identiteit op met
GET /api/v1/invoices/lookup?external_id=...,GET /api/v1/credit-notes/lookup?external_id=...ofGET /api/v1/invoices/payments/lookup?external_id=.... - Gevonden: gebruik dat record.
404: herhaal de identieke body. 409 EXTERNAL_OPERATION_IN_PROGRESS: een ander verzoek maakt het aan; wacht en herhaal daarna de identieke body (de vergrendeling van een onderbroken poging vervalt na twee minuten).502 DOCUMENT_CREATED: het document is opgeslagen, maar de pdf of bijlagen zijn niet afgewerkt; herhaal met dezelfdeexternal_iden dezelfde body.- Schakel nooit over op een nieuwe
external_idomdat een antwoord verloren ging.
PEPPOL_TRANSMISSION_UNCERTAIN betekent dat OrdoGrid niet kan bevestigen of het document vertrokken is: lees de status en stem de uitkomst af met de support van OrdoGrid voor u opnieuw verstuurt, want een time-out bewijst geen mislukking en Peppol markeert een tweede exemplaar niet als dubbel, zodat de software van de klant het twee keer kan boeken.
Aanroeplimieten (rate limits) gelden per sleutel en per minuut: lees X-RateLimit-Limit, X-RateLimit-Remaining en X-RateLimit-Reset, en wacht bij 429 RATE_LIMITED de tijd van Retry-After af. Blader door lijsten met limit (hoogstens 100) en offset tot u elke rij hebt. Baseer uw logica op de foutcode code, nooit op message.
Rekenvoorbeeld: een toonbankverkoop met een voorschot per kaart
Kantoor Plus BV, een winkel in kantoorbenodigdheden in Mechelen, koppelt haar kassa met de sleutel Kassa Mechelen (Integratie-ID pos-mechelen). Op vrijdag 2 oktober 2026 om 10.15 uur neemt Boekhoudkantoor Lemmens BV, btw-plichtig onder BE0123456749, 8 inktcartridges mee tegen € 12,50 per stuk inclusief 21 % btw, betaalt € 40,00 met de kaart en zal de rest overschrijven.
1. GET /api/v1/peppol/participants/BE0123456749 geeft "registered": true en "participant_id": "0208:0123456749".
2. De kassa maakt de factuur aan met het ticket als identiteit:
POST /api/v1/invoices
Authorization: Bearer ik_live_...
Idempotency-Key: pos-ticket-2026-0187-create
Content-Type: application/json
{
"external_id": "pos-ticket-2026-0187",
"client": {"name": "Boekhoudkantoor Lemmens BV", "vat_number": "BE0123456749",
"address": {"street": "Bruul 12", "city": "Mechelen", "postal_code": "2800", "country": "BE"}},
"currency": "EUR", "issue_date": "2026-10-02", "due_date": "2026-11-02",
"purchase_order": "LEM-2026-118",
"items": [{"description": "Inktcartridge XL zwart", "quantity": "8", "unit_price": "0",
"price_basis": "gross", "source_unit_price": "12.50", "vat_rate": 21}],
"prepayments": [{"external_id": "pos-tender-2026-0187-1", "amount": "40.00", "currency": "EUR",
"method": "card", "occurred_at": "2026-10-02T10:15:00+02:00", "reference": "Kassa 2 / ticket 0187"}]
}
3. OrdoGrid berekent:
| Stap | Berekening | Resultaat |
|---|---|---|
| Afgesproken bedrag | 8 × € 12,50 | € 100,00 |
| Nettobedrag | € 100,00 ÷ 1,21 = € 82,6446…, afgerond | € 82,64 |
| Btw aan 21 % | € 82,64 × 21 % = € 17,3544, afgerond | € 17,35 |
Wettelijk totaal (totals.gross) | € 82,64 + € 17,35 | € 99,99 |
Afronding (totals.rounding, BT-114) | € 100,00 − € 99,99 | +€ 0,01 |
Verschuldigd vóór het voorschot (totals.payable, document_total) | € 99,99 + € 0,01 | € 100,00 |
Te betalen bedrag (BT-115, outstanding) | € 99,99 − € 40,00 + € 0,01 | € 60,00 |
Het antwoord 201 bevat het toegekende nummer, bijvoorbeeld F-2026-0412, en:
{
"external_id": "pos-ticket-2026-0187", "integration_id": "pos-mechelen",
"totals": {"net": 82.64, "vat": 17.35, "gross": 99.99, "rounding": 0.01, "payable": 100.0},
"settlement": {"document_total": "100.00", "prepayments": "40.00", "payments": "40.00",
"credits": "0.00", "outstanding": "60.00", "refund_due": "0.00", "status": "partial"}
}
totals zijn JSON-getallen en de waarden in settlement decimale strings: vergelijk ze allebei als decimalen. Het voorschot zit al in payments; tel prepayments er nooit bij op. In de app toont het paneel Afrekening Factuurtotaal € 100,00, Vooruitbetalingen € 40,00, Betalingen (inclusief vooruitbetalingen) € 40,00 en Openstaand € 60,00. De cartridges worden aan de kassa overhandigd, dus de € 40,00 is een gedeeltelijke betaling. Een voorschot dat vóór de levering wordt ontvangen, maakt de btw opeisbaar bij ontvangst en moet uiterlijk de 15e van de volgende maand gefactureerd zijn (voorschotfactuur).
4. POST /api/v1/peppol/invoices/{id}/send met een lege body. De UBL bevat € 0,01 als afronding (BT-114) en € 60,00 als te betalen bedrag (BT-115), zoals regel BR-CO-16 voorschrijft. Kantoor Plus bewaart de peppol_document_id.
5. Op maandag 12 oktober 2026 toont de bank € 60,00 van Boekhoudkantoor Lemmens. POST /api/v1/invoices/{id}/payments met external_id bank-2026-10-12-07, amount "60.00", method bank_transfer, occurred_at 2026-10-12T09:30:00+02:00 geeft 201, outstanding "0.00" en status "settled".
6. De kassa is weer online en stuurt het voorschot pos-tender-2026-0187-1 met identieke velden opnieuw naar dezelfde betalingsroute: OrdoGrid geeft het oorspronkelijke voorschot terug met 200 en "replayed": true, en payments blijft "100.00".
| Fout bij deze verkoop | Resultaat | Oplossing |
|---|---|---|
"unit_price": "12.50" met "prices_include_vat": true, zonder price_basis | € 100,00 netto + € 21,00 btw = € 121,00, dus € 21,00 te veel | Stuur price_basis en source_unit_price |
Voorschot "40.004", of occurred_at zonder offset | INVALID_AMOUNT_PRECISION, INVALID_OCCURRENCE_TIME | Rond af op de cent; voeg +02:00 toe |
| Overschrijving van € 60,50 volledig geboekt | OVERPAYMENT, niets geregistreerd | Registreer € 60,00; regel de € 0,50 buiten deze factuur |
Herhaling opnieuw opgebouwd met "quantity": 8 in plaats van "8" | 409 EXTERNAL_ID_REUSED | Herhaal de bewaarde body |
Stel een acceptatiedossier samen vóór de livegang
Elke aanroep maakt echte, genummerde documenten aan en elke verzending bereikt het echte netwerk. Voer het dossier uit met echte transacties en een pilootklant die ervan op de hoogte is, houd de bedragen klein en corrigeer fouten met creditnota's, via Peppol als de factuur via Peppol ging.
| Nr. | Geval | Verwacht resultaat |
|---|---|---|
| 1 | Nettoprijzen aan elk btw-tarief dat u gebruikt | Netto, btw en totaal gelijk aan uw bron tot op de cent; nummer in de reeks van het bedrijf |
| 2 | Prijzen inclusief btw (het rekenvoorbeeld) | rounding 0,01 en payable 100,00 |
| 3 | Negatieve afronding: 10 × € 12,50 inclusief 21 % btw | Netto € 103,31, btw € 21,70, wettelijk totaal € 125,01, afronding −€ 0,01, te betalen € 125,00 |
| 4 | Gedeeltelijke creditnota | Verstuurd als UBL CreditNote; outstanding daalt; meer crediteren dan er overblijft geeft CREDIT_CAPACITY_EXCEEDED |
| 5 | Creditnota op een betaalde factuur, daarna de terugbetaling | refund_due verschijnt en valt daarna terug op nul |
| 6 | Voorschot, betaling, herhaald voorschot | Het voorschot telt nooit dubbel |
| 7 | Aanmaak herhaald binnen en na 24 uur; antwoord verloren na de commit | Telkens dezelfde factuur en hetzelfde nummer; de opzoeking vindt ze |
| 8 | Gewijzigde body onder een bestaande external_id | 409 EXTERNAL_ID_REUSED; niets aangemaakt |
| 9 | Klant niet op Peppol | registered: false; terugvalkanaal gebruikt; geen Peppol-poging |
| 10 | Aflevering en bewijs | Status gelezen tot aflevering; XML opgehaald met peppol_document_id |
| 11 | Sleutel vervangen met dezelfde Integratie-ID | De opzoeking vindt de eerdere facturen |
| 12 | Ontbrekende permissie, onvolledig adres, onbekend veld | 403 INSUFFICIENT_SCOPE; 400 met de naam van het veld |
Laat de controller de verwachte bedragen vóór de test goedkeuren en ga pas live als elk verschil verklaard is.
Randgevallen en veelgemaakte fouten
| Fout | Gevolg | Juiste aanpak |
|---|---|---|
Betalingsnummers van de kassa die elke dag opnieuw bij 1 beginnen, gebruikt als external_id | 409 EXTERNAL_ID_REUSED vanaf de tweede dag, want bewegings-ID's zijn uniek over alle facturen heen | Bouw ID's die nooit terugkomen, zoals jaar plus ticketnummer, zoals in het voorbeeld |
ERP-nummers in number terwijl gebruikers ook facturen in de app maken | Gaten of 409 DOCUMENT_NUMBER_TAKEN in dezelfde reeks | Laat één systeem eigenaar zijn van de factuurreeks; laat number weg |
Bedragen gewijzigd met PATCH na een betaling of een Peppol-verzending | DOCUMENT_FINANCIAL_CONTENTS_LOCKED | Creditnota en zo nodig een nieuwe factuur |
| Creditnota bij een Peppol-factuur alleen als pdf verstuurd | Niet het gestructureerde formaat dat de wet vraagt | Verstuur ze met POST /api/v1/peppol/credit-notes/{id}/send |
| Traité of ‘afgeleverd’ gelezen als goedkeuring | Betaling opgevolgd voor een factuur die de koper afwees | Volg de Invoice Responses op de pagina Peppol; ze komen alleen in OrdoGrid binnen als het bedrijf daar ontvangt (Activer la réception), en een koper is niet verplicht er een te sturen |
| Pdf gemaild naast de Peppol-verzending | De klant boekt de factuur mogelijk twee keer | Alleen Peppol als de klant daar ontvangt; Belgische Peppol-dienstverleners raden dubbel versturen af |
Bewijs om te bewaren
- Sleutelregister: naam, Integratie-ID, permissies, eigenaar, datum van aanmaak en rotatie; nooit het geheim.
- Momentopname van het contract: het geanonimiseerde
/me-antwoord met datum encontract_version, plus de geversioneerde veldkoppeling en de goedgekeurde verwachte bedragen. - Per transactie:
external_id, OrdoGrid-iden -nummer,peppol_document_id, de exacte verstuurde body, de antwoordcode en decodevan elke weigering. - Foutdossier: voor elke code die u tijdens de acceptatie tegenkwam, een geanonimiseerd verzoek, de
codeen de gekozen herstelactie. Test na een wijziging van de veldkoppeling de herhalingsgevallen opnieuw: een nieuw veld verandert de body van documenten die nog op een herhaling wachten. - Documenten en betalingen: de uitgewisselde XML en pdf, de uitgereikte pdf (
GET /api/v1/invoices/{id}/pdf?view=original), zo nodig een gedateerd overzicht (?view=current) en de bewegingsgeschiedenis (GET /api/v1/invoices/{id}/payments).
De Belgische wet vraagt facturen 7 jaar te bewaren, te rekenen vanaf 1 januari van het jaar na de uitreiking (art. 60 Btw-Wetboek, gewijzigd door de wet van 18 december 2025), en de FOD Financiën raadt sterk aan de oorspronkelijke XML te bewaren. OrdoGrid archiveert de exacte XML en pdf van elke verzending met hun hashes, maar is geen wettelijke archiveringsdienst: bewaar uw eigen kopieën.
Veelgestelde vragen
Is er een sandbox of testmodus?
Nee. Elke aanroep werkt op echte bedrijfsgegevens en elke verzending bereikt het echte Peppol-netwerk; ook "send": false maakt een echte genummerde factuur aan. Test met echte transacties en een pilootklant, en corrigeer fouten met creditnota's.
Wat gebeurt er met mijn integratie als ik een sleutel roteer?
Het oude geheim stopt onmiddellijk, dus zet het nieuwe meteen in gebruik. Roteren behoudt de Integratie-ID, de permissies en de vervaldatum, zodat opzoekingen en de bescherming tegen dubbels blijven werken.
Waarom krijg ik EXTERNAL_ID_REUSED terwijl ik alleen een notitie wijzigde?
OrdoGrid berekent de vingerafdruk van de volledige aanmaakbody, niet alleen van de bedragen. Herhaal de bewaarde body. Is de zakelijke gebeurtenis echt veranderd, behandel het dan als een correctie: een creditnota en zo nodig een nieuwe factuur met een nieuwe external_id.
Kan de API een factuur mailen naar een klant die niet op Peppol staat?
Nee, de publieke API heeft geen e-mailbewerking. Haal de pdf op met GET /api/v1/invoices/{id}/pdf en verstuur hem via uw eigen kanaal, of laat een gebruiker hem in de app versturen met Envoyer.
Betekent een afgeleverde status dat de klant de factuur aanvaardde?
Nee, het betekent aflevering op het netwerk. Aanvaarding of afwijzing komt alleen via een Invoice Response, die een koper niet verplicht is te sturen, en betaling alleen via een geregistreerde beweging.
Kan mijn systeem leveranciersfacturen via de API ontvangen?
Ja, met peppol:read, via GET /api/v1/peppol/inbox en de XML-route, op voorwaarde dat het bedrijf via OrdoGrid ontvangt. OrdoGrid boekt leveranciersfacturen niet en keurt ze ook niet goed; dat blijft in uw boekhoudpakket.
Bronnen en referenties
- OrdoGrid – Referentie van de publieke API
- OpenPeppol – Peppol BIS Billing 3.0
- FOD Financiën – FAQ Algemene vragen over Peppol (0208-ID, opzoeken, vertragingen)
- FOD Financiën – FAQ Algemene vragen over de B2B-verplichting (klant niet klaar, pdf, bijlagen)
- FOD Financiën – FAQ Specifieke vragen over e-facturatie (creditnota's, dubbels)
- FOD Financiën – Hoe bewaar ik facturen die ik via e-facturatie ontvang?