Sandbox
The sandbox validates that your API flow works against simulated services. It does not prove that a Legal Entity is registered or active in production, and no data is sent to AEAT.
Use the sandbox to develop and test your Spanish integration without issuing real fiscal documents.
- API URL:
https://es-sandbox.api.acubeapi.com - Data: use test companies and test documents only.
- Registering a new Legal Entity: the entity is created directly with
POST /legal-entities. The tax ID (NIF, NIE or CIF) format is validated, but no external portal handoff is required. - Tax reporting to AEAT: billing records are not sent to AEAT. The AEAT response is simulated.
- Send outcomes: the simulated AEAT response is derived from the recipient tax
id of the invoice, in the same spirit as test card numbers. Any ordinary recipient
resolves to
accepted; the reservedESSANDBOX*values below force a specific outcome so you can build and test your error handling.
Reserved recipient tax ids
Send an invoice (or a draft, then
POST /invoices/draft/{uuid}/send)
whose recipient tax id is one of the following to obtain that exact outcome. Read the
result back with GET /invoices/{uuid}.
Recipient taxId | Resulting status | errorReason |
|---|---|---|
| (any other value) | accepted | null |
ESSANDBOXERR0001 | rejected | INVALID_RECIPIENT_FISCAL_ID |
ESSANDBOXERR0002 | rejected | DUPLICATE_INVOICE_NUMBER |
ESSANDBOXERR0003 | rejected | SCHEMA_VALIDATION_FAILED |
ESSANDBOXERR0004 | rejected | UNAUTHORIZED_RECIPIENT |
ESSANDBOXERR0005 | error | null |
ESSANDBOXINC0001 | failed | PROCESSING_INCIDENT |
ESSANDBOXACC0001 | accepted_with_errors | FINGERPRINT_MISMATCH |
ESSANDBOXTEC0001 | error | GATEWAY_TIMEOUT |
ESSANDBOXTEC0002 | error | UNREADABLE_RESPONSE |
ESSANDBOXENV0001 | error | SUBMISSION_REJECTED |
ESSANDBOXENV0002 | error | SUBMISSION_REJECTED |
ESSANDBOXENV0003 | failed | SUBMISSION_REJECTED |
Where the simulated outcome carries an AEAT code, it is returned in aeatErrorCode
(for example 1192 for ESSANDBOXERR0001). The sandbox does not simulate the AEAT
text, so aeatErrorDescription stays null.
The same values drive the outcome of a
correction: create an invoice for
ESSANDBOXACC0001 to get one accepted_with_errors, then correct it with an ordinary
recipient (accepted) or a rejecting one (back to accepted_with_errors).
Simplified invoices have no recipient,
so they always resolve to accepted in the sandbox.
Test your webhooks
Webhooks are delivered in the sandbox too, so the same reserved values trigger each event type:
Recipient taxId | Event | status in the payload |
|---|---|---|
| (any other value) | invoice.sent | accepted |
ESSANDBOXACC0001 | invoice.sent | accepted_with_errors |
ESSANDBOXERR0001 to ESSANDBOXERR0004 | invoice.rejected | rejected |
ESSANDBOXINC0001, ESSANDBOXENV0003 | invoice.failed | failed |
ESSANDBOXERR0005, ESSANDBOXTEC0001, ESSANDBOXTEC0002, ESSANDBOXENV0001, ESSANDBOXENV0002 | verifactu.incident | (no invoice event) |
To test a rejected correction, correct an ESSANDBOXACC0001 invoice with a rejecting
recipient: you get invoice.rejected with status accepted_with_errors.
To test a full incident, use an issuer with no failed invoices:
- Send an invoice with one of the
verifactu.incidentvalues above. The invoice ends inerror, and you getverifactu.incidentwithincidentActivetrue. - Send another invoice from the same issuer, with any ordinary recipient. The sandbox
retries the pending record only at this point, and resolves it as
accepted. - You get an
invoice.sentfor each of the two invoices, andverifactu.incidentwithincidentActivefalse.
See Invoice lifecycle for what each status means.