SDIcoop: the SdI cooperative API

SDIcoop is the programmatic channel reserved for accredited intermediaries to exchange machine-to-machine with the SdI. Originally SOAP 1.2 (since 2014), enriched with a REST V2 flavour in 2022, it is the cornerstone of every Italian e-invoicing platform.

Technical roles

The FatturaPA spec distinguishes three technical roles, separate from the commercial roles of the parties. These roles are reflected in XML elements and in SdI checks.

Special case: the Terzo Intermediario o Soggetto Emittente can be declared in FatturaElettronicaHeader/SoggettoEmittente if the invoice is issued by a third party on behalf of the Cedente (factoring, agent). Possible codes: CC (cessionario), TZ (terzo).

SOAP 1.2 — historical WSDL

The SOAP interface is the historical SDIcoop channel, in production since the B2G launch in 2014. Three main services:

1. SdIRiceviFile (send) — the intermediary pushes the signed XML to the SdI. WSDL: RicezioneFatture_v1.0.wsdl.
2. SdIRiceviNotifiche (receive ricevute) — the AdE pushes RC, MC, NS, EC to the intermediary on its declared endpoint. WSDL: TrasmissioneFatture_v1.0.wsdl.
3. SdIRiceviFile_Sospensione (search / suspension) — operation for managing paused invoices (rare operational cases).

POST /sdicoop/v1/RiceviFatture HTTP/1.1
Host: ricevifatture.sdi.gov.it
Content-Type: application/soap+xml; charset=utf-8
SOAPAction: "RiceviFatture"

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
               xmlns:tns="http://www.fatturapa.gov.it/sdi/ws/ricezione/v1.0/types">
  <soap:Body>
    <tns:fileSdIBase64>
      <tns:NomeFile>IT01234567890_00001.xml.p7m</tns:NomeFile>
      <tns:File>MIIIIQYJKoZIhvcNAQcCoIIIEjCCCA4CAQEx...</tns:File>
    </tns:fileSdIBase64>
  </soap:Body>
</soap:Envelope>

REST V2 — JSON / OpenAPI

Published in 2022 (Provvedimento AdE 99922/2022), the REST V2 API radically simplifies ERP integration. Documented via OpenAPI 3.0, JSON responses, cursor pagination.

• POST /api/v2/fatture — send a fattura. JSON body with base64 of the signed XML file. Returns 202 Accepted + SdI identifier in X-SDI-IdentificativoSDI header.
• GET /api/v2/fatture — list invoices sent by the intermediary over a time window. Cursor pagination.
• GET /api/v2/fatture/{id}/stato — retrieve current status of an invoice: in elaborazione, consegnata, mancata consegna, scartata, respinta.
• POST /api/v2/notifiche — webhook callback: the AdE pushes ricevute as soon as emitted (HMAC SHA-256 configured per accreditation convention).
• GET /api/v2/intermediari/{cd} — check the status of a third-party Codice Destinatario (useful before sending).

POST /api/v2/fatture HTTP/1.1
Host: api.sdi.agenziaentrate.gov.it
Authorization: Bearer eyJhbGciOiJSUzI1NiIs...
Content-Type: application/json
X-SDI-Idempotency-Key: 2026-05-19-7a3c-IT01234567890-00001

{
  "nomeFile": "IT01234567890_00001.xml.p7m",
  "fileBase64": "MIIIIQYJKoZIhvcNAQcCoIIIEjCCCA4CAQEx...",
  "formato": "FPR12",
  "intermediario": "M5UXCR1"
}

HTTP/1.1 202 Accepted
X-SDI-IdentificativoSDI: 1234567890
Location: /api/v2/fatture/1234567890/stato

mTLS authentication

SDIcoop authentication relies entirely on mutual TLS (mTLS). No Bearer token, no OAuth 2.0: trust is anchored in the X.509 certificate.

• Intermediary certificate — issued by an Italian QTSP (Aruba, InfoCert, ArubaPEC, Namirial, Postecom). Must carry OID 1.3.6.1.4.1.41946.1.1 (eIDAS qualified seal).
• AdE CA — the AdE exposes its chain certificate at certificate.sdi.gov.it. To add to the intermediary truststore.
• Renewal — typical duration 2-3 years. Renew 30 days before expiration to avoid service interruption.
• No payload signature on the wire — the XML payload itself is signed in CAdES-BES (Cedente responsibility), but the transport layer mTLS only authenticates the Trasmittente.
• Webhook side — the AdE validates the recipient endpoint's certificate for ricevuta pushes (unidirectional TLS).

Retry policy and idempotency

The SdI can return transient errors (HTTP 503 Service Unavailable, SOAP Fault with faultcode EC.02.001) during peak load or scheduled maintenance. AdE rule:

1. Exponential backoff — 1s → 2s → 4s → 8s → 16s, max 5 attempts over a 1-minute horizon.
2. Idempotency key — REST V2 expects a unique X-SDI-Idempotency-Key header per send. The SdI deduplicates server-side if the same key is received within a 24h window.
3. ProgressivoInvio — for SOAP, the DatiTrasmissione/ProgressivoInvio element plays the same role: unique sequence counter per IdTrasmittente, over 18 months.
4. Duplicate reception — if the AdE detects a duplicate, it returns a ricevuta EC.04.001 - File già ricevuto and does not generate a new invoice.
5. Maintenance window — usually 1-3 h during the Saturday-to-Sunday night, announced 48 h ahead in the Comunicazione tecnica published on fatturapa.gov.it.

Throughput and batch limits

Cross-links

• Italy hub — complete e-invoicing mandate
• SdI and FatturaPA — overview
• Codice Destinatario
• FatturaPA XML specification
• Agenzia delle Entrate portal
• PPF (FR equivalent)
• Official SDIcoop documentation