Sandbox

What is Sandbox Mode?

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

Each sandbox is a self-contained workspace with its own data: invoices, contacts, products, templates, and API keys all live separately from your production account. Anything you create in sandbox stays in sandbox; anything you create in production stays in production.

What Sandbox is for:

Trying B2Brouter end-to-end before committing to a paid plan.
Validating your API integration before pointing it at production.
Running training, demos, or proof-of-concept work without affecting your live data.
Walking documents through their lifecycle (draft → sent → registered) so your integration code can exercise the success path of the state machine.

Note. At the moment Sandbox simulates the happy path only. Send operations always succeed and documents always reach their final state — sandbox does not reproduce rejection responses, network failures, or other error conditions. Test those against your own staging infrastructure, not against B2Brouter Sandbox.

What Sandbox is not:

It's not a staging or pre-release version of B2Brouter. It runs the same code as production — only the data and outbound integrations differ.
It's not a backup or a copy of your production data. Sandboxes start empty (apart from a few starter records bootstrapped from your account) and are independent.

Getting Started

Create a sandbox (Web UI)

Sign in to B2Brouter.
Click the Developers button (lightning-bolt icon) in the header.
- If you don't have an eDocExchange subscription yet, this opens the integration banner directly — your first sandbox is created from there.
- If you already have eDocExchange, the Developers area includes a dedicated Sandbox section (box icon); open it.
Click Create Sandbox.
In the modal, give your sandbox a name. The default is your account name followed by "Sandbox" — change it if you'd like to manage several at once.
Click Create. Your new sandbox appears in the list.

After your first sandbox is created, the Developers entry point becomes the Sandboxes list for everyone — showing every sandbox associated with your account or integration group, with rows to open, rename, or delete each one.

You can have up to 5 sandboxes per account or integration group. The Create button is disabled once the limit is reached; delete an existing sandbox to free a slot.

Open a sandbox

In the Sandboxes list, click the open icon (↗) next to the sandbox you want to use. B2Brouter switches you into sandbox mode and lands on the API Keys page for that sandbox.

While you're in sandbox mode, a purple banner runs across the very top of every page reminding you which environment you're in. Every page you visit, every action you take — invoicing, contacts, settings — operates against the sandbox until you exit.

Exit a sandbox

Click Exit Sandbox in the purple banner. You return to your production account, and the banner disappears.

You can re-enter the same sandbox at any time from the Sandboxes list — sandboxes persist until you delete them.

Delete or rename a sandbox

From the Sandboxes list:

Rename: click the rename icon, edit the name inline.
Delete: click the delete icon. All data in that sandbox (invoices, contacts, API keys, etc.) is removed permanently.

Using the API in Sandbox

Sandbox routing is driven entirely by the API key. There is no separate sandbox URL, no sandbox. subdomain, and no environment header to set. Use the standard B2Brouter API base URL — https://api.b2brouter.net/ — and:

Production keys start with prod_ (or with no prefix for legacy keys).
Sandbox keys start with test_.

When you call an endpoint with a test_… key, your request is automatically served from the sandbox environment. When you call with a production key, it goes to production. The same endpoint, the same request body — the routing happens at the key.

Get a sandbox API key

Open the sandbox you want to use (Web UI, see §2.2).
You land on its API Keys page automatically. If not, navigate there from the menu.
Generate or copy the API key. It will start with test_.

Pass that key in the X-B2B-API-Key header (or the api_key query parameter, if your client only supports query params) on every request you want routed to sandbox.

What works

Every API endpoint you'd call in production also works in sandbox: creating invoices, contacts, integration groups, sending documents, fetching states, webhooks, exporting XML, and so on. Behaviour is identical except for the simulated outbound calls described below.

Webhooks

Webhooks do fire from sandbox. This is intentional — webhook delivery is something integrators need to test. Configure a webhook URL on a sandbox integration group and you'll receive calls there as document states change. Production and sandbox webhooks are independent: they're configured separately and won't cross over.

Implications of Using Sandbox

Shared identity, separate data

Your user identity is shared between production and sandbox: the same login, password, 2FA setup, and recovery codes work in both. You sign in once and can move freely between environments.

Everything else is isolated between the two environments:

Independent in each environment — invoices, quotes, contacts, products, templates, integration groups and their configuration, API keys, webhooks, sandbox-side PEPPOL participants. Creating any of these in one environment does not make them visible in the other.
Production only — your real subscription and billing data, real PEPPOL participants (registered in PEPPOL Directory / SML / SMP), real connectors (SFTP, B2Bconnector).
Sandbox only — test data you create while in sandbox mode. None of it is ever published, billed, or transmitted.

