Draaiboek22 min leestijd

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 situatieBelangrijkste aanroepenPermissies (scopes)
ERP reikt facturen uit en verstuurt ze via PeppolPOST /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 maaktinvoices:write, peppol:send, peppol:read
Kassa met voorschotten, latere betalingen en terugbetalingenPOST /api/v1/invoices met prepayments, daarna .../payments en .../refundsde vorige, plus credit_notes:write en payments:write
Creditnota'sPOST /api/v1/credit-notes, daarna POST /api/v1/peppol/credit-notes/{id}/sendcredit_notes:write, peppol:send
Rapportering of afstemmingGET /api/v1/invoices, GET .../payments, GET /api/v1/peppol/documentsinvoices:read, peppol:read
Leveranciersfacturen naar uw systeemGET /api/v1/peppol/inbox, GET /api/v1/peppol/documents/{id}/xmlpeppol:read
  • Een write-permissie omvat read op dezelfde resource en niets anders: peppol:send omvat geen peppol:read, dat u nodig hebt voor de ontvangerscontrole, de afleverstatus en de uitgewisselde XML.
  • POST /api/v1/peppol/send vraagt zowel invoices:write als peppol:send. prepayments op een nieuwe factuur vragen bovendien payments:write, anders volgt 403 INSUFFICIENT_SCOPE.
  • De betalingsgeschiedenis en het opzoeken van een beweging vragen invoices:read, niet payments: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_id in de API. OrdoGrid bewaart elke external_id per 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.

  1. Open in het profielmenu API-sleutels en klik op Sleutel aanmaken. Alleen een Eigenaar of Beheerder kan dat.
  2. Geef een Naam die het systeem herkenbaar maakt, bijvoorbeeld Kassa Mechelen.
  3. Vervang in Integratie-ID de standaardwaarde default door een stabiele waarde zoals pos-mechelen (1 tot 80 letters, cijfers, _, . of -).
  4. 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.
  5. 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.
  6. Roep GET /api/v1/me aan en controleer naam en btw-nummer van het bedrijf, api_key.integration_id, effective_scopes, valuta, betaalmethoden en rate_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.

SituatieWat OrdoGrid doetIntegratie-IDWat u doet
RoterenNieuw geheim met dezelfde naam, permissies, vervaldatum en Integratie-ID; het oude geheim stopt onmiddellijkBehoudenZet het nieuwe geheim meteen in gebruik
Intrekken, daarna Sleutel aanmakenDe oude sleutel stopt onmiddellijkdefault, tenzij u ze opnieuw invultVul exact dezelfde Integratie-ID in
Badge Vervallen of IngetrokkenAanroepen geven 401 API_KEY_EXPIRED of 401 API_KEY_REVOKEDBlijft op de oude sleutelMaak een nieuwe sleutel met dezelfde Integratie-ID; Roteren behoudt een verstreken vervaldatum

Koppel elk veld expliciet

Zakelijk gegevenAPI-veldRegel
Uw order-, ticket- of contractnummerexternal_id1 tot 200 tekens; nooit hergebruikt voor een andere zakelijke gebeurtenis
Klantclient (inline) of client_idEen van beide; voor Peppol vat_number en een volledig address
Adresstreet, city, postal_code, countryAlle 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
FactuurnummernumberLaat 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 klantpurchase_orderWordt de UBL-BuyerReference
BetalingsreferentiecommunicationWordt de UBL-PaymentID, en de BuyerReference als er geen bestelnummer is
Regelsitems[]: description, quantity, unit_price, vat_rate, vat_type, unit, discountunit_price is een prijs exclusief btw
Prijs inclusief btwprice_basis: "gross", source_unit_priceZie hieronder
Btw-regelingitems[].vat_type, per regelstandard, 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 aanmakenprepayments[]Alleen facturen; vraagt payments:write
Uw eigen pdfpdf op POST /api/v1/peppol/send, of PUT /api/v1/invoices/{id}/pdfWordt 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 uitgereiktVerplicht 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, address en items, worden geweigerd met een 400 die ze noemt: een 200 of 201 betekent 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_at vraagt een ISO 8601-offset, zoals 2026-10-02T10:15:00+02:00, anders volgt INVALID_OCCURRENCE_TIME. België staat tot 25 oktober 2026 op UTC+2, daarna op UTC+1. Antwoorden schrijven elk tijdstip in UTC, met milliseconden en Z: deze betaling komt terug als 2026-10-02T08:15:00.000Z. Zet om naar lokale tijd voor weergave; dagen (issue_date, due_date) blijven JJJJ-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.

  1. Controleer de ontvanger. GET /api/v1/peppol/participants/BE0123456749 geeft registered en, als die gevonden is, een participant_id zoals 0208:0123456749. Belgische bedrijven zijn ingeschreven onder hun ondernemingsnummer (schema 0208): vraag uw klanten geen aparte Peppol-ID. registered: false betekent dat geen inschrijving kon worden bevestigd, omdat de klant er niet op staat of omdat de opzoeking mislukte; herhaal ze en zoek zo nodig 0208: gevolgd door het ondernemingsnummer op lookup.peppol.org.
  2. Verstuur met POST /api/v1/peppol/invoices/{id}/send. Optioneel: include_pdf (standaard true), attachments (nieuwe bestanden in base64), attachment_ids (bestanden die al bij de factuur horen).
  3. Bewaar peppol_document_id uit het antwoord, naast document_id en transmission_state.
  4. 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.
  5. Archiveer de uitgewisselde UBL met GET /api/v1/peppol/documents/{peppol_document_id}/xml en 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.

