Vai al contenuto

Sandbox

Non appena registri il tuo account, la Sandbox è disponibile gratuitamente. Puoi archiviare, validare, firmare fatture in uscita e persino ricevere aggiornamenti (simulati) su di esse. Ricevi anche fatture in entrata (simulate) nella Sandbox. Il registro degli eventi è disponibile e puoi creare webhook. In pratica, la Sandbox replica il flusso di lavoro live così puoi sviluppare completamente la tua integrazione prima di spostarla in produzione.

Sandbox gratuita

Quando usi la Sandbox, nessun credito viene consumato. Puoi archiviare, firmare, ricevere tutte le fatture che vuoi nella Sandbox, senza alcun costo. La Sandbox è un ambiente di test; nessuna fattura di test viene inviata o ricevuta dallo SDI.

Assicurati di usare la test API key

Lavori con la Sandbox usando la tua API Key di test, quella con prefisso ik_test_. Assicurati sempre di usare la chiave di test con la Sandbox.

Flusso di lavoro della Sandbox

Facciamo del nostro meglio per simulare un flusso di lavoro live. Ecco come funziona la Sandbox:

  • Quando carichi una fattura, il sistema la prenderà in carico per la consegna (simulata). Puoi recuperare il documento in qualsiasi momento per verificarne lo stato.
  • Se vuoi, puoi richiedere la validazione preventiva della fattura al momento del salvataggio, oppure puoi usare l'endpoint /send/validate/ se vuoi solo convalidare il documento.
  • Puoi richiedere l'applicazione di una firma digitale al documento caricato. Nella Sandbox, verrà utilizzato un certificato di test auto-firmato (CN: InvoiceApiSandbox).
  • Momenti dopo il salvataggio, il primo aggiornamento sul documento è pronto per te. Avrà valori simulati di Identifier, MessageId e State (dati SDI). La fattura originale viene aggiornata di conseguenza (proprietà LastUpdate e DateSent.)
  • Alla fine, un altro aggiornamento si attiverà, segnalando un cambio dello stato di consegna. Il documento potrebbe essere stato consegnato, o forse la consegna è stata impossibile (controlla la proprietà State dell'aggiornamento.)
  • Le fatture in entrata (endpoint /receive/) verranno consegnate a intervalli casuali. Questi sono ovviamente documenti simulati che puoi usare per testare la tua integrazione.
  • I documenti in uscita e i loro aggiornamenti di stato vengono conservati per 15 giorni (2 anni nell'ambiente live), poi vengono eliminati.
  • I documenti in entrata vengono eliminati ogni 24 ore (2 anni nell'ambiente live).
  • I webhook sono funzionali; la Sandbox tenterà di notificare la tua integrazione all'endpoint configurato.
  • La cronologia dei webhook è anche disponibile, ed eliminata ogni 15 giorni.

Confronto dei flussi di lavoro

Un tipico flusso di lavoro della Sandbox andrebbe così:

sequenceDiagram
  participant Client
  box Invoicetronic
  participant API as API (Sandbox)
  participant SDI as SDI (Mock)
  end
  Client->>API: POST (/send/)
  API->>SDI: Invio fattura
  SDI-->>API: Aggiornamento: "Inviato"
  SDI-->>API: Aggiornamento: "Consegnato"
  API-->>Client: GET (/update/)
  Note right of Client: riceve 2 aggiornamenti simulati
  SDI-->>API: Fattura 1
  SDI-->>API: Fattura 2
  API-->>Client: GET (/receive/)
  Note left of API: riceve 2 fatture simulate

Come puoi vedere, la Sandbox è isolata. Nessuna fattura in uscita la lascia, e nessuna fattura in entrata vi entra. Gli aggiornamenti di stato e le fatture in arrivo sono simulati.

Sulla API live, un flusso di lavoro simile andrebbe più o meno così:

sequenceDiagram
  participant Client
  box Invoicetronic
    participant API as API (Live)
  end
  box Agenzia Entrate
    participant SDI as SDI (Live)
  end
  participant Customer as Cliente
  participant Vendor as Fornitore
  Client->>API: POST (/send/)
  API->>SDI: Invio
  SDI-->>Customer: Invio
  SDI-->>API: Aggiornamento: "Inviato"
  Customer-->>SDI: ACK
  SDI-->>API: Aggiornamento: "Consegnato"
  API-->>Client: GET (/update/)
  Note right of Client: riceve 2 aggiornamenti
  Vendor-->>SDI: Fattura 1
  SDI-->>API: Fattura 1
  Vendor-->>SDI: Fattura 2
  SDI-->>API: Fattura 2
  API-->>Client: GET (/receive/)
  Note left of API: riceve 2 fatture

Guardando attentamente, noterai che il client esegue le stesse operazioni in entrambi gli ambienti (Live e Sandbox). Usando la test API key (sk_test_..), puoi sperimentare senza costi e senza rischi nella Sandbox. Quando sei pronto, passi all'ambiente live cambiando alla live API key (sk_live...).