Sandbox

eFakturuj's sandbox is a per-organisation flag on the production backend, not a separate stack. When sandbox_mode is enabled on your organisation:

• Outbound invoices route to a mock Peppol test endpoint instead of the real Peppol AS4 network — no document is delivered to a live counterparty.
• The Slovak Tax Authority (Finančná správa) copy is skipped entirely and a mock acknowledgement is recorded.
• All other behaviour — UBL generation, XSD + Schematron validation, audit logging, billing events, webhook delivery — runs against the same code paths as production. What you test is what you ship.

The same https://api.efakturuj.sk/api/v1 base URL serves both modes; which one you get is determined by the org behind your credential.

Getting access

Sandbox mode is provisioned manually today. It's controlled by the organisations.sandbox_mode boolean and there is no public endpoint to flip it — request enablement by emailing support@efakturuj.sk with the organisation name and your VAT ID.

Once enabled you'll see "Sandbox Mode: Enabled" on the Connect → Sandbox page in the dashboard. Until then the page displays the test invoice template but the API will deliver against production Peppol.

Test API keys

The auth layer recognises two API-key prefixes:

Prefix	Meaning
efk_live_...	Created by POST /api-keys from the dashboard.
efk_test_...	Reserved for sandbox-only credentials.

Today both prefixes are accepted by the unified auth middleware, but the POST /api-keys endpoint always mints efk_live_ keys. While sandbox provisioning is manual, support will issue your efk_test_ key alongside flipping the org flag.

The intent is that efk_test_ keys can only authenticate against sandbox-mode orgs once that gating ships — until then, treat the prefix as a naming convention so logs and Stripe receipts stay unambiguous.

What sandbox does NOT cover

• Peppol participant lookup (GET /lookup/...) hits the real SMP / SML in both modes — there is no mock SMP. To test against a known-good participant id, use one of the Peppol Test SMP fixtures or the testbed participants OpenPeppol publishes during certification.
• Email delivery (password reset, email verification) goes to the configured SMTP relay in both modes. Use a test inbox.
• Stripe billing — sandbox events do not generate live Stripe charges, but the billing_events table is appended to in both modes for audit completeness.

Recommended workflow

1. Mint a sandbox API key (via support, see above).
2. Create a couple of test customers — pick fictional VAT IDs in the SK99999... range so they cannot collide with real Slovak entities.
3. Send a few invoices through the full lifecycle: draft → validate → send. Watch the response transition to delivered (sandbox always succeeds) and confirm your webhook subscriber receives invoice.delivered.
4. Provoke failure cases: pass an invalid VAT category, use a 13-line invoice with mixed VAT rates, drop a required field — the Schematron pipeline will return the same 400 errors as production, so you can build error UX without spending real money.
5. Switch the prefix to efk_live_ and the same payloads work against production unchanged.

See also

• Quickstart — works identically against sandbox; just swap the X-Api-Key value.
• Webhooks — sandbox fires the same event types, so you can develop signature verification end-to-end.