Skip to main content

​
Overview

e-invoice.be has one API host: https://api.e-invoice.be. There is no separate host for development or tests. The company that you authenticate as controls what a send does:
  • A production company sends and receives documents on the Peppol network.
  • A sandbox company runs in test mode. The API sends each document to an email address, and you simulate inbound documents. No Peppol traffic occurs.
Each company has its own API key. To change from tests to production, you change the API key. The base URL and your code stay the same.

​
Terminology

The documentation uses these terms:

​
API host

Use one base URL for all calls:
Put the API key of a sandbox company in E_INVOICE_API_KEY during development. Put the API key of a production company there when you go live.

​
Test mode

When a company is in test mode:
  • The API does not send documents on the Peppol network. It sends an email with the UBL XML as an attachment to the contact email address of the company.
  • The company does not receive documents from the Peppol network. You add inbound documents with Simulate inbound (see Testing received documents).
  • Peppol registration actions in the Admin API are simulated.
  • Document creation, validation, webhooks, the inbox, the outbox and all other endpoints operate as they do for a production company.
Test mode is set when the company is created and does not change. You cannot convert a sandbox company into a production company, or a production company into a sandbox company. Create the type of company that you need.

​
Sandbox companies

A sandbox company is a company in test mode. In the app and in the API it behaves as a production company does: it has settings, documents, webhooks and an API key.
  • Test mode is permanent. Outbound documents go to the contact email address and inbound documents are simulated.
  • Synthetic identifiers. The app suggests a Belgian VAT number that is not real. You can change it. The app does not do a KBO, VIES, email, telephone or payment verification.
  • Webhooks operate. The document.sent and document.received events are sent as they are for a production company.
  • No billing. A sandbox company uses no credits and has no plan.
  • Own API key. Use the key as the Bearer token for https://api.e-invoice.be.

​
Create a sandbox company

1

Sign in

Sign in to the app at app.e-invoice.be.
2

Start the creation

Open Companies and select Create sandbox company.
3

Fill in the details

The suggested values are safe placeholders and you can change them. Select Suggest valid VAT to get a synthetic Belgian VAT number. Enter a Contact email that you can read: this address receives the documents that you send.
4

Copy the API key

Open API Settings in the sandbox company and copy the API key.

​
What a send does in test mode

1

Create the document

POST /api/documents/ operates as it does for a production company. The document gets the DRAFT state.
2

Send the document

POST /api/documents/{document_id}/send changes the state to TRANSIT. The API then sends an email with the UBL XML to the contact email address of the company and changes the state to SENT. No Peppol transmission occurs.
3

Receive the webhook

The document.sent webhook is sent as it is for a production company.
If the sandbox company has no contact email address, the send request returns 400. Make sure that the company has a contact email address before you send.

​
Testing received documents

Use Simulate inbound to test the inbox. It puts a UBL document in the inbox of your sandbox company as if the document came from the Peppol network. The document appears in GET /api/inbox/ with the RECEIVED state, and the document.received webhooks are sent. For the requests that read the inbox, see Receive documents.
You cannot put a document in your own inbox with a send to yourself. In test mode, a send goes to email, so the document gets the SENT state and does not come back in the inbox. The API also ignores the direction field in POST /api/documents/: this endpoint always creates OUTBOUND drafts. Simulate inbound is the only method to fill the inbox of a sandbox company.

​
In the app

In a sandbox company, open Inbox and select Simulate inbound. Then do one of these:
  • Add the built-in sample invoice.
  • Upload your own UBL XML file. The app replaces the receiver identifiers with the identifiers of your company, so that the document is addressed to you.
If the Simulate inbound button does not show, make sure that the active company is a sandbox company, or contact support@e-invoice.be.

​
With the Admin API

A reseller can do the same for each sandbox company that the organisation manages. See Simulate an inbound document in the Admin API.

​
Recommended development workflow

1

Create a sandbox company

Use its API key with https://api.e-invoice.be.
2

Validate your payloads

Use POST /api/validate/json while you develop. Test more than one invoice scenario and examine the tax rates and the totals. See Validation during development.
3

Test the full flow

Create and send documents and read the UBL in the email. Use Simulate inbound to test the receive flow. Make sure that your webhook handler processes the events.
4

Go live

Create a separate production company and use its API key. You cannot convert a sandbox company. Follow the go-live checklist.

​
Frequently asked questions

Create a sandbox company in the app and use its API key with https://api.e-invoice.be. No document goes to the Peppol network.
There is one host: https://api.e-invoice.be. Use it with a sandbox company for tests and with a production company for production.
No. The type of company is set at creation. Create a production company and use its API key.
Replace the API key of the sandbox company with the API key of a production company. The base URL and your code stay the same. The API then sends documents on the Peppol network. See the go-live checklist.
Yes. Webhooks operate the same in test mode. You get document.sent after a send (by email) and document.received after a Simulate inbound.

​
Next Steps

Quickstart

Make your first API call.

Validation during development

Validate invoice payloads during development.

Webhooks

Receive notifications for document events.

Go-live checklist

Move from a sandbox company to a production company.