PeppolKit koppelen via de API

Draait je webshop op een eigen systeem, of op een platform waarvoor we geen plugin hebben? Stuur elke betaalde bestelling naar de API. PeppolKit maakt de factuur, mailt hem naar je klant en verstuurt hem via Peppol.

Begin gratis Zo werkt het

Wat je nodig hebt

• Een account. Maak het gratis aan op de startpagina en kies Eigen systeem (API). Je krijgt een inloglink per mail; een wachtwoord is er niet.
• Je bedrijfsgegevens. Vul ze in het dashboard in onder Instellingen: naam, adres, btw-nummer en KvK- of ondernemingsnummer. Zonder die gegevens weigert de API een bestelling.
• Een sleutel. Ga in het dashboard naar API en klik op Maak een sleutel. Je ziet hem één keer. Bewaar hem op je server, als een wachtwoord.

Zo roep je de API aan

Alle aanroepen gaan naar https://app.peppolkit.com/api/v1, over https, met je sleutel in de kop Authorization. Je stuurt en krijgt JSON. Een eerste test:

curl https://app.peppolkit.com/api/v1/settings \
  -H "Authorization: Bearer pk_your_key"

Gaat er iets mis, dan krijg je een foutcode en een veld error met de reden:

• 401 de sleutel ontbreekt of klopt niet.
• 409 je bedrijfsgegevens zijn nog niet ingevuld.
• 422 de bestelling of terugbetaling is niet geldig; issues noemt per veld wat er mis is.
• 402 de limiet van je plan is bereikt. De bestelling blijft wachten en krijgt haar factuur na een upgrade of aan het begin van de volgende maand.

Een bestelling sturen

Stuur een bestelling zodra hij betaald is, met POST /orders. De opbouw is die van een Shopify-bestelling, zodat bestaande code en voorbeelden bruikbaar zijn. Sla dit op als order.json:

{
  "id": 1042,
  "name": "#1042",
  "currency": "EUR",
  "taxes_included": true,
  "created_at": "2026-11-13T10:15:00+01:00",
  "email": "inkoop@klant.be",
  "billing_address": {
    "name": "An Peeters",
    "company": "Klant BV",
    "address1": "Kerkstraat 1",
    "zip": "9000",
    "city": "Gent",
    "country_code": "BE"
  },
  "line_items": [
    {
      "id": 1,
      "title": "Kettingset 11-speed",
      "sku": "KS-11",
      "quantity": 2,
      "price": "39.00",
      "tax_lines": [{ "rate": 0.21, "price": "13.54" }]
    }
  ],
  "shipping_lines": [
    { "title": "Verzending", "price": "6.95", "tax_lines": [{ "rate": 0.21, "price": "1.21" }] }
  ],
  "note_attributes": [{ "name": "VAT number", "value": "BE0123456749" }],
  "total_price": "84.95"
}

En stuur het:

curl -X POST https://app.peppolkit.com/api/v1/orders \
  -H "Authorization: Bearer pk_your_key" \
  -H "Content-Type: application/json" \
  -d @order.json

De velden

• id het nummer van de bestelling in je systeem, een geheel getal. Dezelfde id nog een keer sturen maakt geen tweede factuur: je krijgt de bestaande terug met status: "exists".
• name het bestelnummer zoals je klant het ziet, bijvoorbeeld #1042.
• currency drie letters, bijvoorbeeld EUR.
• taxes_included true als de prijzen inclusief btw zijn, false als ze exclusief zijn.
• created_at datum en tijd van de bestelling (ISO 8601).
• email het adres waar de factuur naartoe gaat.
• billing_address naam, bedrijf, adres, postcode, plaats en land (country_code, twee letters). shipping_address mag erbij, in dezelfde vorm.
• line_items minstens één regel, met id, title, quantity, de stuksprijs price en de btw van de hele regel in tax_lines (rate als breuk: 0.21 is 21%). Een korting op een regel geef je mee in discount_allocations, als [{"amount": "5.00"}].
• shipping_lines de verzendkosten, in dezelfde vorm.
• note_attributes het btw-nummer van een zakelijke klant, met de naam VAT number. Met dat nummer wordt het een zakelijke factuur.
• total_price het totaal dat de klant betaalde.

Bedragen zijn tekst met een punt als decimaalteken ("39.00"), nooit een getal met afronding. Velden die PeppolKit niet kent, worden genegeerd.

