Skip to main content

Sandbox

note

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 reserved ESSANDBOX* 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 taxIdResulting statuserrorReason
(any other value)acceptednull
ESSANDBOXERR0001rejectedINVALID_RECIPIENT_FISCAL_ID
ESSANDBOXERR0002rejectedDUPLICATE_INVOICE_NUMBER
ESSANDBOXERR0003rejectedSCHEMA_VALIDATION_FAILED
ESSANDBOXERR0004rejectedUNAUTHORIZED_RECIPIENT
ESSANDBOXERR0005errornull
ESSANDBOXINC0001failedPROCESSING_INCIDENT
ESSANDBOXACC0001accepted_with_errorsFINGERPRINT_MISMATCH
ESSANDBOXTEC0001errorGATEWAY_TIMEOUT
ESSANDBOXTEC0002errorUNREADABLE_RESPONSE
ESSANDBOXENV0001errorSUBMISSION_REJECTED
ESSANDBOXENV0002errorSUBMISSION_REJECTED
ESSANDBOXENV0003failedSUBMISSION_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 taxIdEventstatus in the payload
(any other value)invoice.sentaccepted
ESSANDBOXACC0001invoice.sentaccepted_with_errors
ESSANDBOXERR0001 to ESSANDBOXERR0004invoice.rejectedrejected
ESSANDBOXINC0001, ESSANDBOXENV0003invoice.failedfailed
ESSANDBOXERR0005, ESSANDBOXTEC0001, ESSANDBOXTEC0002, ESSANDBOXENV0001, ESSANDBOXENV0002verifactu.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:

  1. Send an invoice with one of the verifactu.incident values above. The invoice ends in error, and you get verifactu.incident with incidentActive true.
  2. 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.
  3. You get an invoice.sent for each of the two invoices, and verifactu.incident with incidentActive false.

See Invoice lifecycle for what each status means.