Playbook22 min read

Public API integration: keys, scopes, mapping and acceptance

Connect an ERP or till to OrdoGrid's public API: company keys and Integration ID, scopes, VAT-inclusive prices, Peppol sending, safe retries and acceptance tests.

Updated
Content owner
Integration team
For
Integration engineers · Solution architects · Finance owners of an integration

At a glance

Create one company-scoped key per integration with the narrowest permissions and a stable Integration ID, map fields so amounts match your source to the cent (VAT-inclusive prices included), check each recipient before sending on Peppol, and prove retries, settlement and delivery on real invoices before go-live. There is no sandbox: every call acts on real data.

Before you begin

  • Business plan including public API access
  • Owner or Administrator role in the OrdoGrid company the integration will act for
  • A signed Autorisation Peppol for the company's Belgian VAT number, if the integration sends on Peppol
  • A stable source identifier for every invoice, credit note and payment
  • Expected amounts for representative cases, agreed with your controller or accountant

What you will achieve

  • A key with the narrowest permissions and a recorded Integration ID
  • A field mapping that reproduces your amounts to the cent, rounding included
  • A passed acceptance pack covering retries, Peppol delivery and settlement
On this page

OrdoGrid's public API (/api/v1) lets an ERP, a till or a billing system create invoices, credit notes and payments in one OrdoGrid company and send them on Peppol. This playbook takes you from the key to go-live: permissions, field mapping to the cent, Peppol sending, retries without duplicates, and the tests to pass first.

It is written for integration engineers and the finance owner who signs off the amounts. Every endpoint is described in the API reference, readable without a login, with its OpenAPI file. Runtime retry and incident policy is in integration reliability.

What the law requires, what we recommend, what OrdoGrid does

What the law requires. Since 1 January 2026, businesses established in Belgium must issue structured electronic invoices for supplies to Belgian VAT-registered business customers, in principle in the Peppol BIS format over the Peppol network (the obligation in detail). That structured invoice is the legal invoice; a PDF copy is optional. A credit note correcting a structured invoice must also go via Peppol. If the customer cannot receive, you must still issue the invoice in another form, such as a PDF. FPS Finance points out that Peppol cannot detect duplicates: preventing them is your job.

What OrdoGrid does. The API builds the UBL XML from the fields you send, validates it against EN 16931 and Peppol BIS Billing 3.0.21 before delivery, and archives the exact XML and PDF transmitted. OrdoGrid connects to Peppol through a certified access point, and only companies with a Belgian (BE) VAT number can send. There is no sandbox, no endpoint that turns a PDF into an invoice, and no API operation that emails a document.

What we recommend. One key per integration, the narrowest permissions, a durable identity for every business event, a recipient check before each Peppol send, and expected amounts signed before go-live.

Choose the pattern and the permissions

Your situationMain callsPermissions (scopes)
ERP issues invoices and sends them on PeppolPOST /api/v1/invoices, then POST /api/v1/peppol/invoices/{id}/send; or one call to POST /api/v1/peppol/send, with your own pdf if you render oneinvoices:write, peppol:send, peppol:read
Till with deposits, later payments and refundsPOST /api/v1/invoices with prepayments, then .../payments and .../refundsthe above plus credit_notes:write and payments:write
Credit notesPOST /api/v1/credit-notes, then POST /api/v1/peppol/credit-notes/{id}/sendcredit_notes:write, peppol:send
Reporting or reconciliationGET /api/v1/invoices, GET .../payments, GET /api/v1/peppol/documentsinvoices:read, peppol:read
Supplier invoices into your systemGET /api/v1/peppol/inbox, GET /api/v1/peppol/documents/{id}/xmlpeppol:read
  • A write scope includes read on the same resource and nothing else: peppol:send does not include peppol:read, which you need for the recipient check, delivery status and exchanged XML.
  • POST /api/v1/peppol/send needs both invoices:write and peppol:send. prepayments on a new invoice need payments:write too, otherwise 403 INSUFFICIENT_SCOPE.
  • Payment history and movement lookup need invoices:read, not payments:read.
  • The inbox only fills when the company receives through OrdoGrid (Réception Peppol → Activer la réception, Enable reception).

