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.

ℹ

Sandbox and production share the same base URL: https://api.clearvo.io/v1. The environment is determined entirely by the API key prefix — not a header or URL parameter.

Sandbox & Testing

Getting Started

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

1

Open Settings

Navigate to app.clearvo.io → Settings → Sandbox.

2

Create a sandbox entity

Click Create sandbox entity. Choose Fresh for a blank entity, or Copy from production to inherit VAT numbers and address from an existing production entity.

3

Copy your API key

Copy the csk_test_* key displayed — it is shown only once. Store it securely in your environment variables.

4

Swap the key

All API calls are identical to production. Replace your csk_live_* key with the csk_test_* key — no other changes required.

Sandbox & Testing

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.

Prefix	Environment	Database
csk_live_*	Production	Production DB
csk_test_*	Sandbox	Sandbox DB (isolated)

⚠

Never use sandbox keys in production flows — the key prefix is checked on every request, and a csk_test_* key will always route to the sandbox regardless of intent.

Sandbox & Testing

Supported Endpoints

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

Endpoint	Sandbox behaviour
POST /v1/send	XML is generated and validated normally. No authority submission occurs. Returns a mock response with `"sandbox": true`.
GET /v1/status	Polls the sandbox DB. `PENDING` records auto-resolve to `ACCEPTED` after 30 seconds, simulating authority clearance.
GET /v1/invoices	Lists sandbox submissions only, scoped to the authenticated entity and account. Production records are never returned.
GET /v1/documents/:id	Retrieves the generated XML from the sandbox DB. Use this to verify the output format before going live.
GET /v1/export	Exports sandbox records as CSV or JSONL. Production records are not included.
POST /GET /DELETE /v1/webhooks	Manages webhook configs in the sandbox DB. Events fire against sandbox-configured URLs only.

Sandbox & Testing

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):

JSON Response

{
  "ok": true,
  "sandbox": true,
  "country": "IT",
  "referenceId": "SDI-SANDBOX-a1b2c3d4",
  "fileName": "IT01234567890_FPA01_001.xml",
  "clearanceStatus": "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. clearanceStatus mirrors what production returns for each country: Italy starts as PENDING, while synchronous-clearance countries like Spain and Poland return ACCEPTED immediately.

Country clearance behaviour in sandbox

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

Country	Initial status	Resolves to
Italy (IT)	PENDING	ACCEPTED after 30s
Poland (PL)	ACCEPTED	— (terminal)
Spain (ES)	ACCEPTED	— (terminal)
Portugal (PT)	ACCEPTED	— (terminal)
Romania (RO)	PENDING	ACCEPTED after 30s
Hungary (HU)	PENDING	ACCEPTED after 30s
Greece (GR)	ACCEPTED	— (terminal)
Argentina (AR)	ACCEPTED	— (terminal)
Peppol countries	ACCEPTED	— (terminal)

Sandbox & Testing

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.

Sandbox & Testing

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 or PL KSeF test — all responses are mocked. 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. Sandbox requests count against your plan limits.

✓

Use webhook.site or ngrok to receive sandbox webhook events during local development — no public server needed.

⚠

Never use sandbox keys in production flows — the key prefix is checked on every request, and a csk_test_* key will always route to the sandbox regardless of your intent.