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.

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).
  • Moments later, the first update on the document is ready for you. It will have simulated SDI Identifier, MessageId and State values. The original invoice is also updated as needed (LastUpdate and DateSent properties.)
  • Eventually, another update will trigger, signalling a change of the delivery state. The document might have been delivered, or maybe delivery was impossibile for it (check the update's State property.)
  • Inbound invoices (/receive/ endpoint) will be delivered at random intervals. 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.
  • The webhook history is also available, and vacuumed every 15 days days.

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 (sk_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 (sk_live...).