Sandbox & Testing

Clearvo provides a complete sandbox environment for integration testing. Sandbox keys (csk_test_*) route all requests to an isolated database — no data crosses into production, and no tax authority is ever contacted.

The sandbox supports every /v1/* endpoint with the same request and response shapes as production. XML is generated and validated normally; only the final authority submission step is replaced with a mock. This lets you verify your integration end-to-end — including format correctness, idempotency behaviour, status polling, and webhooks — before touching production.

Getting Started

Create a sandbox entity and obtain a test API key in four steps:

API Key Prefixes

The key prefix is the sole source of truth for environment routing. The API determines the environment from the key itself — there is no separate sandbox URL, header, or query parameter.

Supported Endpoints

All /v1/* endpoints work with sandbox keys. Behaviour is identical to production except where noted:

Mock Responses

A POST /v1/send call with a sandbox key returns a response that mirrors the production shape exactly, with one additional field: "sandbox": true. Below is an example for Italy (IT):

{
  "ok": true,
  "sandbox": true,
  "country": "IT",
  "referenceId": "SDI-SANDBOX-a1b2c3d4",
  "fileName": "IT01234567890_FPA01_001.xml",
  "status": "PENDING",
  "stage": "awaiting_authority",
  "reason": "PENDING",
  "terminal": false,
  "submittedAt": "2026-06-18T14:30:00.000Z",
  "nextPollAfter": "2026-06-18T14:30:05.000Z"
}

The sandbox: true field is always present on sandbox responses and is never returned in production. The XML is fully generated and schema-valid — only the authority submission step is skipped. status mirrors what production returns for each country: Italy starts as PENDING, while synchronous-clearance countries like Spain return COMPLETED immediately. Poland returns COMPLETED immediately too, unless the business profile has KSeF test credentials registered: then the invoice is submitted to the KSeF test environment, stays PENDING and resolves to COMPLETED or REJECTED from KSeF's own answer, with the KSeF number and UPO once KSeF issues them.

Country clearance behaviour in sandbox

The initial status and auto-resolution timing per country are designed to reflect how each real authority behaves:

Isolation Guarantees

The sandbox is architecturally isolated from production, not just logically separated:

• Sandbox entities live in a separate database — they cannot read or write production data under any circumstances.
• Sandbox API keys are stored in the sandbox database and cannot authenticate against production endpoints.
• Chain state such as VeriFactu huella (Spain) and Portugal ATCUD sequences is never advanced by sandbox submissions — your production counters are untouched.
• Sandbox records do not appear in production invoice listings, exports, or webhooks.

Limitations

The sandbox is designed for integration testing of your API usage, not for round-tripping against real tax authority staging environments. The following constraints apply:

• No authority staging connectivity. Sandbox does not connect to tax authority test portals such as IT SDI test — all responses are mocked. The exception is Poland: a business profile with KSeF test credentials registered submits to the KSeF test environment and is resolved from KSeF's real answer. For integration testing against real authority staging environments, contact support@clearvo.io.
• Argentina AFIP authentication is skipped. Sandbox calls bypass AFIP login entirely — no real CAE (Código de Autorización Electrónica) is issued.
• Webhook delivery is sandbox-scoped. Events fire against sandbox-configured webhook URLs only. Use a tool like webhook.site to receive events during local development.
• Rate limits apply equally to sandbox and production — the same per-key limits, counted separately for each key, so sandbox traffic never uses up a production key's budget. See Rate limits.