Sandbox

Sandbox is an isolated test environment that lets you try B2Brouter (issue invoices, send documents, test the API) without touching real data, real recipients, or your subscription’s transaction count.

What is Sandbox

• A self-contained workspace with separate data (invoices, contacts, products, templates, API keys).
• Lets you run end-to-end tests before committing to a paid plan.
• Used to validate your API integration before deploying to production.
• Ideal for training, demos, and proof-of-concept work.

Simulated network behavior. By default, sends in sandbox succeed and the document reaches its final state (equivalent to production). In addition, sandbox can reproduce the full outbound lifecycle, including rejections and network errors, when you send to one of the documented test recipients below. No document ever goes out over the real network: the whole cycle is simulated inside B2Brouter.

Getting started

Create a Sandbox (web UI)

1. Sign in to B2Brouter.
2. Click the Developers button (lightning-bolt icon).
3. Click Create Sandbox.
4. Give the sandbox a name.
5. Maximum 5 sandboxes per account / integration group.

Enter and exit

• Click the open icon (↗) to enter sandbox mode.
• While you’re in it, a purple banner appears on every page.
• Click Exit Sandbox to return to production.

Using the API in Sandbox

API routing is driven entirely by the key:

• No separate sandbox URL or subdomain is needed.
• Use the standard B2Brouter API base: https://api.b2brouter.net/.
• Production keys start with prod_ (or with no prefix, for compatibility).
• Sandbox keys start with test_.

Pass the sandbox key via the X-B2B-API-Key header or the api_key query parameter.

Document lifecycle

Documents follow the same lifecycle as in production. With a normal recipient, the send reaches:

draft → sent → registered

With a test recipient (see below), sandbox continues the cycle according to the associated scenario, asynchronously (transitions arrive within a few seconds), so you can test how your system handles each outcome:

• Registered successfully: sent → registered
• Rejected: sent → registered → refused
• Network error (unregistered recipient): sent → error, with error_code = PEPPOL_NO_RECEIVER

Since transitions are asynchronous, if you poll you may see intermediate states in quick succession; your code must tolerate receiving them back to back. Webhooks fire on every transition, same as in production.

Simulating network responses (test recipients)

To test how your system reacts to a rejection or a network error, send to one of the predefined test recipients. They work like test cards: the outcome is determined by the recipient, not by any special parameter. Your sending code runs exactly as it would in production.

Every new sandbox already includes these contacts, created automatically (look for them in your contacts list), along with an active PEPPOL channel, so you can send without any prior setup.

Test contact	Channel	Scheme	Identifier (XIN)	Simulated outcome
Test PEPPOL — Registered	PEPPOL	GLN (0088)	9508397101047	sent → registered
Test PEPPOL — Refused	PEPPOL	GLN (0088)	9506215594996	sent → registered → refused
Test PEPPOL — No receiver	PEPPOL	GLN (0088)	9500047420799	sent → error (PEPPOL_NO_RECEIVER)

You can also create your own contacts with one of these identifiers: sandbox recognizes the outcome by the identifier, not by the specific contact.

Any other recipient (not listed here) follows the default path and succeeds at sent/registered.

Current scope of the simulation

The enriched lifecycle (registered/rejected/error) is available for PEPPOL invoices. Other document types and channels complete successfully (sent), and some cases only distinguish success/error. Not yet simulated: receiving inbound documents, order responses, or response artifacts from tax authorities (CSV/UPO). These will arrive in later phases.

What is simulated (not real)

• No emails are sent from sandbox.
• No real PEPPOL traffic, no document crosses the PEPPOL network, and the real SMP is never queried. Recipient registration and the network lifecycle are fully simulated inside B2Brouter.
• No real submissions to tax authorities, SII, TicketBAI, Verifactu, Chorus, and ZATCA are routed to the authority’s test endpoints or skipped.
• No payments are processed.

Watermark on documents

Invoices and quotes downloaded from sandbox carry a clear watermark: “Not valid — Test invoice generated from the B2Brouter Sandbox”.

Limitations

Not available in Sandbox:

• Real delivery of documents to PEPPOL, email, B2Bconnector, or SFTP.
• Real payment processing.
• Tax authority verification checks.
• Connections (Transport) tab disabled. The test PEPPOL channel already comes configured automatically: you don’t need to manage it to send to test recipients.
• B2Bconnector and SFTP channels.
• Account closure features.

Other restrictions:

• Profile changes (name, password, 2FA) must be made in production.
• API keys don’t cross environments (test_ keys only work in sandbox).
• Production data can’t be cloned into sandbox with a single click.

Webhooks

Webhooks fire from sandbox intentionally, since webhook delivery is one of the things integrators need to test. Sandbox and production webhooks are independent and configured separately.

Key differences from production

• Identity (user, password, 2FA) is shared between environments.
• All other data is isolated.
• Activity in sandbox does not consume subscription quota.
• All API-level features are available regardless of your contracted plan.