Skip to main content

​
Overview

e-invoice.be runs on a single API host, https://api.e-invoice.be. There is no separate staging or development host — you develop, test, and run in production against the same URL. What changes is the mode your workspace operates in:
  • Production — documents are transmitted over the real Peppol network.
  • Test mode — documents are never sent over Peppol; sends are diverted to email and inbound documents are simulated, so you can build and verify your integration safely.
The easiest way to get a test-mode workspace is to create a sandbox company (see below).

​
API Host: api.e-invoice.be

Base URL: https://api.e-invoice.be This is the only API host. Use it for everything:
  • Real Peppol network transmission (for production companies)
  • Development and testing (for sandbox companies / test mode)
  • Stable, released features
Configure your integration with a single base URL and switch behaviour by using a production or a sandbox company’s API key — not by changing hosts.

​
Test Mode

Test mode is an operating mode for a workspace (tenant) that prevents any real interaction with the Peppol network. When a workspace is in test mode:
  • Documents are not sent via Peppol. Instead, an email containing the UBL XML that would have been transmitted is sent to the workspace’s contact email.
  • Inbound documents are never received from the real network, but can be injected with the Simulate inbound feature (see Testing Received Documents).
  • Peppol registration actions (Admin API) are simulated rather than performed on the live network.
  • Everything else works exactly as in production: document creation, validation, webhooks, inbox/outbox, and all API endpoints.
Test mode is fixed for the lifetime of a workspace — a company is either a real (production) company or a sandbox company, decided when it is created. There is no switch to convert one into the other; instead, create the type of company you need.

​
Sandbox Companies

A sandbox company is a company whose workspace runs in test mode. It behaves like any other company in the app and the API — company switcher, settings, documents, webhooks, API key — but nothing it does touches the Peppol network. Sandbox companies are ideal for building an integration, running a hackathon, or evaluating the platform. Key characteristics:
  • Test mode always on — outbound sends go to email, inbound is simulated, no Peppol traffic. This is immutable.
  • Synthetic identifiers — a placeholder Belgian VAT number is assigned automatically (you can edit it). KBO/VIES, email, phone, and payment verification are skipped.
  • Full webhook machinery — document.sent and document.received webhooks fire exactly as they do in production, so you can exercise your complete integration.
  • No billing — sandbox companies don’t consume credits and have no plan; credit, top-up, and usage screens are hidden.
  • Own API key — each sandbox company has its own API key, just like a real company. Use it as the Authorization: Bearer token against https://api.e-invoice.be.

​
Creating a Sandbox Company

  1. Sign in to the app at app.e-invoice.be.
  2. Open the Companies view and choose Create sandbox company.
  3. Fill in the details. The suggested country and VAT number are safe placeholders and can be edited; click Suggest valid VAT to generate a synthetic Belgian VAT number.
  4. Open the new sandbox workspace and copy its API key from settings.
You can now point your integration at https://api.e-invoice.be using the sandbox API key and develop against the full API without sending anything over Peppol.

​
How Sends Behave in Test Mode

When you send a document from a sandbox company (or any test-mode workspace):
  1. Document creation: Works exactly the same as production.
  2. Document sending (POST /api/documents/{id}/send):
    • The document is validated and converted to UBL XML.
    • State transitions: DRAFT → TRANSIT → SENT.
    • The UBL XML is attached to an email sent to the workspace’s contact email.
    • No Peppol transmission occurs.
  3. Webhooks and everything else: Operate normally.

​
Testing Received Documents

To test incoming documents (inbox functionality), use the Simulate inbound feature. It injects a UBL document into your sandbox company’s inbox exactly as if it had been received over Peppol — the document lands in GET /api/inbox/ in the RECEIVED state, and any document.received webhooks you have configured fire normally.
You cannot put a document in your own inbox by sending one to yourself. In test mode, sending is diverted to email rather than transmitted over Peppol, so a self-addressed document reaches SENT but never loops back into the inbox. The direction field on POST /api/documents/ is also ignored — that endpoint always creates OUTBOUND drafts. Simulate inbound is the only way to populate the inbox without a real Peppol receipt.

​
Using the app

In a sandbox workspace, open Inbox and click Simulate inbound. You can either:
  • Inject a built-in sample invoice with one click, or
  • Upload your own UBL XML — the receiver identifiers are automatically substituted with your company’s, so the document is addressed to you.
The simulated document then appears in your inbox, and you can exercise your complete receive-side integration (listing, webhooks, downstream processing) without needing a second Peppol participant. If you don’t see the Simulate inbound option, confirm you are in a sandbox company, or contact support@e-invoice.be.

​
Using the Admin API (resellers)

Resellers with an organization API key can drive the same behaviour programmatically for any of their sandbox tenants via Simulate an Inbound Document (POST /api/admin/tenants/{tenant_id}/simulate-inbound).

​
Recommended Development Workflow

  1. Create a sandbox company and use its API key against https://api.e-invoice.be.
  2. Validate thoroughly — use POST /api/validate/json extensively; test multiple invoice scenarios and verify calculations, tax rates, and totals.
  3. Test end-to-end — create and send documents (verify the UBL email in test mode), use Simulate inbound to test receiving, and confirm your webhook handling.
  4. Go to production — create (or use) a real company and switch your integration to that company’s API key. No code changes are needed beyond the API key; real documents are then transmitted over Peppol.

​
Frequently Asked Questions

​
How do I test my integration?

Create a sandbox company in the app and use its API key against https://api.e-invoice.be. It runs in test mode, so you can build and verify everything without sending real documents over Peppol.

​
Which API host should I use?

There is only one: https://api.e-invoice.be. Use it for both testing (with a sandbox company) and production (with a real company).

​
Can I convert a sandbox company into a real one?

No. Whether a company is a sandbox (test mode) or a real (production) company is fixed at creation. When you’re ready for production, use a real company and switch to its API key.

​
How do I move from testing to production?

Point your integration at a real company’s API key instead of the sandbox one. The base URL and your code stay the same; documents are then sent via Peppol instead of email.

​
Can I test webhooks in a sandbox company?

Yes. Webhooks work identically in test mode and production. You’ll receive events for document state changes, including when documents are “sent” (via email in test mode, via Peppol in production) and received (via Simulate inbound in test mode).

​
Can I use different API keys for different applications?

Yes. Each company has its own API key, and you can create additional keys to isolate different applications.

​
Next Steps

Quickstart

Get started with your first API call

Validation

Learn how to validate invoices during development

Creating Invoices

Create and send your first e-invoice

Webhooks

Set up webhook notifications