SDIcoop : l'API coopérative du SdI

SDIcoop est le canal programmatique réservé aux intermédiaires accrédités pour échanger machine-à-machine avec le SdI. Initialement SOAP 1.2 (depuis 2014), enrichi d'une variante REST V2 en 2022, il sert de pierre angulaire à l'ensemble des plateformes e-invoicing italiennes.

Rôles techniques

La spécification FatturaPA distingue trois rôles techniques distincts, séparés du rôle commercial des parties. Ces rôles sont reflétés dans les éléments XML et dans les contrôles SdI.

Cas particulier : le Terzo Intermediario o Soggetto Emittente peut être déclaré dans FatturaElettronicaHeader/SoggettoEmittente si la facture est émise par un tiers pour le compte du Cedente (factoring, mandataire). Codes possibles : CC (cessionario), TZ (terzo).

SOAP 1.2 — WSDL historique

L'interface SOAP est le canal historique de SDIcoop, en production depuis le lancement du B2G en 2014. Trois services principaux :

1. SdIRiceviFile (envoi) — l'intermédiaire pousse le XML signé au SdI. WSDL : RicezioneFatture_v1.0.wsdl.
2. SdIRiceviNotifiche (réception ricevute) — l'AdE pousse les RC, MC, NS, EC à l'intermédiaire sur son endpoint déclaré. WSDL : TrasmissioneFatture_v1.0.wsdl.
3. SdIRiceviFile_Sospensione (recherche / suspension) — opération de gestion des fattura en pause (rares cas opérationnels).

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

Publiée en 2022 (Provvedimento AdE 99922/2022), l'API REST V2 simplifie radicalement l'intégration ERP. Documentée via OpenAPI 3.0, retours JSON, pagination par curseur.

• POST /api/v2/fatture — envoyer une fattura. Body JSON avec base64 du fichier XML signé. Retour 202 Accepted + identifiant SdI dans le header X-SDI-IdentificativoSDI.
• GET /api/v2/fatture — lister les fatture envoyées par l'intermédiaire sur une période. Pagination par curseur.
• GET /api/v2/fatture/{id}/stato — récupérer le statut courant d'une fattura : in elaborazione, consegnata, mancata consegna, scartata, respinta.
• POST /api/v2/notifiche — webhook callback : l'AdE pousse les ricevute dès qu'elles sont émises (configuration HMAC SHA-256 par convention d'accréditation).
• GET /api/v2/intermediari/{cd} — vérifier le statut d'un Codice Destinatario tiers (utile avant envoi).

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

Authentification mTLS

L'authentification SDIcoop repose entièrement sur la mutual TLS (mTLS). Pas de Bearer token, pas d'OAuth 2.0 : la confiance est ancrée dans le certificat X.509.

• Certificat intermédiaire — délivré par un QTSP italien (Aruba, InfoCert, ArubaPEC, Namirial, Postecom). Doit avoir l'OID 1.3.6.1.4.1.41946.1.1 (e-IDAS qualified seal).
• CA AdE — l'AdE expose son chain certificate à certificate.sdi.gov.it. À ajouter dans le truststore de l'intermédiaire.
• Renouvellement — durée typique 2-3 ans. À renouveler 30 jours avant expiration pour éviter coupures de service.
• Sans signature payload — le payload XML est lui-même signé en CAdES-BES (responsabilité du Cedente), mais la couche transport mTLS authentifie seulement le Trasmittente.
• Côté webhook — l'AdE valide le certificat de l'endpoint du destinataire pour les pushs de ricevute (TLS unidirectionnel).

Retry policy et idempotence

Le SdI peut renvoyer des erreurs transitoires (HTTP 503 Service Unavailable, SOAP Fault avec faultcode EC.02.001) lors de pics de charge ou de maintenance programmée. La règle AdE :

1. Backoff exponentiel — 1s → 2s → 4s → 8s → 16s, max 5 tentatives sur un horizon de 1 minute.
2. Idempotency key — REST V2 attend un header X-SDI-Idempotency-Key unique par envoi. Le SdI déduplique côté serveur si la même clé est reçue dans une fenêtre de 24 h.
3. ProgressivoInvio — pour SOAP, l'élément DatiTrasmissione/ProgressivoInvio joue le même rôle : compteur séquentiel unique par IdTrasmittente, sur 18 mois.
4. Réception en double — si l'AdE détecte un duplicate, elle renvoie une ricevuta EC.04.001 - File già ricevuto et n'imprime pas une nouvelle facture.
5. Fenêtre de maintenance — généralement 1-3 h dans la nuit du samedi au dimanche, annoncée 48 h à l'avance dans la Comunicazione tecnica publiée sur fatturapa.gov.it.

Limites de débit et de batch

Liens transverses

• Hub Italie — mandat e-invoicing complet
• SdI et FatturaPA — vue d'ensemble
• Codice Destinatario
• Spécification XML FatturaPA
• Portail Agenzia delle Entrate
• PPF (équivalent FR)
• Documentation officielle SDIcoop