Skip to main content

Italy — SDI Sandbox Onboarding

Operational guide for getting test credentials at the Italian Sistema di Interscambio (SDI) sandbox.

PropertyValue
AuthorityAgenzia delle Entrate (AdE)
Sandbox base URLhttps://testservizi.fatturapa.it/services/
CostFree
Time to provision1-2 weeks (if you already have an Italian VAT number); longer if not
Identity requiredItalian VAT number (Partita IVA) + SPID or CIE or CNS

Steps​

  1. Authenticate to the Fatture e Corrispettivi test portal at ivaservizi.agenziaentrate.gov.it/portale (test variant) using SPID.
  2. Register your software's SDI codice destinatario (7-character alphanumeric) — this is where SDI test responses are routed back to your system.
  3. Alternatively, route responses via your PEC mailbox if you don't want a codice destinatario.
  4. Validate with a small FatturaPA XML submission via the SDI test endpoint.

GitHub secrets to set​

IT_SDI_VAT_NUMBER
IT_SDI_CODICE_DESTINATARIO   # for response routing (or PEC fallback)
IT_SDI_USERNAME              # if SOAP auth path is used
IT_SDI_PASSWORD

Gotchas​

  • DC (Documento Commerciale, B2C variant) uses a separate flow from SDI (B2B/B2G). DC is for retail receipts; SDI is for B2B invoices. Adapter at rust/adapters/italy/ handles both via dc_client.rs and the SDI client.
  • Test SDI sometimes returns delayed responses (24h+). Polling worker must handle this gracefully — adapter is Deferred mode (per fi-rah).
  • TD-prefix document codes have stricter rules in test than they used to. For example, TD11 was retired and replaced with TD17/TD18/TD19 family for cross-border. Cluster-validation already corrected this in golden audit (per fi-93q).
  • Italy was wired into PollableRegistry late (per fi-50n). Sandbox tests should verify both the submit dispatch AND the polling for SDI receipts.

Non-resident path​

Italian VAT (Partita IVA) is required for SDI access. Foreign vendors typically appoint a rappresentante fiscale (fiscal representative).

  • SPID requires Italian residency. The standard alternatives are CIE (Italian electronic ID — only for Italian citizens, so not usable by us) or CNS (Carta Nazionale dei Servizi) smart card. CNS can be issued by Italian Chambers of Commerce abroad in some cases; check with the local Camera di Commercio first.
  • For non-Italian developers the practical path is CNS for individual identity plus a fiscal representative for VAT and the SDI codice destinatario.
  • Cheapest dev path: Italian fiscal representative — budget ~€200-600/month. They handle VAT registration, the SPID-equivalent identity step, and SDI codice destinatario assignment. 3-6 weeks to first credentials.
  • Production. Italian VAT registration or stable establishment for direct issuance; platform-serves-merchants model otherwise. The latter is preferred — merchants already hold Partita IVA.
  • Adapter crate: rust/adapters/italy/
  • DC client: rust/adapters/italy/src/dc_client.rs
  • Sandbox tests: rust/adapters/italy/tests/sandbox.rs