Public API integration: company scope, financial mapping and acceptance
Build a company-scoped invoice integration using the live API contract, durable source identities, settlement values and structured Peppol transmission.
- Updated
- Content owner
- Integration team
- For
- Integration engineers · Solution architects · Technical finance owners
At a glance
Verify the key's company and capabilities, map structured financial data explicitly, and prove creation, retry, delivery and reconciliation before release.
Before you begin
- An authorised company API key owner
- Structured source documents and stable transaction identities
- An agreed field mapping and representative financial examples
What you will achieve
- A tested company-scoped integration contract
- Durable mapping between source and product identities
- A release pack covering retries, settlement and transmission evidence
On this page
The public API is a financial integration boundary. Build against its live contract and preserve source identities from the first prototype. A successful HTTP request is useful evidence, but an enterprise integration also needs to explain what it created, which company owns it and how recovery avoids duplication.
Discover the contract and company
Fetch GET /api/v1/openapi.json for the actual endpoint description. Start authenticated calls with GET /api/v1/me; verify company identity, integration namespace, supported operations, payment methods, currencies and tax capabilities. Keep the contract version and retrieval date with your mapping.
Create the key from Company → API keys using an authorised owner/admin. Its secret appears once; store it in your approved secret manager. Keys are company-scoped, so no company header can redirect a call to another tenant. App session cookies and the public API credentials are separate.
| Responsibility | Owner | Evidence |
|---|---|---|
| Company and scope choice | Company key owner | Redacted /me and scope inventory |
| Data/identity mapping | Integration engineer | Versioned field and ID mapping |
| Financial expectations | Controller | Approved amounts and tax cases |
| Recovery and monitoring | Integration operations | Replay and exception evidence |
| Release | Service owner | Acceptance decision and handover |
Grant only the needed operations
Use Authorization: Bearer … or the supported X-Api-Key header. Discover scopes at GET /api/v1/scopes. Document writes require their write scope. payments:write is required for cash movements and creation prepayments. Peppol send and Peppol read are independent.
POST /api/v1/peppol/send creates an invoice and can transmit it; it therefore needs invoices:write and peppol:send. Reading delivery evidence requires peppol:read. Verify company registration approval and plan quota separately from key permissions.
Map data with explicit authority
Keep a mapping table for source field, API field, type, transformation, authority and refusal handling. Addresses need street, city, postal code and country. Unknown fields are rejected, so do not send your entire source object. Omit invoice number when the company sequence should assign it.
Use decimal strings for cash amounts with supported currency precision. Record currency and timezone-aware occurrence time on movements. Do not silently truncate values, convert currencies or infer a payment from a source “paid” label without the confirmed movement.
Example source identity: an ERP order order-4711 becomes invoice external_id: order-4711 under integration namespace erp. A confirmed deposit has its own movement identity tender-4711-1. Keep those values stable through retries and key replacement.
Separate creation from exchange when useful
POST /api/v1/invoices creates the document. Send an existing invoice through POST /api/v1/peppol/invoices/{invoice_id}/send; credit notes use the separate credit-note path. Quotes and receipts have no Peppol send route.
The combined /peppol/send endpoint accepts structured invoice fields and optional supplied PDF. With send: false, it creates without network transmission, useful for a controlled creation check. It is not a sandbox and still creates a real invoice.
Peppol carries structured UBL; a supplied PDF is a companion, not data to be extracted. BIS Billing 3.0 publishes invoice and credit-note syntax. The product has no PDF-to-invoice OCR endpoint on this public surface.
Implement durable recovery
Send stable document/movement external_id values and a separate Idempotency-Key for retryable writes. HTTP idempotency is valid for 24 hours and scoped to the API key. Durable financial identities survive that window and key rotation.
After an uncertain create response, use external lookup or retry identical content. EXTERNAL_ID_REUSED means a changed creation payload or movement details reused an identity; investigate the original mapping and appropriate correction instead of assigning an arbitrary new ID. Peppol uncertain transmission needs provider reconciliation before resend.
Read lists through every page using the documented envelope. Branch on error code, not its prose message. Respect rate-limit headers and Retry-After on 429 responses.
Prove acceptance with financial examples
Cover an ordinary invoice, credit note, deposit, partial payment, completed refund, duplicate create retry, movement retry and lost response. Compare totals, source IDs, assigned number, settlement, delivery and archived XML/PDF separately.
For a €121 invoice with €40 deposit, assert payments €40 and outstanding €81. A later €81 payment settles it. Replaying the original deposit must return the same movement and leave payments €121. Never add prepayments to payments.
Retrieve issued and current PDF views deliberately: current is a dated settlement statement, while issued/original preserves the original rendering. The Peppol document identifier retrieves the exchanged XML/PDF; it differs from invoice and provider IDs.
Hand over the mapping, key owner, external-ID register, monitoring, reconciliation procedure and sanitized failure examples. Release only with unexplained financial differences resolved. Continue with integration reliability and month-end reconciliation.