Create the key and record its Integration ID

Integration ID

The namespace of a key, integration_id in the API. OrdoGrid stores every external_id per company, Integration ID and document type, so lookups and duplicate protection only see records created under the same Integration ID. It is set at creation, cannot be changed, and survives rotation.

  1. In the profile menu, open API keys and click Create key. Only an Owner or Administrator can.
  2. Enter a Name that identifies the system, for example POS Namur.
  3. In Integration ID, replace the default default with a stable value such as pos-namur (1–80 letters, digits, _, . or -).
  4. Tick only the Permissions from the table above. Leave Expires on empty for no expiry, or match your rotation policy.
  5. Click Create key, copy the secret under Copy this key now into your secret manager, then click I have saved it. The secret starts with ik_live_ and is shown only once.
  6. Call GET /api/v1/me and check the company name and VAT number, api_key.integration_id, effective_scopes, currencies, payment methods and rate_limit_per_minute. Keep the redacted response with your mapping.
curl https://ordogrid.com/api/v1/me -H "Authorization: Bearer ik_live_..."

The key can also be sent in the X-Api-Key header. App session cookies do not work on this API, and the key itself identifies the company, so there is no company header and no way to reach another company. The API keys list does not show the Integration ID after creation, and the page has no edit action: to change permissions, create a new key with the same Integration ID, switch the connector, then Revoke the old one.

SituationWhat OrdoGrid doesIntegration IDWhat you do
RotateNew secret with the same name, permissions, expiry and Integration ID; the old secret stops immediatelyKeptDeploy the new secret at once
Revoke, then Create keyThe old key stops immediatelydefault unless you retype itRetype exactly the same Integration ID
Badge Expired or RevokedCalls return 401 API_KEY_EXPIRED or 401 API_KEY_REVOKEDStays on the old keyCreate a new key with the same Integration ID; Rotate keeps a past expiry date

Map every field explicitly

Business dataAPI fieldRule
Your order, ticket or contract numberexternal_id1–200 characters; never reused for another business event
Customerclient (inline) or client_idOne of the two; for Peppol, vat_number and a complete address
Addressstreet, city, postal_code, countryAll four are required. Prefer a two-letter ISO code such as BE. Known country names in French, Dutch, English or German are normalized to that code; an unknown value is rejected with 400 INVALID_COUNTRY at creation
Invoice numbernumberOmit it so OrdoGrid assigns the next number of the company's series; a used number returns 409 DOCUMENT_NUMBER_TAKEN
Customer's order numberpurchase_orderBecomes the UBL BuyerReference
Payment referencecommunicationBecomes the UBL PaymentID, and the BuyerReference when there is no order number
Linesitems[]: description, quantity, unit_price, vat_rate, vat_type, unit, discountunit_price is a price excluding VAT
Price including VATprice_basis: "gross", source_unit_priceSee below
VAT treatmentitems[].vat_type, per linestandard, reverse_charge, cocontractant, intracommunity, exempt (small-business franchise), exempt_art44 (art. 44 exemption), zero_rated, export, margin; other values return UNKNOWN_VAT_TYPE, and a document-level vat_type is rejected as an unknown field
Money received at creationprepayments[]Invoices only; needs payments:write
Your own PDFpdf on POST /api/v1/peppol/send, or PUT /api/v1/invoices/{id}/pdfSent byte for byte, so it must show the same amounts as the data
Invoice being credited (credit notes)credit_for_invoice_id, or credit_for_invoice_number for an invoice issued outside OrdoGridRequired on POST /api/v1/credit-notes; links the credit note to the invoice it corrects