Outbound integrations are simulated

When you send a document from sandbox (issue an invoice, send a despatch advice, generate a tax report), B2Brouter simulates the send and advances the document to its final state — without contacting any external system.

Concretely:

No emails are sent. Document delivery by email, password reset emails, error notifications: none of these leave sandbox.
No PEPPOL traffic. Your sandbox documents are not transmitted over the PEPPOL network. Your sandbox participants are not registered in PEPPOL Directory, SML, or SMP.
No real tax authority submissions. SII, TicketBAI, Verifactu, Chorus, ZATCA, and similar integrations either route to the authority's own test endpoints or are skipped entirely — nothing you do in sandbox reaches a production tax authority.
No payments. Stripe and other payment gateway calls are disabled.

The document still transitions through its normal lifecycle (draft → sent → registered, etc.) so your integration code can exercise the full state machine.

Watermark on downloaded documents

Invoices and quotes downloaded from sandbox carry a clear watermark — "No vàlida — Factura de proves generada des de B2Brouter Sandbox" — on every HTML preview and PDF. This makes test documents impossible to mistake for real ones.

No subscription gating

In sandbox, all eDocExchange-tier features are available regardless of your real subscription. Transaction count limits, user count limits, and product entitlement checks are lifted. Sandbox usage does not count toward your production subscription's transaction quota.

Sandboxes are throwaway

You can delete and recreate sandboxes freely. There's no charge for using them. Treat them as temporary — the only cap is the one on simultaneously-active sandboxes per owner (see §5.3).

Limitations

What's not available in Sandbox

Real document delivery — PEPPOL, email, B2Bconnector, and SFTP destinations are not connected. Outbound sends are simulated only.
Real payments — sandbox cannot process subscription payments. The Subscription / Payment / Billing sections are hidden inside sandbox.
Tax authority verification — NIF/census checks against the AEAT and similar authorities are skipped.
Connections (Transport) — the Connections tab is disabled in sandbox. Add and configure transports from production.
B2Bconnector and SFTP — these channels do not work against a sandbox environment. Use the API or the Web UI for testing.
Account closure — you cannot close or downgrade your account from inside sandbox. Exit to production first.

Profile changes happen in production

To change your name, password, language, timezone, email address, or 2FA configuration, exit sandbox first. These actions are intentionally disabled while you're inside sandbox: your identity is shared, so changes always apply globally and should be made from the production environment for clarity.

Quota: 5 sandboxes per owner

You can have up to 5 active sandboxes per account or integration group. Delete one to free a slot.

API keys don't cross environments

A test_… key is only valid against the sandbox environment, and a production key is only valid against production. If you send a sandbox key to an endpoint that resolves to production data (or vice versa), the request is rejected.

This also means: do not commit sandbox keys to your production configuration, and do not paste production keys into your sandbox tooling. Keep them separate.

Frequently Asked Questions

Will sandbox usage affect my subscription quota or invoice count? No. Sandbox traffic is fully separated from production billing. Documents you create in sandbox don't count toward transaction limits, and sandbox API requests don't appear in your production usage reports.

Can I import production data into a sandbox? Not as a one-click clone. Each new sandbox starts with the basic structure of your account (project, company, owner membership) and is otherwise empty. To populate it with realistic data, use the API or the Web UI's import flows just as you would in production.

How do I tell sandbox documents apart from real ones? Three signals:

The purple Sandbox banner is visible at the top of every page in sandbox mode.
Every downloaded invoice or quote carries a clear "No vàlida" watermark.
Sandbox API keys start with test_; production keys do not.

Can I share a sandbox with a teammate? Yes. Anyone who is a member of the owning account or integration group sees the sandbox in their Sandboxes list and can open it. There's no separate per-sandbox permission to manage.

What happens to my sandbox if I cancel my subscription? Sandboxes are tied to your B2Brouter account, not to a paid subscription tier. They remain available regardless of your subscription state.

Can I have a sandbox API key with restricted permissions? Yes — sandbox API keys support the same permission scoping (restricted keys, section capacities, etc.) as production keys.

Where to Go Next

API reference: see the API documentation at the developer portal.
Found a problem in sandbox? Open a support ticket from inside sandbox — it'll reach our team.