Sandbox (Test Mode)

eFakturuj's sandbox is self-serve and per-key. You don't request access or spin up a separate stack — you create a test API key and use it. A test key routes to a mock Peppol/Finančná správa endpoint, so nothing is delivered to a live counterparty and nothing is billed.

• Create a test key in the dashboard (the Create API key form has a Test / Live toggle) or via the API: POST /api-keys { "name": "sandbox", "environment": "test" }.
• Test keys are prefixed efk_test_; live keys are efk_live_.
• The same https://api.efakturuj.sk/api/v1 base URL serves both — the key's environment decides the behaviour.

What a test key does

• No real delivery. Outbound invoices created with a test key route to a mock Peppol test endpoint instead of the real AS4 network, and the Slovak Tax Authority (Finančná správa) copy is skipped with a mock acknowledgement recorded. No document reaches a live counterparty.
• Never billed. Test invoices are not usage-counted and not billed — no billing_events, no usage increment. Build and iterate freely.
• Soft-isolated data. Every invoice is tagged with its key's environment. A test key only ever sees test data; a live key only sees live data. In the dashboard, the Test mode switch scopes the invoice, events, and API-log views to the selected environment.
• Same code paths. UBL generation, XSD + Schematron validation, audit logging, and webhook delivery run exactly as in production. What you test is what you ship — only the final delivery and billing differ.

What sandbox does NOT change

• 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 a Peppol Test SMP fixture or an OpenPeppol testbed participant.
• Email delivery (password reset, email verification) goes to the configured SMTP relay in both modes — use a test inbox.

Recommended workflow

1. Create a test key — dashboard Connect → API keys → Create with the environment set to Test, or POST /api-keys {"environment":"test"}. Copy the efk_test_… secret (shown once).
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. The response transitions to delivered (sandbox always succeeds) and your webhook subscriber receives invoice.delivered — with nothing delivered to a live counterparty and nothing billed.
4. Provoke failure cases — an invalid VAT category, a mixed-rate invoice, a missing required field — and the Schematron pipeline returns the same 400 errors as production, so you can build error UX for free.
5. When you're ready, mint an efk_live_ key (the environment toggle set to Live, or the API default) and the same payloads work against production unchanged.

Switching environment is just switching the key: there is no code change between sandbox and production beyond the X-Api-Key you send.

See also

• Quickstart — works identically with a test key; just use your efk_test_… value as the X-Api-Key.
• Webhooks — test keys fire the same event types, so you can develop signature verification end-to-end.