Because BuyerReference falls back to the payment reference and then the invoice number, the Peppol rule requiring a buyer or order reference (PEPPOL-EN16931-R003) is always met; still send the customer's order number when you have one. The API does not choose the VAT treatment: your source system or accountant does, using Belgian VAT regimes on invoices.

  • Send only mapped fields. Unknown fields, also inside client, address and items, are rejected with 400 naming them, so a 200 or 201 means everything you sent was applied.
  • Amounts are decimal strings. EUR, USD and GBP take two decimals, JPY none. Excess precision on a movement is refused (INVALID_AMOUNT_PRECISION), never truncated. Unit prices and quantities keep their precision.
  • Times carry a time zone. occurred_at needs an ISO 8601 offset, such as 2026-10-02T10:15:00+02:00, or the call returns INVALID_OCCURRENCE_TIME. Belgium is on UTC+2 until 25 October 2026, then UTC+1. Responses write every timestamp in UTC, with milliseconds and Z: this payment comes back as 2026-10-02T08:15:00.000Z. Convert to local time for display; days (issue_date, due_date) stay YYYY-MM-DD.
  • No currency conversion. A movement must be in the invoice currency (CURRENCY_MISMATCH). Belgian VAT rules require the VAT total in euro even on an invoice in another currency: agree the approach with your accountant before automating it.
  • Payments are movements, not labels. A paid status without a matching movement is refused with PAYMENT_MOVEMENT_REQUIRED.

Prices including VAT: send the price the customer saw

unit_price always means a net price, and prices_include_vat only changes how prices are displayed. A till that sends "unit_price": "12.50" with "prices_include_vat": true is charging €12.50 plus 21% VAT.

Send "price_basis": "gross" and "source_unit_price": "12.50" instead; unit_price is then a placeholder that does not override the source. OrdoGrid computes each line's net amount as quantity × price including VAT ÷ (1 + VAT rate), rounded to the cent, then VAT once per rate on the net total. The difference between your VAT-inclusive total and net plus VAT is totals.rounding, sent on Peppol as the rounding amount (BT-114). totals.gross stays net plus VAT; totals.payable is what the customer owes before prepayments. Fixed discounts take amount_basis: "net" (default) or "gross". Responses split discounts net of VAT: totals.line_discounts, totals.global_discount and their sum totals.discounts, the discount total printed on the PDF; global_discount returns the entered document discount. On 0% lines (reverse charge, intra-EU supplies, exports) gross equals net, so send net prices. Details: prices including VAT and rounding.

Send on Peppol: check, send, read the outcome

A user must first sign Autorisation Peppol (Peppol authorisation) for the company's VAT number in the Peppol menu (set up Peppol in OrdoGrid); otherwise sends return 403 PEPPOL_APPROVAL_REQUIRED. Sends count against the plan's monthly Peppol quota (403 PEPPOL_LIMIT_REACHED, count and limit in details). Receiving through OrdoGrid is not needed for sending, but Belgian law also requires your company to be able to receive Peppol invoices, through OrdoGrid or another provider.

  1. Check the recipient. GET /api/v1/peppol/participants/BE0123456749 returns registered and, if found, a participant_id such as 0208:0123456749. Belgian companies are registered under their enterprise number (scheme 0208): do not ask customers for a separate Peppol ID. registered: false means no registration could be confirmed, either because the customer is not registered on Peppol or because the lookup failed; repeat it and, if needed, search 0208: plus the enterprise number on lookup.peppol.org.
  2. Send with POST /api/v1/peppol/invoices/{id}/send. Optional: include_pdf (default true), attachments (new base64 files), attachment_ids (files already on the invoice).
  3. Store peppol_document_id from the response, next to document_id and transmission_state.
  4. Read the outcome with GET /api/v1/peppol/invoices/{id}/status (status, lifecycle, transmission_state). In the app the document appears in Peppol → Outbox, where the badge Traité (Processed) means network delivery, not acceptance. Most documents arrive within minutes to a couple of hours; after one working day, contact OrdoGrid support.
  5. Archive the exchanged UBL with GET /api/v1/peppol/documents/{peppol_document_id}/xml and the transmitted PDF with .../pdf. The invoice id does not work there.

