Voor ontwikkelaars en integratieteams

Behoud uw facturatiesysteem. Verbind de facturen met Peppol.

Maak facturen op basis van gestructureerde gegevens, verstuur bestaande facturen en creditnota’s via Peppol en haal afleverstatussen en ontvangen documenten op. Elke sleutel van de publieke REST-API werkt binnen één OrdoGrid-bedrijf. Uw team bouwt en beheert de verbinding; de referentie beschrijft de ondersteunde verzoeken en antwoorden.

Bekijk de API-referentieVergelijk abonnementen

Kies de integratie rond uw eigen werkproces

Een ERP of uw eigen facturatieapplicatie

Maak klanten, facturen en creditnota’s uit gekoppelde velden. Bewaar de bron-ID zodat herhalingen hetzelfde document terugvinden in plaats van een tweede factuur uit te reiken.

Een systeem dat al pdf’s maakt

Lever de gestructureerde factuurvelden en eventueel uw eigen pdf-weergave aan. OrdoGrid bouwt de UBL op uit die velden; deze API haalt geen factuurgegevens uit een pdf.

Een proces voor aankoopfacturen of afstemming

Lees de Peppol-inbox, haal uitgewisselde XML- en pdf-bestanden op en stem ze af met uw systeem. Het bedrijf moet via OrdoGrid ontvangen om de inbox te vullen.

Van uw bronrecord naar een controleerbaar resultaat

  1. Maak een beperkte bedrijfssleutel

    Een eigenaar of beheerder maakt een sleutel in Bedrijf → API-sleutels. Kies een stabiele Integratie-ID en alleen de vereiste rechten. Begin met GET /api/v1/me om bedrijf, naamruimte en effectieve rechten te controleren.

  2. Maak en controleer de factuur

    POST /api/v1/invoices aanvaardt een bestaande client_id of klantgegevens in het verzoek, met gestructureerde factuurregels. Bewaar de teruggegeven id en het nummer. Laat number weg om de bedrijfsreeks te gebruiken; controleer bedragen, klant en btw-behandeling vóór verzending.

  3. Controleer de ontvanger en verstuur

    Controleer GET /api/v1/peppol/participants/{vat_number} en roep daarna POST /api/v1/peppol/invoices/{id}/send aan. Aanmaken vereist invoices:write; verzenden vereist peppol:send. Creditnota’s hebben een eigen credit-notes-verzendroute.

  4. Lees de aflevering en bewaar de bestanden

    Gebruik GET /api/v1/peppol/invoices/{id}/status met peppol:read. Bewaar document_id en peppol_document_id; gebruik die laatste voor de uitgewisselde XML. Overdracht aan het toegangspunt, netwerkaflevering, klantantwoord en betaling zijn afzonderlijke resultaten.

Drie afzonderlijke verzoeken, één factuur

Voorbeeldverzoeken via HTTP, geen interactieve console. Vervang iedere tijdelijke aanduiding door uw bedrijfssleutel, een bestaande klant-ID en stabiele bewerkingssleutels. Gebruik de teruggegeven factuur-id voor verzending en status. Het voorbeeld heeft twee eenheden van €150 netto en 21% btw; kies de behandeling die bij uw echte transactie past.

Verzoeken werken op echte bedrijfsgegevens. Een factuur aanmaken legt een echt document en nummer vast. Er is geen sandbox: verstuur uitsluitend echte facturen naar een afgesproken ontvanger. Deze pagina voert geen verzoek uit.

1. Maak de factuur

POST /api/v1/invoices
Authorization: Bearer <company-api-key>
Idempotency-Key: <stable-create-operation-key>
Content-Type: application/json

{
  "external_id": "your-source-order-id",
  "client_id": "<existing-client-id>",
  "currency": "EUR",
  "items": [
    {
      "description": "Adviesdienst",
      "quantity": "2",
      "unit_price": "150.00",
      "vat_rate": 21
    }
  ]
}

2. Verstuur de gecontroleerde factuur

POST /api/v1/peppol/invoices/<invoice-id>/send
Authorization: Bearer <company-api-key>
Idempotency-Key: <stable-send-operation-key>
Content-Type: application/json

{ "include_pdf": true }

3. Lees de Peppol-status

GET /api/v1/peppol/invoices/<invoice-id>/status
Authorization: Bearer <company-api-key>

Het antwoord op aanmaken bevat id en number. Verzending en status gebruiken document_id voor de factuur en peppol_document_id voor het uitgewisselde Peppol-document, met genormaliseerde status, lifecycle en transmission_state. Een geslaagd verzendantwoord bewijst geen klantgoedkeuring of betaling.

