Skip to main content

Overview

A sandbox company cannot be converted into a production company. Test mode is fixed when a company is created. To go live, you create a separate production company and repeat the configuration that belongs to a company: the API key, the Peppol ID and the webhooks. The API host does not change. Sandbox companies and production companies both use https://api.e-invoice.be. See Test mode and sandbox companies.
A production company sends documents on the Peppol network. Each document that you send from a production company reaches a real recipient.

What changes and what stays the same

Checklist

1

Create the production company

Sign in to app.e-invoice.be and create a company that is not a sandbox company. Complete the company verification steps that the app shows.The sandbox company stays available. Keep it for development and for regression tests.See Test mode and sandbox companies for the differences between the two company types.
2

Confirm the Peppol ID of the company

Call GET /api/me/ with the production API key and read peppol_ids. The sender of each document must be one of these Peppol IDs. If it is not, POST /api/documents/ returns 406 and POST /api/documents/{document_id}/send returns 409. The two responses have the same detail, for example Derived sender '0208:0999123457' is not in tenant peppol_ids. For self-billing documents, the Peppol sender is the customer, so the check applies to the customer_* fields.Example: E-INVOICE BV has peppol_ids ["0208:1018265814"] and makes a self-billing invoice for its supplier OpenPeppol VZW. Put the VAT number of E-INVOICE BV in customer_tax_id:
If the company must receive documents, it must also be registered on the Peppol network. Check the registration with GET /api/validate/peppol-id. See Look up Peppol participants and the Peppol ID entry in the glossary.
3

Copy the production API key

The app creates the API key with the company. Open API settings in the production company and copy the key. Store the key in a secret manager and load it from the environment variable E_INVOICE_API_KEY. Do not use the sandbox key in production, and do not use the production key in tests.See Authentication.
4

Create the webhooks again

Webhooks belong to one company. The webhooks of the sandbox company do not exist in the production company. Create each webhook again with POST /api/webhooks/.The server generates a new secret for each webhook. Store the new secret and use it to verify the X-Signature header. A signature check that uses the sandbox secret fails for production events.See Webhooks.
5

Check the plan and the credit balance

Call GET /api/me/ and read plan and credit_balance. A sandbox company has no billing, so this is the first time that these values apply to your integration.See Usage statistics and credits.
6

Send with explicit Peppol routing

Set sender_peppol_scheme, sender_peppol_id, receiver_peppol_scheme and receiver_peppol_id on each call to POST /api/documents/{document_id}/send. Explicit routing prevents delivery failures that occur when the API derives a Peppol ID from the company identifiers in the document.Example request line:
The scheme and the identifier are two separate parameters. Do not put 0208:1018265814 in sender_peppol_id: the API does not split the value, and the send fails with 409. Example: sender_peppol_scheme=0208&sender_peppol_id=0208:1018265814 gives the detail Derived sender '0208:0208:1018265814' is not in tenant peppol_ids.See Create e-invoices.
7

Check the recipient before each send

Call GET /api/validate/peppol-id for the recipient. The response contains is_valid, dns_valid, business_card_valid and supported_document_types. Send only when the recipient is registered and supports the document type.In a sandbox company this check has no effect on delivery, because documents go to email. In a production company the document can only be delivered to a recipient that is registered on the Peppol network.See Look up Peppol participants.
8

Handle rate limits and failed documents

Four endpoints have a rate limit for each API key: POST /api/documents/, POST /api/documents/ubl, POST /api/validate/json and POST /api/validate/ubl. When you exceed the limit, the endpoint returns 429. The Retry-After header gives the length of the rate-limit window in seconds. It does not give the time until the counter resets. Wait that number of seconds before you send the request again.A document that cannot be delivered gets the state FAILED. Subscribe to the document.sent.failed and document.received.failed events, and make sure that an operator sees these documents.See Errors and troubleshooting and Document lifecycle and delivery tracking.
9

Send one real document

Send one document from the production company to a participant that you know, for example a company of your own organisation or a partner who expects the test. Then call GET /api/documents/{document_id} and confirm that state is SENT. The timeline (GET /api/documents/{document_id}/timeline) shows the transmission as a send_success event. A failed transmission shows a send_failed event.See Document lifecycle and delivery tracking.
10

Set up monitoring

Monitor these items from the first production day:
  • Webhook deliveries that fail. GET /api/webhooks/{webhook_id}/history shows the delivery history of a webhook.
  • Documents in the state FAILED.
  • Your usage and the value of credit_balance from GET /api/me/.
See Webhooks, List, filter and manage documents and Usage statistics and credits.

Frequently asked questions

No. Test mode is fixed when the company is created. Create a separate production company.
The host, the endpoints and the payloads are identical. The API key and the webhook secrets change. Recipient checks and the handling of FAILED documents become important, because documents go to real recipients.
No. Each company has its own documents, webhooks and API key.
No. GET /api/me/ does not return the test mode of the company. Label each key when you store it, so that a sandbox key and a production key cannot be confused.

Next Steps

Test mode and sandbox companies

Compare sandbox companies and production companies

Errors and troubleshooting

Handle error responses and rate limits

Document lifecycle and delivery tracking

Follow a document from draft to delivery

Webhooks

Receive events for sent and received documents