If the customer is not on Peppol, create the invoice with POST /api/v1/invoices, fetch its PDF with GET /api/v1/invoices/{id}/pdf and deliver it through your own channel, or let a user send it with Envoyer (Send) in the app. Once the customer can receive, do not resend old invoices on Peppol; see customer not on Peppol.

RouteUseWatch out for
POST /api/v1/peppol/sendCreate and send in one call"send": false creates a real numbered invoice without sending, and still needs the authorisation and remaining quota
POST /api/v1/peppol/invoices/{id}/sendSend an existing invoiceA credit note id returns 404
POST /api/v1/peppol/credit-notes/{id}/sendSend a credit noteGoes out as a UBL CreditNote (type 381); an invoice id returns 404
Quotes, receiptsNoneNot Peppol documents

Peppol BIS accepts six attachment types: PDF, PNG, JPEG, CSV, XLSX and ODS, and FPS Finance states that attachments travel with the invoice, not separately by email. Take attachment_ids from attachments[] in GET /api/v1/invoices/{id}; omit the field to attach every file, send [] for none. An id that matches nothing is silently ignored.

Make retries safe

MechanismScopeLifetimeIdentical retryDifferent content
Idempotency-Key headerOne API key; POST operations that document it24 hoursOriginal response, header Idempotent-Replay: true409 IDEMPOTENCY_KEY_REUSED
external_id on invoices and credit notesCompany, Integration ID, document typeNo expiry; survives rotationFirst completed response409 EXTERNAL_ID_REUSED
external_id on prepayments, payments, refundsCompany and Integration ID, across invoicesNo expiry; survives rotationOriginal movement, 200, "replayed": true409 EXTERNAL_ID_REUSED

Use both. PATCH, PUT and DELETE have no response replay. For documents, OrdoGrid fingerprints the whole creation body as sent: a changed note or email, an extra optional field, or 8 instead of "8" is different content, so store the body you sent and replay it unchanged. For movements, amount, currency, method, occurred_at (compared in UTC) and reference count.

After a timeout or a lost response:

  1. Look up the identity with GET /api/v1/invoices/lookup?external_id=..., GET /api/v1/credit-notes/lookup?external_id=... or GET /api/v1/invoices/payments/lookup?external_id=....
  2. Found: use that record. 404: retry the identical body.
  3. 409 EXTERNAL_OPERATION_IN_PROGRESS: another request is creating it; wait, then retry the identical body (an interrupted attempt's lease ends after two minutes).
  4. 502 DOCUMENT_CREATED: saved, but the PDF or attachments were not completed; retry the same external_id and body.
  5. Never switch to a new external_id because a response was lost.

PEPPOL_TRANSMISSION_UNCERTAIN means OrdoGrid cannot confirm whether the document left: read its status and check with OrdoGrid support before sending again, because a timeout does not prove failure and Peppol does not flag a second copy as a duplicate, so the customer's software may book it twice.

Rate limits apply per key and minute: read X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset, and on 429 RATE_LIMITED wait for Retry-After. Page lists with limit (at most 100) and offset until you have every row. Branch on the error code, never on message.

Worked example: a counter sale with a card deposit

Bureau Plus SRL, an office-supplies shop in Namur, connects its till with the key POS Namur (Integration ID pos-namur). On Friday 2 October 2026 at 10:15, Cabinet Lemaire SRL, an accounting firm registered for VAT under BE0123456749, takes 8 ink cartridges at €12.50 each including 21% VAT, pays €40.00 by card and will pay the rest by transfer.

1. GET /api/v1/peppol/participants/BE0123456749 returns "registered": true and "participant_id": "0208:0123456749".

2. The till creates the invoice with the ticket as identity:

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": "Cabinet Lemaire SRL", "vat_number": "BE0123456749",
    "address": {"street": "Rue de Fer 12", "city": "Namur", "postal_code": "5000", "country": "BE"}},
  "currency": "EUR", "issue_date": "2026-10-02", "due_date": "2026-11-02",
  "purchase_order": "LEM-2026-118",
  "items": [{"description": "Ink cartridge XL black", "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": "Till 2 / ticket 0187"}]
}