Bekijk de API-referentie

Houd controle over het bedrijf en de rechten

  • De sleutel identificeert één bedrijf; er is geen header waarmee de aanroeper een ander bedrijf kiest. App-sessiecookies authenticeren geen zakelijke bewerkingen van de publieke API.
  • Dit voorbeeld vereist invoices:write, peppol:send en peppol:read. Een write-recht omvat read op dezelfde bron; peppol:send omvat geen peppol:read.
  • Kopieer het geheim eenmalig naar uw geheime opslag op de server. Houd het uit browsercode, URL’s, analyses en logs. Roteer of trek het in via de app wanneer nodig.
  • Behoud dezelfde Integratie-ID bij sleutelvervanging. Roteren behoudt die; een afzonderlijk aangemaakte sleutel vereist dat u de oorspronkelijke naamruimte opnieuw opgeeft.

Bouw herstel in de verbinding in

Twee identiteiten voor herhalingen

Op ondersteunde POST-routes speelt Idempotency-Key een geslaagd antwoord 24 uur opnieuw af binnen dezelfde API-sleutel. Een stabiele external_id beschermt documentcreatie per bedrijf, Integratie-ID en documenttype ook daarna. Bewaar de oorspronkelijke inhoud ongewijzigd.

Stem een onbekend resultaat eerst af

Zoek na een time-out de factuur via external_id en lees de verzendstatus. Een onzekere verzending kan al op het netwerk zitten: houd ze vast en stem de gearchiveerde overdracht af vóór een nieuwe verzending. Maak geen nieuwe factuur om een fout te omzeilen.

Respecteer limieten en foutcodes

Lees de limietheaders per sleutel en wacht Retry-After bij HTTP 429. Baseer de logica op de foutcode, niet op de berichttekst. Lees lijsten met limit en offset om alle records op te halen.

Haal statussen op en stem ze af

Uw integratie leest de publieke status- en documentroutes en beheert de bewaking. Bewaar de uitgewisselde XML en controleer brontotalen, aflevering en afrekening apart. De integratiegidsen beschrijven herstelgevallen en acceptatiecontroles.

Controleer deze grenzen vóór uw keuze

  • Gestructureerde velden zijn verplicht. Deze publieke API heeft geen extractieroute voor alleen pdf en geen verzendroute voor geüploade ruwe UBL. Een optionele pdf is de weergave, niet de bron voor de UBL.
  • Peppol-verzending ondersteunt facturen en creditnota’s, geen offertes of ontvangstbewijzen. De bedrijfsmachtiging en toepasselijke maandlimiet worden vóór verzending gecontroleerd.
  • POST /api/v1/peppol/send maakt een echte factuur, ook met send: false. Dat is geen sandbox en controleert nog steeds de Peppol-machtiging en limiet.
  • De publieke API heeft geen bewerking om documenten te e-mailen. Registreer betalingen pas nadat het geld via uw eigen betaalkanaal is verplaatst; payments:write belast geen kaart en maakt geen geld over.
  • Een verbinding vraagt veldkoppeling, ontwikkeling en beheer. Dit is geen kant-en-klare connector voor elk ERP of elke boekhouder. Historiek en exports vragen een afzonderlijk migratieplan.

Vragen over factureren via de API

Kan ik de documentatie zonder account lezen?
Ja. De referentie en GET /api/v1/openapi.json zijn openbaar. Zakelijke bewerkingen vereisen uw eigen bedrijfssleutel en de rechten die bij elke bewerking staan.
Kan ik de pdf’s van mijn eigen systeem behouden?
Ja. Lever uw pdf samen met overeenkomstige gestructureerde gegevens, of upload de weergave naar de bestaande factuur. De referentie beschrijft de aanvaarde formaten. Controleer vóór verzending of de weergave en gestructureerde bedragen overeenkomen.
Heb ik de API nodig voor enkele facturen per maand?
Meestal volstaat de app. Het blijvend gratis abonnement omvat onbeperkt Peppol ontvangen en één verzonden factuur per maand; Starter voegt onbeperkt verzenden toe. Kies Business wanneer u deze API of de andere inbegrepen processen nodig hebt.
Kan ik statussen lezen met alleen peppol:send?
Nee. Voeg peppol:read toe voor ontvangercontroles, afleverstatus, inbox en uitgewisselde documenten. Geef de sleutel alleen de rechten die uw integratie nodig heeft.

Plan en bouw de verbinding