Aller au contenu

Italie — E-INVOICE IT (Unified API)

En Italie, la facturation électronique est obligatoire, réglementée par l’Agenzia delle Entrate et légalement exigée depuis janvier 2019. Chaque facture, B2B comme B2C, est échangée via le SDI (Sistema di Interscambio) au format XML FatturaPA et doit être conservée à long terme via un archivage certifié (conservazione a norma).

E-INVOICE IT gère cet échange pour vous. Vous envoyez les données de facture via l’Unified API ; fiskaly génère le XML FatturaPA, le transmet au SDI, suit le résultat et conserve la facture pendant les 10 ans exigés par la loi.

fiskaly émet la Facture standard (Fattura ordinaria, TD01) et la Note de crédit (Nota di credito, TD04), qui couvrent ensemble la facturation courante et les corrections. Vous ne définissez pas le type de document : il est déduit de l’opération de l’Unified API que vous appelez. La Facture simplifiée (Fattura semplificata, TD07) est prévue sur la feuille de route.

Types de documents hors du périmètre actuel

Les factures d’acompte (TD02), les factures différées (TD24, TD25) et les factures destinées aux administrations publiques (B2G, la variante FatturaPA FPA12) ne sont pas émises. recipients[].type accepte BUSINESS et CONSUMER.

Cette page couvre les exigences spécifiques à l’Italie qui complètent le Guide d’intégration général étape par étape pour intégrer un Taxpayer à la facturation électronique.

fiskaly gère les deux sens de l’échange SDI, qui fonctionnent différemment :

Au-delà de ces deux sens, chaque facture que vous envoyez et recevez est automatiquement archivée. Cela signifie une conservation certifiée à long terme (conservazione a norma) pendant les 10 années légalement requises, sans aucune configuration de votre côté.

Ces prérequis s’appliquent à tout Taxpayer que vous intégrez pour la facturation électronique en Italie — que vous envoyiez, receviez, ou les deux. Assurez-vous de disposer des informations suivantes sur le Taxpayer avant de continuer.

Données d’enregistrement spécifiques à l’Italie — transmises sous content.fiscalization.registration :

  • company_id — Numero Registro Imprese (numéro du registre du commerce)
  • office — code de la province de la Camera di Commercio qui a délivré le numéro REA, p. ex. MI, RM
  • entry — numéro REA (6 ou 7 chiffres)
  • legal_form — forme juridique de l’entité (p. ex. LIMITED_LIABILITY_COMPANY, JOINT_STOCK_COMPANY)
  • capital — capital social enregistré en EUR (p. ex. "10000.00")
  • shareholder_status — SOLE_SHAREHOLDER ou MULTIPLE_SHAREHOLDERS
  • liquidation_status — IN_LIQUIDATION ou NOT_IN_LIQUIDATION
  • tax_regime — facultatif, ORDINARY (par défaut) ou FLAT_RATE_SCHEME (Regime Forfettario)

Champs standard du Taxpayer — font partie du Taxpayer lui-même (partagés avec SIGN IT si vous l’utilisez) :

  • content.name — dénomination légale enregistrée de l’entreprise ou du particulier
  • content.address — adresse légale enregistrée
  • content.address.region — Provincia (code de province, p. ex. MI, RM) ; obligatoire sur le Taxpayer et validé lors de la mise en service

Envoi de factures électroniques : exigences relatives au destinataire

Section intitulée « Envoi de factures électroniques : exigences relatives au destinataire »

Pour envoyer une facture électronique, vous indiquez son destinataire et ses données de routage directement dans le Record de la facture. Lorsque vous créez la facture (TRANSACTION::INVOICE) avec createRecord, sur le System E_INVOICE_SERVICE ou, si le Taxpayer utilise aussi SIGN IT, sur son FISCAL_DEVICE, ajoutez le destinataire à son tableau recipients. Les champs à renseigner dépendent de la personne que vous facturez :

Chaque destinataire porte invoicing.type = SDI. Ce qui change d’un cas à l’autre, c’est l’identification, le code destinataire et l’intervention ou non d’une PEC :

EntrepriseConsommateur en ItalieConsommateur à l’étranger
typeBUSINESSCONSUMERCONSUMER
identificationVAT — validéTAX — codice fiscale, validétout type ; non validé
invoicing.destination_codele code du destinataire sur 7 caractères, ou "0000000" ; à l’étranger "XXXXXXX""0000000""XXXXXXX"
invoicing.pecobligatoire avec "0000000"facultativenon utilisée
address.regionobligatoire lorsque l’adresse est en Italieobligatoirenon obligatoire
nameraison socialegender, forename, surnamegender, forename, surname