RouteGebruikLet op
POST /api/v1/peppol/sendAanmaken 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}/sendEen bestaande factuur versturenEen creditnota-ID geeft 404
POST /api/v1/peppol/credit-notes/{id}/sendEen creditnota versturenVertrekt als UBL CreditNote (type 381); een factuur-ID geeft 404
Offertes, ontvangstbewijzenGeenGeen 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

MechanismeBereikLooptijdIdentieke herhalingAndere inhoud
Header Idempotency-KeyEén API-sleutel; de POST-bewerkingen die hem documenteren24 uurOorspronkelijk antwoord, header Idempotent-Replay: true409 IDEMPOTENCY_KEY_REUSED
external_id op facturen en creditnota'sBedrijf, Integratie-ID, documenttypeVervalt niet; overleeft rotatieEerste volledige antwoord409 EXTERNAL_ID_REUSED
external_id op voorschotten, betalingen, terugbetalingenBedrijf en Integratie-ID, over alle facturen heenVervalt niet; overleeft rotatieOorspronkelijke beweging, 200, "replayed": true409 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:

  1. Zoek de identiteit op met GET /api/v1/invoices/lookup?external_id=..., GET /api/v1/credit-notes/lookup?external_id=... of GET /api/v1/invoices/payments/lookup?external_id=....
  2. Gevonden: gebruik dat record. 404: herhaal de identieke body.
  3. 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).
  4. 502 DOCUMENT_CREATED: het document is opgeslagen, maar de pdf of bijlagen zijn niet afgewerkt; herhaal met dezelfde external_id en dezelfde body.
  5. Schakel nooit over op een nieuwe external_id omdat 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:

StapBerekeningResultaat
Afgesproken bedrag8 × € 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 verkoopResultaatOplossing
"unit_price": "12.50" met "prices_include_vat": true, zonder price_basis€ 100,00 netto + € 21,00 btw = € 121,00, dus € 21,00 te veelStuur price_basis en source_unit_price
Voorschot "40.004", of occurred_at zonder offsetINVALID_AMOUNT_PRECISION, INVALID_OCCURRENCE_TIMERond af op de cent; voeg +02:00 toe
Overschrijving van € 60,50 volledig geboektOVERPAYMENT, niets geregistreerdRegistreer € 60,00; regel de € 0,50 buiten deze factuur
Herhaling opnieuw opgebouwd met "quantity": 8 in plaats van "8"409 EXTERNAL_ID_REUSEDHerhaal 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.GevalVerwacht resultaat
1Nettoprijzen aan elk btw-tarief dat u gebruiktNetto, btw en totaal gelijk aan uw bron tot op de cent; nummer in de reeks van het bedrijf
2Prijzen inclusief btw (het rekenvoorbeeld)rounding 0,01 en payable 100,00
3Negatieve afronding: 10 × € 12,50 inclusief 21 % btwNetto € 103,31, btw € 21,70, wettelijk totaal € 125,01, afronding −€ 0,01, te betalen € 125,00
4Gedeeltelijke creditnotaVerstuurd als UBL CreditNote; outstanding daalt; meer crediteren dan er overblijft geeft CREDIT_CAPACITY_EXCEEDED
5Creditnota op een betaalde factuur, daarna de terugbetalingrefund_due verschijnt en valt daarna terug op nul
6Voorschot, betaling, herhaald voorschotHet voorschot telt nooit dubbel
7Aanmaak herhaald binnen en na 24 uur; antwoord verloren na de commitTelkens dezelfde factuur en hetzelfde nummer; de opzoeking vindt ze
8Gewijzigde body onder een bestaande external_id409 EXTERNAL_ID_REUSED; niets aangemaakt
9Klant niet op Peppolregistered: false; terugvalkanaal gebruikt; geen Peppol-poging
10Aflevering en bewijsStatus gelezen tot aflevering; XML opgehaald met peppol_document_id
11Sleutel vervangen met dezelfde Integratie-IDDe opzoeking vindt de eerdere facturen
12Ontbrekende permissie, onvolledig adres, onbekend veld403 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

FoutGevolgJuiste aanpak
Betalingsnummers van de kassa die elke dag opnieuw bij 1 beginnen, gebruikt als external_id409 EXTERNAL_ID_REUSED vanaf de tweede dag, want bewegings-ID's zijn uniek over alle facturen heenBouw ID's die nooit terugkomen, zoals jaar plus ticketnummer, zoals in het voorbeeld
ERP-nummers in number terwijl gebruikers ook facturen in de app makenGaten of 409 DOCUMENT_NUMBER_TAKEN in dezelfde reeksLaat één systeem eigenaar zijn van de factuurreeks; laat number weg
Bedragen gewijzigd met PATCH na een betaling of een Peppol-verzendingDOCUMENT_FINANCIAL_CONTENTS_LOCKEDCreditnota en zo nodig een nieuwe factuur
Creditnota bij een Peppol-factuur alleen als pdf verstuurdNiet het gestructureerde formaat dat de wet vraagtVerstuur ze met POST /api/v1/peppol/credit-notes/{id}/send
Traité of ‘afgeleverd’ gelezen als goedkeuringBetaling opgevolgd voor een factuur die de koper afweesVolg 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-verzendingDe klant boekt de factuur mogelijk twee keerAlleen 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 en contract_version, plus de geversioneerde veldkoppeling en de goedgekeurde verwachte bedragen.
  • Per transactie: external_id, OrdoGrid-id en -nummer, peppol_document_id, de exacte verstuurde body, de antwoordcode en de code van elke weigering.
  • Foutdossier: voor elke code die u tijdens de acceptatie tegenkwam, een geanonimiseerd verzoek, de code en 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