Het antwoord bevat de factuur, met links naar de pdf en het UBL-bestand die 30 dagen werken. Het btw-nummer in dit voorbeeld bestaat niet; stuur je het zo in, dan staat er in warnings dat VIES het niet kent.

{
  "ok": true,
  "status": "issued",
  "warnings": [],
  "invoice": {
    "number": "2026-00042",
    "type": "invoice",
    "orderId": "1042",
    "issueDate": "2026-11-13",
    "total": 84.95,
    "currency": "EUR",
    "peppolStatus": "sent",
    "emailedAt": "2026-11-13T09:15:04.000Z",
    "emailTo": "inkoop@klant.be",
    "emailError": null,
    "pdfUrl": "https://app.peppolkit.com/i/…",
    "ublUrl": "https://app.peppolkit.com/i/…?format=xml",
    "warnings": []
  }
}

Btw en Peppol

PeppolKit bepaalt uit het land van de klant, het btw-nummer en je instellingen hoe de factuur wordt opgemaakt: gewone btw, btw verlegd of OSS. Het btw-nummer wordt gecontroleerd in VIES. Wijkt de uitkomst af van wat je winkel rekende, of is het nummer niet geldig, dan staat dat in warnings. Heeft je klant een Peppol-adres en staat versturen aan, dan gaat de factuur ook via Peppol; peppolStatus zegt hoe dat ging (sent, pending, not_on_peppol of failed); ging de factuur niet via Peppol, dan is het veld leeg (null).

Een terugbetaling sturen

Betaal je een klant terug, stuur dat dan met POST /refunds. PeppolKit maakt een creditnota bij de factuur van die bestelling. line_item_id verwijst naar de id van de regel in de bestelling; het bedrag dat je terugbetaalde staat in transactions.

curl -X POST https://app.peppolkit.com/api/v1/refunds \
  -H "Authorization: Bearer pk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "refund": {
      "id": 7001,
      "order_id": 1042,
      "created_at": "2026-11-20T14:00:00+01:00",
      "refund_line_items": [{ "line_item_id": 1, "quantity": 1 }],
      "transactions": [{ "kind": "refund", "status": "success", "amount": "39.00" }]
    }
  }'

Dezelfde id nog een keer sturen maakt geen tweede creditnota. Is er voor de bestelling geen factuur, dan krijg je 404.

Facturen ophalen

Met GET /invoices?orderId=… krijg je de factuur en de creditnota's van één bestelling. Zonder orderId krijg je de laatste 50 documenten. Met lang (nl, fr of en) kies je de taal van de waarschuwingen. Het antwoord is {"invoices": […]}, met per document dezelfde velden als hierboven; type is invoice of credit_note.

curl "https://app.peppolkit.com/api/v1/invoices?orderId=1042&lang=en" \
  -H "Authorization: Bearer pk_your_key"

Bedrijfsgegevens via de API

De instellingen uit het dashboard kun je ook via de API lezen (GET /settings) en schrijven (PUT /settings). Handig als je meerdere winkels aansluit.

curl -X PUT https://app.peppolkit.com/api/v1/settings \
  -H "Authorization: Bearer pk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Velo Atelier BV",
    "street": "Dorpsstraat 1",
    "postalCode": "9000",
    "city": "Gent",
    "country": "BE",
    "vatNumber": "BE0123456749",
    "registrationNumber": "0123456749",
    "email": "info@veloatelier.be",
    "language": "auto",
    "emailCustomers": true,
    "peppolSend": true
  }'

Eerst testen

Wil je proberen zonder dat er iets over het echte Peppol-netwerk gaat? Maak een tweede account aan met een adres dat eindigt op .test, bijvoorbeeld mijnwinkel.test. Zo'n account maakt echte facturen en pdf's, maar verstuurt nooit via Peppol. Zet daarnaast in de instellingen Mail de factuur automatisch naar de klant uit, of gebruik je eigen e-mailadres in de testbestellingen.

Veelgestelde vragen

PeppolKit per platform: Shopify, WooCommerce, PrestaShop, Magento, Drupal Commerce, OpenCart, Shopware, Joomla, bol.com, Lightspeed, CCV Shop, Wix en Stripe. Zo werkt het voor jouw webshop.

Uitleg ter oriëntatie, geen fiscaal advies.