Chaque destinataire professionnel est de type BUSINESS avec un bloc invoicing renseigné, comme l’explique l’intégration générale pas à pas. Outre les informations standard exigées par toute facture électronique (nom du destinataire, adresse, identification fiscale, lignes de facture, etc.), l’Italie ajoute les champs de routage SDI présentés ci-dessus.

Les valeurs de destination_code et de pec dépendent du destinataire :

Scénariodestination_codepec
Le destinataire a une boîte SDI enregistréeson code à 7 caractères (p. ex. ABC1234)facultatif
Le destinataire n’est pas enregistré auprès du SDI"0000000"obligatoire
Le destinataire est une entreprise hors d’Italie"XXXXXXX"non utilisé

Une facture adressée à une entreprise à l’étranger est déclarée au SDI, mais n’est pas remise par son intermédiaire. Envoyez-la avec destination_code: "XXXXXXX" et le numéro de TVA étranger du destinataire :

ChampValeur
recipients[].identificationVAT : le numéro de TVA étranger du destinataire
recipients[].address.countryle pays du destinataire sous forme de code ISO 3166-1 alpha-2 (pas IT)
recipients[].address.codele vrai code postal du destinataire. fiskaly inscrit "00000" dans la FatturaPA, qui n’accepte que les codes postaux italiens ; la copie PDF affiche le vrai code
recipients[].invoicing.destination_code"XXXXXXX"

region n’est pas obligatoire et pec n’est pas utilisé. Une entreprise établie en Italie suit toujours le flux national décrit ci-dessus.

Lorsque votre client est un particulier et non une entreprise, définissez recipients[].type sur CONSUMER. La facture passe par le SDI sous forme de document FatturaPA (TD01), comme une facture B2B.

Les consommateurs n’ont généralement pas de boîte SDI, le routage fonctionne donc différemment. La façon d’identifier le consommateur dépend de sa résidence en Italie ou non :

  • Résident en Italie — identifié par son codice fiscale, routé avec le code destinataire "0000000".
  • Hors d’Italie — aucun codice fiscale n’existe : un identifiant étranger prend sa place et la facture est routée avec "XXXXXXX".

Au-delà des champs du tableau ci-dessus, un destinataire consommateur porte toujours name.gender, name.forename et name.surname, ainsi que son adresse.

Envoyez le codice fiscale comme identification de type TAX (16 caractères), l’adresse de résidence y compris region (Provincia) en deux lettres majuscules, par exemple RM, et le code destinataire "0000000". Une pec est facultative.

Un consommateur qui ne réside pas en Italie n’a pas de codice fiscale : envoyez à la place un identifiant étranger, généralement un numéro fiscal ou de TVA étranger.

ChampValeur
recipients[].identificationobligatoire ; VAT, TAX, PASSPORT, DOCUMENT ou OTHER, selon l’identifiant dont vous disposez
recipients[].address.countryle pays du consommateur, code ISO 3166-1 alpha-2
recipients[].address.codele vrai code postal du destinataire. fiskaly inscrit "00000" dans la FatturaPA, qui n’accepte que les codes postaux italiens ; la copie PDF affiche le vrai code
recipients[].invoicing.destination_code"XXXXXXX"

L’identifiant est transmis au SDI comme IdCodice ; ni fiskaly ni le SDI n’en contrôlent la validité dès lors que le pays de l’adresse n’est pas l’Italie. La region n’est pas obligatoire pour une adresse non italienne.

Pour un consommateur résidant en Italie, le SDI dépose la facture originale dans son espace réservé sur le portail de l’AdE (Fatture e Corrispettivi).

Un avoir portant sur une facture à un consommateur suit les mêmes étapes que pour une facture à une entreprise : une INTENTION::TRANSACTION, puis une TRANSACTION::CORRECTION qui fait référence à la facture d’origine.

Lorsque le client a besoin d’une facture plutôt que d’un ticket

Section intitulée « Lorsque le client a besoin d’une facture plutôt que d’un ticket »

L’Italie déclare les deux documents par des canaux distincts — le ticket via les corrispettivi, la facture via le SDI — et rien ne les relie automatiquement.

Recueillez la demande avant la clôture de la vente. Lorsque le client vous indique qu’il a besoin d’une fattura, émettez une TRANSACTION::INVOICE à la place d’une TRANSACTION::RECEIPT. Demander « Avez-vous besoin d’une facture ? » au moment du paiement est le flux que fiskaly prend en charge de bout en bout aujourd’hui, que le client le demande avant ou pendant la vente.

