> ## Documentation Index
> Fetch the complete documentation index at: https://docs.e-invoice.be/llms.txt
> Use this file to discover all available pages before exploring further.
# Environments
> Understanding the API host, test mode, and sandbox companies
## 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.
```bash theme={null}
# .env
E_INVOICE_API_KEY=your_api_key
E_INVOICE_BASE_URL=https://api.e-invoice.be
```
## 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](#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](https://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](mailto: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](/admin-api#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
Get started with your first API call
Learn how to validate invoices during development
Create and send your first e-invoice
Set up webhook notifications