- An account at app.e-invoice.be.
- A terminal with
curl(or Node.js 18+, Python withrequests, PHP with the cURL extension, or .NET 6+).
A sandbox company needs no VAT verification, no contact verification and no payment. It is free to use. See Test mode and sandbox companies for the details of test mode.
1
Create an account
Sign up at app.e-invoice.be and log in.
2
Create a sandbox company
- Open Companies and select Create sandbox company.
- Keep the country Belgium and select Suggest valid VAT number to get a synthetic Belgian VAT number, for example
BE0999123457. - Make sure that Contact email is an address that you can read. The API sends the test document to this address. In the API, this address is the
company_emailfield. - Create the company, open API settings and copy the API key of the sandbox company.
3
Check the API key
Request the details of the company that owns the key.The API returns
200 OK:smp_registration and smp_registration_date are legacy fields. They do not show if your Peppol ID is published: smp_registration is usually false, also for a company with a published Peppol ID. To check the registration, use GET /api/validate/peppol-id. See Look up Peppol participants.The vendor of each document that you create must be a Peppol ID of your company. For a Belgian company, the Peppol ID is 0208: followed by the VAT number without the BE prefix. Example: peppol_ids ["0208:0999123457"] gives the vendor VAT number BE0999123457. Keep this VAT number in a second environment variable:4
Write the invoice
Save the invoice as
invoice.json. The command puts your vendor VAT number in the file. The customer is OpenPeppol VZW (BE0848934496).Replace vendor_name and vendor_address with the name and the address of your sandbox company. The UBL XML in the test email then shows your company as the vendor.5
Validate the invoice
Validation is not a separate mandatory call.
POST /api/documents/ rejects a payload that does not pass the same rules. Use POST /api/validate/json while you develop, because it returns all rule failures and the generated UBL.201 Created. This call does not store a document. The ubl_document field contains the full UBL XML; it is shortened here.is_valid is false, read the issues array, correct invoice.json and validate again.If a total or a VAT rule is not correct, the API returns 406 Not Acceptable and no issues array. The detail text starts with Document is not valid: and gives each failure. Example: add "subtotal": 900.00 to invoice.json. The calculated subtotal is 1000.00, thus the detail contains Subtotal mismatch. See Validation during development.6
Create the document
Send the same file to The API returns Keep the
POST /api/documents/. The API stores the document in the state DRAFT.201 Created with the complete document. The response is shortened here.id for the next step:7
Send the document
Send the draft. The request has no body.The API returns
200 OK with the document. The state is now TRANSIT, because delivery runs in the background. The response is shortened here.If
company_email is empty, this call returns 400 with the message Tenant is in test mode but no company email is set. The state of the document is then SENT, but the API sends no email. Add a contact email address in the company settings, then create and send a new document.8
Check the result
Open the mailbox of the contact email address of the sandbox company. You get an email with the subject The API also sends a
Document sent via Peppol // e-invoice.be [TEST-MODE] and the UBL XML as an attachment. This is the file that a production company transmits on the Peppol network.When the email is sent, the state of the document changes to SENT:document.sent event to each webhook that subscribes to it. See Webhooks.Go live
Test mode is fixed when a company is created. To send documents on the Peppol network, create a production company and use its API key. The API host and your code stay the same. Follow the go-live checklist before you send the first production document. If you prefer a typed client, see SDKs. If you prefer a terminal, see the peppol CLI.Next Steps
Go-live checklist
Create a production company and send on the Peppol network
Test mode and sandbox companies
Learn how test mode and sandbox companies work
Create e-invoices
Use all invoice fields, payment details and tax options
Webhooks
Get a notification for each sent and received document