Contrairement à un appel d’API synchrone, le résultat du SDI est asynchrone. Après avoir créé la facture (TRANSACTION::INVOICE) avec createRecord, interrogez le Record E_INVOICE::TRANSMISSION pour savoir si le SDI l’a acceptée. Il n’existe pas de webhook.

Si la facture est transmise, les trois Records atteignent leur état final ensemble :

RecordÉtat final
E_INVOICE::TRANSMISSIONCOMPLETED ou FAILED, mode=FINISHED
TRANSACTION::INVOICECOMPLETED ou FAILED, mode=FINISHED
INTENTION::TRANSACTIONCOMPLETED ou FAILED, mode=FINISHED

En cas d’échec, lisez logs[].message : un échec avant que la facture n’atteigne le SDI est consigné sur le Record TRANSACTION::INVOICE, un rejet du SDI sur le Record E_INVOICE::TRANSMISSION, d’où il est aussi copié dans les logs des Records TRANSACTION::INVOICE et INTENTION::TRANSACTION. Pour plus de détails, consultez How to check the status of an e-invoice sur notre page d’assistance.

state vous indique où en est une facture, logs[] vous indique pourquoi. Lisez-les ensemble et agissez en fonction de ce que vous trouvez :

Ce que vous voyezCe que cela signifieCe qu’il faut faire
4xx de createRecord, aucun Record crééLe payload a été rejeté. Rien n’a été créé et rien n’a été envoyé.Corrigez le payload et réessayez sur le même INTENTION::TRANSACTION.
state=ACCEPTEDToujours en cours.Interrogez le Record E_INVOICE::TRANSMISSION environ toutes les 15 secondes jusqu’à mode=FINISHED. Les résultats arrivent généralement en quelques minutes ; un rejet peut prendre jusqu’à 5 jours.
state=FAILEDTerminé, et la facture n’est pas juridiquement valide. Elle a été bloquée avant d’atteindre le SDI ou rejetée par le SDI avec NS.Lisez logs[].message pour en connaître la raison, corrigez les données et démarrez une nouvelle chaîne — voir Échecs et nouvelle soumission.
state=COMPLETED avec une entrée ERROR dans logs[]Quelque chose s’est mal passé en route, sans bloquer la facture.Lisez logs[].message avant de considérer la facture comme envoyée.
state=COMPLETED, aucune entrée ERRORLe SDI a accepté la facture.Rien de plus.

Chaque entrée de logs[] est soit un ERROR, soit un WARNING. Un WARNING est informatif et ne bloque jamais une facture — vous en recevez un lorsque quelque chose dans votre payload a été ajusté ou ne concordait pas, par exemple si vous avez envoyé plusieurs paiements en attente et que seul le premier a été utilisé, ou si les totaux de TVA de votre payload diffèrent des totaux calculés à partir des lignes de la facture.

Tout rejet n’a pas l’apparence d’un rejet. Les données de facture sont contrôlées à trois endroits différents, et chacun échoue sous une forme différente :

Où cela échoueExempleCe que vous voyez
Contraintes de schémaidentification.number hors de AlphaNumerical28 ; document.number hors de ^[0-9A-Z_/\-\.]{1,20}$400 de createRecord. Rien n’est créé.
Validation de champUn codice fiscale au format incorrect ou à la clé de contrôle erronée ; un recipients[].address.region manquantcreateRecord réussit. Le Record se ferme en COMPLETED / FINISHED, mais content.used_in est absent et rien n’est transmis. La raison n’apparaît que dans une entrée content.logs de sévérité ERROR.
En avalLe SDI rejette la facture avec NS, ou la transmission échoue avant d’atteindre le SDIcreateRecord réussit et la chaîne passe ensuite à FAILED. FAILED couvre toute transmission en échec, pas seulement un NS — la raison figure dans logs[].message.

Si le SDI renvoie NS (Notifica di Scarto), la facture est juridiquement inexistante :

  1. Lisez logs[].message pour obtenir le motif de rejet du SDI. Il figure sur le Record E_INVOICE::TRANSMISSION et est aussi copié dans les logs des Records TRANSACTION::INVOICE et INTENTION::TRANSACTION
  2. Créez une nouvelle INTENTION::TRANSACTION et une nouvelle TRANSACTION::INVOICE avec les données corrigées
  3. Le rejet NS ouvre un nouveau délai de 5 jours. Pendant ce délai, vous pouvez renvoyer la facture avec le même document.number, sous forme de nouveaux Records avec une nouvelle clé d’idempotence.
  4. La chaîne ayant échoué reste FAILED de façon permanente — elle est conservée à des fins d’audit

