Skip to content

Sandbox

As soon as you register your account, the Sandbox is available free of charge. You can store, validate, sign outbound invoices and even receive (mock) updates about them. You also receive (mock) inbound invoices in the Sandbox. The event log is available and you can create webhooks. In practice, the Sandbox replicates the live workflow so you can fully develop your integration before moving it to production.

Free Sandbox

When using the Sandbox, no credits are consumed. You can store, sign, receive all invoices you want in the Sandbox, at no charge. The Sandbox is a test environmnent; no test invoice is sent or received from the SDI.

Use the Sandbox with Desk

You can also use your sandbox API key with Desk Cloud, for free: no Desk seat required, no time limit. It's the easiest way to evaluate Desk with no commitment.

Make sure you use the test API key

You work with the Sandbox by using your test API Key, the one prefixed with ik_test_. Always ensure that you are using the test key with the Sandbox.

Sandbox workflow

We do our best to simulate a live workflow. Here is how the Sandbox works:

  • When you upload an invoice, the system will pick it up for (simulated) delivery. You can retrieve the document at any moment to verify its state.
  • If you want, you can request pre-flight validation for the invoice as you store it, or you can use the /send/validate/ endpoint if you only want to validate the document.
  • You can request a digital signature to be applied to the uploaded document. In the Sandbox, a self-signed test certificate will be used (CN: InvoiceApiSandbox).
  • The simulator does not work in real time but in hourly cycles, at half past every hour: this way it tries to roughly mimic the behavior and response times of SDI, which does not return receipts and outcomes immediately.
  • At the first cycle after upload, the invoice is "sent" and the first update is ready for you, with simulated SDI Identifier, MessageId and State values. The original invoice is also updated as needed (LastUpdate and DateSent properties.)
  • At the next cycle, another update signals a change of the delivery state. The document might have been delivered, rejected, or maybe delivery was impossible for it (check the update's State property.) For invoices to the Public Administration, a further cycle produces the recipient's outcome or the expiry of terms. Expect up to about two hours between upload and outcome.
  • For invoices between private parties (FPR12) you can choose the outcome instead of leaving it to chance, by using one of these reserved codes as CodiceDestinatario: SBXRC00 (Consegnato), SBXMC00 (ImpossibilitaDiRecapito) or SBXNS00 (Scartato). Any other code keeps the outcome random. These codes only work in the Sandbox: in the live environment SDI would reject the invoice because the recipient code does not exist.
  • Inbound invoices (/receive/ endpoint) are delivered at every simulator cycle, in varying numbers (one to six per company), but only to active companies (see the note below). These are of course mock documents that you can use to test your integration.
  • Outbound documents and their state updates are kept for 15 days (2 years in the live enviroment), then they are vacuumed.
  • Inbound documents are vacuumed every 24 hours (2 years in the live environment).
  • Webhooks are functional; the Sandbox will attempt to notify your integration at the configured endpoint. See the Webhooks guide to learn how to validate notifications.
  • The webhook history is also available, and vacuumed every 15 days days.

Inbound invoices and active companies

To keep the Sandbox realistic and avoid piling up useless documents, mock inbound invoices are generated only for "active" companies: those created recently — so a new account still sees sample invoices right away — or those that have sent at least one invoice in the last month. Companies with no recent outbound activity stop receiving mock invoices; to resume generation, simply send a new invoice from the company.

Workflow comparison

An typical Sandbox workflow would go like this:

sequenceDiagram
  participant Client
  box Invoicetronic
  participant API as API (Sandbox)
  participant SDI as SDI (Mock)
  end
  Client->>API: POST (/send/)
  API->>SDI: Send invoice
  SDI-->>API: Update: "Inviato"
  SDI-->>API: Update: "Consegnato"
  API-->>Client: GET (/update/)
  Note right of Client: receives 2 mock updates
  SDI-->>API: Invoice 1
  SDI-->>API: Invoice 2
  API-->>Client: GET (/receive/)
  Note left of API: receives 2 mock invoices

As you can see, the Sandbox is isolated. No outbound invoice leaves it, and no inbound invoice is enters it. Status updates and incoming invoices are mocks.

On the live API, a similar workflow would go something like this:

sequenceDiagram
  participant Client
  box Invoicetronic
    participant API as API (Live)
  end
  box Agenzia Entrate
    participant SDI as SDI (Live)
  end
  participant Customer
  participant Vendor
  Client->>API: POST (/send/)
  API->>SDI: Send
  SDI-->>Customer: Send
  SDI-->>API: Update: "Inviato"
  Customer-->>SDI: ACK
  SDI-->>API: Update: "Consegnato"
  API-->>Client: GET (/update/)
  Note right of Client: receives 2 updates
  Vendor-->>SDI: Invoice 1
  SDI-->>API: Invoice 1
  Vendor-->>SDI: Invoice 2
  SDI-->>API: Invoice 2
  API-->>Client: GET (/receive/)
  Note left of API: receives 2 invoices

Looking closely, you'll notice that the client performs the same operations in both environments (Live and Sandbox). Using the test API key (ik_test_...), you can experiment at no cost and no risk in the Sandbox. When ready, you move to the live environment by switching to the live API key (ik_live_...).