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. For self-billing documents, the same check applies to the receiver.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

Create the production API key

Copy the API key of the production company from its settings in the app. 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.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

The document write endpoints return 429 when the rate limit for the API key is exceeded. Read the Retry-After header and 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}/timeline and confirm that the document reaches the state SENT.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