Un System E_INVOICE_SERVICE peut à la fois envoyer et recevoir des factures électroniques. La réception est facultative — un Taxpayer qui ne fait qu’émettre peut ignorer cette section.

Deux éléments distincts et indépendants entrent en jeu :

  • La capacité à recevoir — fiskaly la configure automatiquement lorsque vous mettez en service le System.
  • L’enregistrement du code destinataire SDI (manuel, réalisé par vous) — dans votre portail Agenzia delle Entrate (AdE), définissez le code destinataire SDI de fiskaly JKKZDGR comme destination SDI de votre entreprise, afin que le SDI achemine vos factures entrantes vers fiskaly.

Dans la réponse de mise en service, compliance.state vaut TRANSMISSION_ONLY. Il passe ensuite automatiquement à TRANSMISSION_RECEPTION une fois l’enregistrement du Taxpayer terminé — ce qui se produit normalement, que vous ayez ou non effectué l’enregistrement AdE ou prévu de recevoir.

Appelez retrieveSystem à tout moment pour lire le compliance.state actuel, qui reflète uniquement la capacité à recevoir — et non l’enregistrement AdE :

  • TRANSMISSION_RECEPTION — fiskaly a configuré le System pour recevoir.
  • TRANSMISSION_ONLY — cette configuration n’est pas terminée.

Il n’y a rien de plus à configurer pour l’acheminement : fiskaly associe automatiquement chaque facture entrante au bon Taxpayer grâce à son identifiant fiscal — c’est aussi pourquoi chaque identifiant fiscal doit appartenir à un seul Taxpayer enregistré. Vous n’avez pas besoin de configurer ni de stocker un code d’acheminement distinct.

Lorsqu’une facture vous est envoyée via le SDI, fiskaly la reçoit automatiquement :

  • la livraison entrante est traitée automatiquement de notre côté
  • un enregistrement de réception (reception record) est créé pour la facture
  • le XML signé, le PDF et les métadonnées sont stockés avec l’enregistrement
  • les livraisons en double sont dédupliquées

En pratique, la première facture qui vous parvient de cette manière confirme aussi que la réception est correctement configurée.

Chaque facture adressée à votre Taxpayer est reçue, validée et stockée automatiquement sous forme de Record — il n’existe pas de webhook, vous interrogez donc l’API pour détecter les nouvelles :

  1. Appelez listRecords et filtrez sur E_INVOICE::RECEPTION.
  2. Pour chaque nouveau Record, appelez retrieveRecord avec compliance-artifact pour obtenir le XML signé.

listRecords renvoie les Records les plus récents (limit par défaut à 10, du plus récent au plus ancien) : suivez donc ceux que vous avez déjà traités.

La loi italienne exige que les factures électroniques soient conservées à long terme via un archivage numérique certifié (conservazione a norma) : elles doivent être conservées pendant au moins 10 ans et stockées de manière à rester immuables, authentiques et facilement récupérables, avec des signatures numériques et des horodatages (marca temporale). Conserver votre propre copie du XML ne suffit pas — fiskaly s’en charge pour vous.

Pour l’Italie, l’archivage est automatique et toujours actif : chaque facture que vous envoyez et chaque facture que vous recevez via le SDI est légalement conservée, sans configuration supplémentaire ni appel d’API de votre côté. Cela repose uniquement sur l’identifiant fiscal italien du Taxpayer, qui fait déjà partie de l’onboarding. Chaque facture conservée reçoit un reçu de conservation comme preuve de conservazione a norma, joint automatiquement dès qu’il est prêt — rien n’est requis de votre côté. Plutôt qu’un délai fixe, utilisez state et mode du Record pour savoir si le reçu s’est stabilisé ; voir Quand les artefacts deviennent disponibles ci-dessous.

Récupérez les artefacts d’une facture électronique depuis son enregistrement avec retrieveRecord, en sélectionnant l’artefact via un paramètre de requête :

  • compliance-artifact — le document qui fait juridiquement foi. Pour l’Italie, le XML FatturaPA validé par le SDI.
  • archive-artifact — le reçu de conservation attestant la conservation légale (conservazione a norma), renvoyé sous forme de XML signé.

Les deux artefacts sont renvoyés dans la réponse JSON du Record, sous la forme d’un objet portant type et data :

"compliance": {
"artifact": { "type": "application/xml", "data": "<base64>" }
}

Pour l’Italie, type vaut toujours application/xml — il n’existe ni réponse XML brute distincte, ni variante PDF pour l’un ou l’autre artefact. L’en-tête Accept n’a aucun effet sur ce comportement.