3. OrdoGrid calculates:

StepCalculationResult
Agreed amount8 × €12.50€100.00
Net amount€100.00 ÷ 1.21 = €82.6446…, rounded€82.64
VAT at 21%€82.64 × 21% = €17.3544, rounded€17.35
Legal total (totals.gross)€82.64 + €17.35€99.99
Rounding (totals.rounding, BT-114)€100.00 − €99.99+€0.01
Owed before the deposit (totals.payable, document_total)€99.99 + €0.01€100.00
Amount due (BT-115, outstanding)€99.99 − €40.00 + €0.01€60.00

The 201 response carries the assigned number, say F-2026-0412, and:

{
  "external_id": "pos-ticket-2026-0187", "integration_id": "pos-namur",
  "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 are JSON numbers and settlement values decimal strings: compare both as decimals. The deposit is already inside payments; never add prepayments to it. In the app the Settlement panel shows Invoice total €100.00, Prepayments €40.00, Payments (including prepayments) €40.00 and Outstanding €60.00. The cartridges change hands at the till, so the €40.00 is a part payment; a deposit taken before delivery makes VAT due on receipt and needs an invoice by the 15th of the following month (advance invoices).

4. POST /api/v1/peppol/invoices/{id}/send with an empty body. The UBL carries €0.01 as rounding (BT-114) and €60.00 as amount due (BT-115), as rule BR-CO-16 requires. Bureau Plus stores the peppol_document_id.

5. On Monday 12 October 2026 the bank shows €60.00 from Cabinet Lemaire. POST /api/v1/invoices/{id}/payments with external_id bank-2026-10-12-07, amount "60.00", method bank_transfer, occurred_at 2026-10-12T09:30:00+02:00 returns 201, outstanding "0.00" and status "settled".

6. The till, back online, re-sends the deposit pos-tender-2026-0187-1 with identical fields to the same payments route: OrdoGrid returns the original prepayment with 200 and "replayed": true, and payments stays "100.00".

Mistake in this saleResultFix
"unit_price": "12.50" with "prices_include_vat": true, no price_basis€100.00 net + €21.00 VAT = €121.00, €21.00 too muchSend price_basis and source_unit_price
Deposit "40.004", or occurred_at without offsetINVALID_AMOUNT_PRECISION, INVALID_OCCURRENCE_TIMERound to the cent; add +02:00
Transfer of €60.50 recorded in fullOVERPAYMENT, nothing recordedRecord €60.00; settle the €0.50 outside this invoice
Retry rebuilt with "quantity": 8 instead of "8"409 EXTERNAL_ID_REUSEDReplay the stored body

Build an acceptance pack before go-live

Every call creates real, numbered documents and every send reaches the real network. Run the pack on real transactions with a pilot customer who knows about the pilot, keep amounts small, and correct mistakes with credit notes, via Peppol when the invoice went via Peppol.

#CaseExpected result
1Net prices at each VAT rate you useNet, VAT and total equal your source to the cent; number in the company's series
2VAT-inclusive prices (worked example)rounding 0.01, payable 100.00
3Negative rounding: 10 × €12.50 incl. 21% VATNet €103.31, VAT €21.70, legal total €125.01, rounding −€0.01, payable €125.00
4Partial credit noteSent as UBL CreditNote; outstanding drops; crediting more than remains returns CREDIT_CAPACITY_EXCEEDED
5Credit note on a paid invoice, then the refundrefund_due appears, then returns to zero
6Deposit, payment, replayed depositThe deposit is never counted twice
7Create retried within and after 24 hours; response dropped after commitSame invoice and number every time; lookup finds it
8Changed body under an existing external_id409 EXTERNAL_ID_REUSED; nothing created
9Customer not on Peppolregistered: false; fallback channel used; no Peppol attempt
10Delivery and evidenceStatus read until delivered; XML fetched with peppol_document_id
11Key replaced with the same Integration IDLookup finds the earlier invoices
12Missing scope, partial address, unknown field403 INSUFFICIENT_SCOPE; 400 naming the field

Have the controller sign the expected amounts before the run and release only when every difference is explained.

Edge cases and common mistakes

MistakeConsequenceCorrect action
Till tender numbers that restart every day (1, 2…) used as external_id409 EXTERNAL_ID_REUSED from the second day, because movement ids are unique across all invoicesBuild ids that never repeat, such as year plus ticket number, as in the example
ERP numbers sent in number while users also create invoices in the appGaps or 409 DOCUMENT_NUMBER_TAKEN in the same seriesLet one system own the invoice series; omit number
Amounts changed with PATCH after a payment or a Peppol sendDOCUMENT_FINANCIAL_CONTENTS_LOCKEDCredit note and, if needed, a new invoice
Credit note for a Peppol invoice sent only as a PDFNot the structured format the law requiresSend it with POST /api/v1/peppol/credit-notes/{id}/send
Traité or “delivered” read as approvalChasing payment on an invoice the buyer rejectedWatch Invoice Responses on the Peppol page; they only reach OrdoGrid when the company receives there (Activer la réception), and buyers are not obliged to send one
PDF emailed as well as sent on PeppolThe customer may book it twicePeppol alone when the customer receives there; Belgian Peppol service providers recommend avoiding dual sending

Evidence to keep

  • Key register: name, Integration ID, permissions, owner, creation and rotation dates; never the secret.
  • Contract snapshot: the redacted /me response with its date and contract_version, plus the versioned mapping and the signed expected amounts.
  • Per transaction: external_id, OrdoGrid id and number, peppol_document_id, the exact body sent, the response code and any refusal code.
  • Refusal catalogue: for each code met during acceptance, a sanitised request, the code and the recovery chosen. After a mapping change, rerun the retry cases: a new field changes the body of documents still waiting for a retry.
  • Documents and cash: the exchanged XML and PDF, the issued PDF (GET /api/v1/invoices/{id}/pdf?view=original), a dated statement when useful (?view=current), and the movement history (GET /api/v1/invoices/{id}/payments).

Belgian law requires invoices to be kept for 7 years from 1 January of the year after issue (art. 60 VAT Code, as amended by the Law of 18 December 2025), and FPS Finance strongly recommends keeping the original XML. OrdoGrid archives each transmission's exact XML and PDF with their hashes, but it is not a legal archiving service: keep your own copies.

FAQ

Is there a sandbox or test mode?

No. Every call acts on real company data and every send reaches the real Peppol network; "send": false still creates a real numbered invoice. Test with real transactions and a pilot customer, and correct mistakes with credit notes.

What happens to my integration when I rotate a key?

The old secret stops working immediately, so deploy the new one at once. Rotation keeps the Integration ID, permissions and expiry date, so lookups and duplicate protection keep working.

Why do I get EXTERNAL_ID_REUSED when I only changed a note?

OrdoGrid fingerprints the whole creation body, not only the amounts. Replay the stored body. If the business event really changed, treat it as a correction: a credit note and, if needed, a new invoice with a new external_id.

Can the API email an invoice to a customer who is not on Peppol?

No, the public API has no email operation. Fetch the PDF with GET /api/v1/invoices/{id}/pdf and send it through your own channel, or let a user send it from the app with Envoyer.

Does a delivered status mean the customer accepted the invoice?

No, it means network delivery. Acceptance or rejection only comes through an Invoice Response, which buyers are not obliged to send, and payment only through a recorded movement.

Can my system receive supplier invoices through the API?

Yes, with peppol:read, through GET /api/v1/peppol/inbox and the XML route, provided the company receives through OrdoGrid. OrdoGrid does not book or approve supplier invoices; that stays in your accounting system.

Sources and references