> ## 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.

# Test mode and sandbox companies

> Use a sandbox company to build and test your integration on the single API host without Peppol traffic.

## 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](/glossary#production-company) sends and receives documents on the Peppol network.
* A [sandbox company](/glossary#sandbox-company) runs in [test mode](/glossary#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:

| Term | Meaning |
| - | - |
| **Sandbox company** | A company that runs in test mode. It has its own API key and does not exchange documents on the Peppol network. |
| **Production company** | A company that sends and receives documents on the Peppol network. |
| **Company** | The unit that sends and receives documents in the app and in the API. A company is a sandbox company or a production company. |
| **Tenant** | The name of a company in the Admin API and in the `tenant_id` field of a webhook payload. A tenant is a company that a [reseller](/reseller-programme) manages. |
| **Organisation** | The account of a reseller. An organisation has one Admin API key and manages many tenants. |
| **Contact email address** | The email address of the company (the `company_email` field). In test mode, the API sends each outbound document to this address. |
| **Test mode** | The operating mode of a sandbox company. It is set when you create the company and you cannot change it. |

## API host

Use one base URL for all calls:

```bash theme={null}
# .env
E_INVOICE_API_KEY=your_api_key
E_INVOICE_BASE_URL=https://api.e-invoice.be
```

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](/glossary#simulate-inbound) (see [Testing received documents](#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.

<Note>
  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.
</Note>

## 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

<Steps>
  <Step title="Sign in">
    Sign in to the app at [app.e-invoice.be](https://app.e-invoice.be).
  </Step>

  <Step title="Start the creation">
    Open **Companies** and select **Create sandbox company**.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Copy the API key">
    Open **API Settings** in the sandbox company and copy the API key.
  </Step>
</Steps>

### What a send does in test mode

<Steps>
  <Step title="Create the document">
    `POST /api/documents/` operates as it does for a production company. The document gets the `DRAFT` state.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Receive the webhook">
    The `document.sent` webhook is sent as it is for a production company.
  </Step>
</Steps>

<Warning>
  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.
</Warning>

## 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](/guides/receiving-documents).

<Warning>
  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.
</Warning>

### 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](mailto: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](/admin-api#simulate-an-inbound-document) in the Admin API.

## Recommended development workflow

<Steps>
  <Step title="Create a sandbox company">
    Use its API key with `https://api.e-invoice.be`.
  </Step>

  <Step title="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](/guides/validation).
  </Step>

  <Step title="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.
  </Step>

  <Step title="Go live">
    Create a separate production company and use its API key. You cannot convert a sandbox company. Follow the [go-live checklist](/going-live).
  </Step>
</Steps>

## Frequently asked questions

<AccordionGroup>
  <Accordion title="How do I test my integration?">
    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.
  </Accordion>

  <Accordion title="Which API host do I use?">
    There is one host: `https://api.e-invoice.be`. Use it with a sandbox company for tests and with a production company for production.
  </Accordion>

  <Accordion title="Can I convert a sandbox company into a production company?">
    No. The type of company is set at creation. Create a production company and use its API key.
  </Accordion>

  <Accordion title="How do I move from tests to production?">
    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](/going-live).
  </Accordion>

  <Accordion title="Can I test webhooks with a sandbox company?">
    Yes. Webhooks operate the same in test mode. You get `document.sent` after a send (by email) and `document.received` after a Simulate inbound.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Make your first API call.
  </Card>

  <Card title="Validation during development" icon="circle-check" href="/guides/validation">
    Validate invoice payloads during development.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/essentials/webhooks">
    Receive notifications for document events.
  </Card>

  <Card title="Go-live checklist" icon="list-check" href="/going-live">
    Move from a sandbox company to a production company.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.