compliance-artifact et archive-artifact n’existent pas pendant toute la vie d’un Record. Aucun des deux n’est produit à la création du Record : tous deux sont écrits une fois la transmission terminée — c’est-à-dire une fois que le SDI a répondu, ce qui peut prendre jusqu’à 5 jours. Ils se fixent au même moment, car l’étape d’archivage s’exécute avant le changement d’état du Record.

Vous disposez ainsi d’une règle fondée uniquement sur l’état, sans rien à chronométrer :

État du RecordCe qu’il dit des artefacts
state: ACCEPTED, mode: PROCESSINGNon terminal. Les artefacts peuvent encore manquer, et manquant signifie ici pas encore : ils arrivent.
state: COMPLETED / FAILED / REJECTED, mode: FINISHEDTerminal. Ce qui est présent est tout ce qu’il y aura ; un artefact absent n’apparaîtra plus.

Le reçu de conservation appartient au Record E_INVOICE::TRANSMISSION et non à la TRANSACTION::INVOICE. Prenez content.used_in.id sur le Record de la facture, puis :

GET /records/{transmissionId}?archive-artifact

Le reçu est renvoyé encodé en Base64 dans content.compliance.archive.data. Les factures que vous envoyez et celles que vous recevez ont chacune leur propre reçu. Tant que l’artefact n’est pas disponible, le champ est absent de la réponse plutôt que présent et vide.

Pour une facture impayée (payments[].type = OUTSTANDING), l’objet instruction est facultatif. Sans lui, la facture est acceptée et transmise, mais le mode de paiement est déclaré comme un virement bancaire sans aucune coordonnée bancaire : votre client reçoit alors une facture électronique sans IBAN sur lequel payer.

Si la facture doit être réglée par virement bancaire, envoyez instruction.type = CREDIT_TRANSFER avec :

  • account : votre IBAN
  • name : le titulaire du compte, c’est-à-dire vous, l’émetteur de la facture
  • payment_service_provider : le code BIC/SWIFT de votre banque (un nom de banque n’est pas accepté)

Pour un exemple complet et la variante par prélèvement, consultez Comment représenter les paiements sur une facture.

La loi italienne impose un droit de timbre (imposta di bollo) de 2,00 € sur les factures dont les lignes exonérées de TVA dépassent 77,47 € au total. fiskaly l’applique automatiquement : dès que le total des lignes exonérées de TVA concernées franchit ce seuil, le droit de timbre est ajouté à la FatturaPA transmise.

Il n’existe aucun champ pour le droit de timbre, ni dans la requête ni dans la réponse — rien à définir lorsque vous créez la facture, et rien n’est renvoyé sur le Record. Le seul endroit où la valeur appliquée apparaît est l’élément DatiBollo du XML FatturaPA, que vous pouvez lire depuis le document transmis :

GET /records/{transmissionId}?compliance-artifact

Le XML arrive encodé en Base64 : décodez-le avant d’y chercher DatiBollo.

Attendez-vous à deux avertissements d’écart sur les totaux

Section intitulée « Attendez-vous à deux avertissements d’écart sur les totaux »

Les 2,00 € sont ajoutés après le calcul des totaux de la facture : sur chaque facture qui franchit le seuil, les totaux transmis sont donc supérieurs de 2,00 € à ceux que vous avez envoyés. Le Record consigne cet écart sous forme de deux entrées WARNING dans content.logs, par exemple :

provided '100.00000000', calculated '102.00'

C’est le comportement attendu, et c’est le signal que le droit de timbre a été appliqué. Continuez à envoyer vos totaux hors droit de timbre : aucune charge utile ne permet à la fois de porter le droit de timbre et d’éviter les avertissements. Traitez ces deux entrées WARNING comme purement informatives et ne faites pas échouer votre intégration à cause d’elles.

En Italie, le type de document est l’identifiant de type FatturaPA : une CORRECTION est transmise en TD04 (Nota di credito), une INVOICE en TD01 (Fattura). Le type découlant de l’opération, une facture non transmise par fiskaly ne peut pas être créditée — émettre une TD01 référençant la facture antérieure augmente le montant dû au lieu de l’annuler. Voir Note de crédit pour la règle générale.

Pour les cas ponctuels, le SdI accorde un accès au portail à tous les commerçants, où un avoir peut être émis manuellement. Cela ne passe pas à l’échelle et n’est pas un modèle d’intégration : considérez-le comme une solution de repli pour la migration, et conservez le précédent système de facturation électronique jusqu’à ce que tout ce qu’il a émis soit réglé ou crédité.