Peppol API Integration
for ERPs, SaaS and Finance Systems

What is a Peppol API?

A Peppol API is a web interface, run by a certified Peppol Access Point, that lets your software send and receive e-invoices on the Peppol network with ordinary HTTPS calls. You post an invoice and read back its delivery status. The Access Point handles the AS4 messaging, certificates, validation and receiver discovery that Peppol requires.

Peppol itself has no central sending API. The network is a set of certified Access Points that exchange documents with each other, plus a directory (the SML and the SMPs) that says which Access Point serves which business. OpenPeppol publishes the rules and a public directory you can search, but an invoice only travels from one Access Point to another. So every Peppol API you can send through is an Access Point's own interface, and the questions worth asking are how it authenticates you, how you test against it, how you find a receiver and how it tells you an invoice arrived. The rest of this page answers each of those for GoRoute's API.

What is Peppol API integration?

Peppol API integration is the process of connecting a business system — an ERP such as SAP S/4HANA or Microsoft Business Central, an accounting package such as Odoo or Zoho Books, or a SaaS billing platform such as Stripe or Zuora — to the Peppol network via a certified Access Point exposed as a REST API.

Instead of implementing AS4 messaging, G3 PKI certificates, EN 16931 Schematron validation and SMP/SML discovery yourself, you POST a UBL or JSON document to a single endpoint. GoRoute's certified Access Point (POP000991) handles conversion, validation, signing, routing and delivery to any business registered to receive on Peppol, whichever Access Point that business uses.

The same API also covers DBNAlliance in the United States, Finvoice in Finland, and national CTC systems including Fawtara Oman, KSeF Poland, SDI Italy, XRechnung Germany and MyInvois Malaysia (ZATCA Saudi Arabia is in development) — so a single integration unlocks 40+ countries.

How do Peppol API keys work?

Every request carries one API key in the X-API-Key header. Test keys start sk_test_ and live keys start pk_live_, so the two cannot be confused in a config file. A key belongs to exactly one organisation, and every call it makes is scoped to that organisation: there is no organisation ID to pass.

Create a key in the dashboard under Settings → API Keys, or with POST /api/v1/api-keys once you hold one. The secret is shown once, in the response that creates it, and never again. Each key carries scopes, so an integration that only sends invoices does not also need the power to manage webhooks:

A new key from the API gets send and read unless you ask for more. Keys can carry an expiry date, or none. To rotate without downtime, create the new key, deploy it, confirm it works, then revoke the old one with DELETE /api/v1/api-keys/{id}. Revocation is permanent.

Errors name their cause in a top-level error_code: MISSING_API_KEY, INVALID_API_KEY or EXPIRED_API_KEY with HTTP 401, INSUFFICIENT_SCOPE with 403, and a 429 with a Retry-After header when you pass your plan's rate limit. Limits apply per organisation, not per key. The full rules are in the authentication guide.

Integrate in three steps

How do I track delivery status through the Peppol API?

Every send returns 202 with status queued and a transaction_id. From there, either poll GET /api/v1/transactions/{transaction_id} or let a webhook tell you. There is no synchronous send mode, so do not write code that waits on the first response. A transaction moves through these states:

To be told rather than poll, register a URL with POST /api/v1/webhooks and choose events. The ones a sender needs are transaction.queued, transaction.delivered, transaction.retrying and transaction.failed. A failed event carries the error_code, the message and the retry count.

Each delivery is signed. The X-Webhook-Signature header holds a timestamp t and an HMAC-SHA256 value v1, computed with your webhook secret over the timestamp, a full stop and the raw request body. Verify the raw bytes before parsing the JSON, or the digest will not match.

Retries are safe if you send an Idempotency-Key header: a repeat within 24 hours returns the first transaction_id and its current status, and nothing is sent twice. Field-by-field detail is in the webhook events reference. If a shop platform rather than your own code reports a failure, start with what to do when an e-invoice was not delivered.

Worked example: sending a Belgian invoice under scheme 0208

Since 1 January 2026, a Belgian VAT-liable business invoicing another must send a structured e-invoice in Peppol BIS Billing 3.0 over Peppol, and every such business must be able to receive one, as the Belgian government's e-invoicing site sets out. Belgian companies are usually addressed by their enterprise number (KBO/BCE) under Peppol scheme 0208; the VAT number under scheme 9925 is also in use. No Belgian accreditation is needed beyond Peppol certification. Here is the whole flow through the API.

1. Confirm the buyer can receive

Look the buyer up as 0208: plus its ten-digit enterprise number, as in the lookup example above. If 0208 is not confirmed, try the buyer's VAT number under 9925 before concluding anything. The enterprise number has a mod-97 check on its last two digits, so validate it in your own system before you call. The numbers on this page pass that check but are illustrations: replace them with your own and your customer's.

2. Send the invoice as JSON

curl -X POST https://app.goroute.ai/peppol-api/api/v1/invoices \
  -H "X-API-Key: $GOROUTE_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: BE-2026-0412" \
  -d '{
    "invoice": {
      "document_type": "invoice",
      "number": "BE-2026-0412",
      "issue_date": "2026-10-12",
      "due_date": "2026-11-11",
      "currency": "EUR",
      "seller": {
        "name": "Voorbeeld NV",
        "peppol_id": "0208:0123456749",
        "vat_number": "BE0123456749",
        "address": { "street": "Koningsstraat 1", "city": "Brussel",
                     "postal_code": "1000", "country": "BE" }
      },
      "buyer": {
        "name": "Klant BV",
        "peppol_id": "0208:0987654394",
        "vat_number": "BE0987654394",
        "address": { "street": "Meir 10", "city": "Antwerpen",
                     "postal_code": "2000", "country": "BE" }
      },
      "lines": [
        { "description": "Consulting, October 2026", "quantity": 10,
          "unit": "HUR", "unit_price": 100.00,
          "tax_rate": 21, "tax_category": "standard" }
      ],
      "totals": { "net_amount": 1000.00, "tax_amount": 210.00,
                  "payable_amount": 1210.00 }
    }
  }'

GoRoute validates the data, renders a Peppol BIS Billing 3.0 UBL invoice and answers 202 with "status": "queued". To check the same body without sending it, post it to /api/v1/invoices/validate first. Belgium's reduced rates of 12% and 6% go in as the standard category with the lower percentage; they are not separate codes.

3. Watch it arrive

The transaction.delivered webhook, or a poll that reads delivered, closes the loop. One Belgian rule is enforced for you: asking GoRoute to deliver a Belgian seller's invoice by email instead is refused with EMAIL_NOT_ALLOWED, because a PDF by email no longer counts between Belgian businesses.

For the mandate itself, see Belgium e-invoicing compliance. For why 0208 matters more than the VAT number, read the Belgian enterprise number on Peppol.

Peppol API integration FAQ