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 :
Envoi — B2B et B2C
fiskaly génère la FatturaPA et l'envoie au SDI, qui la valide et la transmet au destinataire de manière asynchrone. Aucune inscription au réseau n'est requise. Les destinataires professionnels et les consommateurs exigent des champs différents.
Réception — B2B uniquement
Facultative, activée pour chaque Taxpayer. Nécessite une inscription unique pour recevoir les factures de vos fournisseurs.
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é.
Si vous disposez déjà d’une intégration SIGN IT, vous ne repartez pas de zéro — vous étendez votre Taxpayer existant avec les données d’enregistrement supplémentaires et mettez en service un System E_INVOICE_SERVICE. Consultez E-INVOICE IT pour les clients SIGN IT pour toutes les étapes.
Prérequis
Section intitulée « Prérequis »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.
E-INVOICE IT prend actuellement en charge les Taxpayers de type COMPANY. L’enregistrement d’un Taxpayer INDIVIDUAL — un indépendant ou entrepreneur individuel qui émet sous son propre codice fiscale plutôt qu’avec un numéro de TVA de société — arrive bientôt.
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,RMentry— 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_SHAREHOLDERouMULTIPLE_SHAREHOLDERSliquidation_status—IN_LIQUIDATIONouNOT_IN_LIQUIDATIONtax_regime— facultatif,ORDINARY(par défaut) ouFLAT_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 particuliercontent.address— adresse légale enregistréecontent.address.region— Provincia (code de province, p. ex.MI,RM) ; obligatoire sur le Taxpayer et validé lors de la mise en service
Pour la facturation électronique en Italie, content.fiscalization.registration et content.address.region (Provincia) sont des champs obligatoires sur le Taxpayer. Ils sont validés lors de la mise en service du System E_INVOICE_SERVICE — la mise en service échoue s’ils sont absents. Assurez-vous que les deux champs soient définis ou mis à jour sur le Taxpayer au préalable.
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 :
Destinataires professionnels (B2B)
Routés par le code destinataire SDI. Les entreprises à l'étranger sont déclarées avec XXXXXXX.
Destinataires consommateurs (B2C)
Les résidents italiens sont identifiés par le codice fiscale ; les consommateurs à l'étranger par un identifiant étranger.
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 :
| Entreprise | Consommateur en Italie | Consommateur à l’étranger | |
|---|---|---|---|
type | BUSINESS | CONSUMER | CONSUMER |
identification | VAT — validé | TAX — codice fiscale, validé | tout type ; non validé |
invoicing.destination_code | le code du destinataire sur 7 caractères, ou "0000000" ; à l’étranger "XXXXXXX" | "0000000" | "XXXXXXX" |
invoicing.pec | obligatoire avec "0000000" | facultative | non utilisée |
address.region | obligatoire lorsque l’adresse est en Italie | obligatoire | non obligatoire |
name | raison sociale | gender, forename, surname | gender, forename, surname |
- Le code à 7 caractères que le destinataire vous a communiqué (p. ex.
ABC1234) : uniquement des lettres majuscules et des chiffres. "0000000": le destinataire n’a pas de boîte SDI — les consommateurs résidant en Italie, ainsi que les entreprises sans code SDI."XXXXXXX": le destinataire est à l’étranger (entreprise ou consommateur).
Destinataires professionnels (B2B)
Section intitulée « Destinataires professionnels (B2B) »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énario | destination_code | pec |
|---|---|---|
| Le destinataire a une boîte SDI enregistrée | son 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 pec est une adresse Posta Elettronica Certificata — la messagerie certifiée italienne. Elle est obligatoire pour un destinataire professionnel avec "0000000". Envoyez toujours la pec avec destination_code: "0000000" : fiskaly inscrit la PEC dans la FatturaPA en tant que PECDestinatario, vous n’avez donc jamais à renseigner cet élément vous-même.
recipients[].address.region (la Provincia du destinataire) n’est pas marquée comme obligatoire dans le schéma partagé de l’Unified API, mais l’Italie l’exige dès lors que l’adresse se situe en Italie. Si elle est absente, aucune réponse d’erreur n’est renvoyée : l’enregistrement revient en COMPLETED avec une entrée ERROR dans logs et sans used_in, et aucune facture n’est créée. Envoyez-la en deux lettres majuscules, par exemple RM. Les autres formes, comme IT-RM, rm ou Roma, sont acceptées mais ne figurent pas dans la facture.
Destinataires professionnels hors d’Italie
Section intitulée « Destinataires professionnels hors d’Italie »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 :
| Champ | Valeur |
|---|---|
recipients[].identification | VAT : le numéro de TVA étranger du destinataire |
recipients[].address.country | le pays du destinataire sous forme de code ISO 3166-1 alpha-2 (pas IT) |
recipients[].address.code | le 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.
Le SDI n’a aucun canal pour atteindre une entreprise à l’étranger : "XXXXXXX" ne fait que déclarer la facture. Envoyez séparément au destinataire son exemplaire (par exemple par e-mail ou via Peppol), en dehors du SDI. La vérification du numéro de TVA étranger dans VIES vous incombe ; fiskaly ne le vérifie pas dans VIES.
Destinataires consommateurs (B2C)
Section intitulée « Destinataires consommateurs (B2C) »La loi italienne interdit d’émettre des factures électroniques via le système d’échange (SDI) pour des prestations de santé fournies à des consommateurs finaux (personnes physiques). Ces factures ne doivent donc pas être émises avec E-INVOICE IT. Nous vous recommandons de vérifier auprès de votre conseiller fiscal si l’interdiction s’applique à vos factures.
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.
Consommateurs résidant en Italie
Section intitulée « Consommateurs résidant en Italie »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.
Pour un consommateur résidant en Italie, une identification est obligatoire, elle doit être de type TAX, et le codice fiscale est vérifié dès la création de l’enregistrement. S’il est absent ou mal formé, aucune réponse d’erreur n’est renvoyée : l’enregistrement revient en COMPLETED avec une entrée ERROR dans logs et sans used_in, et aucune facture n’est créée. Vérifiez toujours logs et used_in avant de considérer une facture comme émise. Le SDI le valide ensuite auprès du registre fiscal : un code bien formé mais inconnu y est rejeté.
Consommateurs hors d’Italie
Section intitulée « Consommateurs hors d’Italie »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.
| Champ | Valeur |
|---|---|
recipients[].identification | obligatoire ; VAT, TAX, PASSPORT, DOCUMENT ou OTHER, selon l’identifiant dont vous disposez |
recipients[].address.country | le pays du consommateur, code ISO 3166-1 alpha-2 |
recipients[].address.code | le 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.
"XXXXXXX" indique au SDI que le dédouanement est demandé mais que la remise via le système d’échange ne s’applique pas — le SDI n’a aucun canal pour atteindre un destinataire à l’étranger. Transmettez au consommateur son exemplaire de la facture (PDF ou équivalent) séparément, hors SDI.
gender est exigé par l’Unified API, pas par le SDI — la facture FatturaPA ne comporte aucun champ de ce type. Envoyez DIVERSE lorsque vous n’avez pas l’information.
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.
Traitement des réponses du SDI
Section intitulée « Traitement des réponses du SDI »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.
Les résultats du SDI arrivent généralement en quelques minutes, mais le SDI peut mettre jusqu’à 5 jours pour renvoyer un rejet : continuez donc d’interroger jusqu’à ce que le Record atteigne mode=FINISHED. Tant que l’état est ACCEPTED et le mode PROCESSING, interrogez environ toutes les 15 secondes.
Si la facture est transmise, les trois Records atteignent leur état final ensemble :
| Record | État final |
|---|---|
E_INVOICE::TRANSMISSION | COMPLETED ou FAILED, mode=FINISHED |
TRANSACTION::INVOICE | COMPLETED ou FAILED, mode=FINISHED |
INTENTION::TRANSACTION | COMPLETED 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.
Lire le résultat
Section intitulée « Lire le résultat »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 voyez | Ce que cela signifie | Ce 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=ACCEPTED | Toujours 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=FAILED | Terminé, 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 ERROR | Le 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.
Cela ne signifie pas que le destinataire l’a reçue. Le SDI signale comme succès à la fois la livraison (RC) et la non-livraison (MC, qui reste juridiquement valide), et l’API ne distingue pas les deux cas.
Où se manifestent les échecs de validation
Section intitulée « Où se manifestent les échecs de validation »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 échoue | Exemple | Ce que vous voyez |
|---|---|---|
| Contraintes de schéma | identification.number hors de AlphaNumerical28 ; document.number hors de ^[0-9A-Z_/\-\.]{1,20}$ | 400 de createRecord. Rien n’est créé. |
| Validation de champ | Un codice fiscale au format incorrect ou à la clé de contrôle erronée ; un recipients[].address.region manquant | createRecord 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 aval | Le SDI rejette la facture avec NS, ou la transmission échoue avant d’atteindre le SDI | createRecord 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. |
La ligne du milieu est celle qui piège les intégrateurs : un Record COMPLETED / FINISHED sans facture derrière lui ressemble exactement à un Record réussi si vous lisez state et vous arrêtez là. Lisez toujours content.logs à la recherche d’entrées ERROR et vérifiez que content.used_in est présent avant de considérer une facture comme émise.
Échecs et nouvelle soumission
Section intitulée « Échecs et nouvelle soumission »Si le SDI renvoie NS (Notifica di Scarto), la facture est juridiquement inexistante :
- Lisez
logs[].messagepour obtenir le motif de rejet du SDI. Il figure sur le RecordE_INVOICE::TRANSMISSIONet est aussi copié dans leslogsdes RecordsTRANSACTION::INVOICEetINTENTION::TRANSACTION - Créez une nouvelle
INTENTION::TRANSACTIONet une nouvelleTRANSACTION::INVOICEavec les données corrigées - Le rejet
NSouvre un nouveau délai de 5 jours. Pendant ce délai, vous pouvez renvoyer la facture avec le mêmedocument.number, sous forme de nouveaux Records avec une nouvelle clé d’idempotence. - La chaîne ayant échoué reste
FAILEDde façon permanente — elle est conservée à des fins d’audit
Chaque nouvelle soumission démarre une nouvelle chaîne de transaction — UAPI la traite comme une soumission entièrement nouvelle.
Réception de factures électroniques
Section intitulée « Réception de factures électroniques »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
JKKZDGRcomme 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.
TRANSMISSION_RECEPTION signifie que le System est en mesure de recevoir, mais pas que les factures entrantes sont effectivement remises au Taxpayer. Cette remise nécessite l’enregistrement AdE : tant qu’il n’est pas en place, le Taxpayer ne reçoit aucune facture, même lorsque le System est prêt. Vous pouvez effectuer l’enregistrement AdE à tout moment — par exemple, pour activer la réception sur un Taxpayer qui n’était auparavant configuré que pour l’émission.
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.
Si retrieveSystem continue de renvoyer compliance.state = TRANSMISSION_ONLY après la mise en service, l’enregistrement du Taxpayer ne s’est pas terminé. Traitez-le comme une transition bloquée et contactez le support fiskaly à dev-support@fiskaly.com en indiquant le numéro de TVA du Taxpayer afin que nous puissions enquêter.
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 arrive
Section intitulée « Lorsqu’une facture arrive »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.
Récupérer les factures reçues
Section intitulée « Récupérer les factures reçues »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 :
- Appelez
listRecordset filtrez surE_INVOICE::RECEPTION. - Pour chaque nouveau Record, appelez
retrieveRecordaveccompliance-artifactpour 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.
E-INVOICE IT partage son Taxpayer avec SIGN IT : les identifiants Fisconline sont donc nécessaires même si vous n’utilisez qu’E-INVOICE IT. C’est le fonctionnement actuel ; ce ne sera plus nécessaire lorsque la version complète de SIGN IT sera disponible.
Les identifiants ne doivent être valides qu’à deux moments : lors de la mise en service du Taxpayer, et chaque fois qu’il repasse de SUSPENDED à OPERATIVE. La création d’une facture (TRANSACTION::INVOICE) ne les vérifie pas : des identifiants expirés n’interrompent donc pas la facturation au quotidien.
Ils redeviennent importants la prochaine fois que vous avez besoin de ce passage SUSPENDED → OPERATIVE pour une autre raison — par exemple lors de la mise à jour de l’adresse du Taxpayer —, car la réactivation échoue si les identifiants ont expiré. Le mot de passe expire tous les 90 jours : vérifiez qu’il est toujours valide avant d’effectuer ce type de mise à jour.
Consultez Identifiants Fisconline pour savoir comment les obtenir et les renouveler.
Archivage
Section intitulée « Archivage »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.
Quand les artefacts deviennent disponibles
Section intitulée « Quand les artefacts deviennent disponibles »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 Record | Ce qu’il dit des artefacts |
|---|---|
state: ACCEPTED, mode: PROCESSING | Non terminal. Les artefacts peuvent encore manquer, et manquant signifie ici pas encore : ils arrivent. |
state: COMPLETED / FAILED / REJECTED, mode: FINISHED | Terminal. Ce qui est présent est tout ce qu’il y aura ; un artefact absent n’apparaîtra plus. |
Demander un artefact qui n’existe pas encore renvoie 200 avec le Record tel quel — aucune erreur et aucun signal « pas encore prêt ». Déterminez à partir du state et du mode du Record si un artefact absent signifie pas encore ou jamais, et non à partir de la réponse à la requête d’artefact.
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-artifactLe 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.
file-artifact renvoie l’enveloppe signée du Record tel qu’il a été soumis — un conteneur générique utilisé pour tous les types de Record, figé à la création du Record et sans lien avec la génération de la FatturaPA. C’est du XML bien formé, mais ce n’est pas la FatturaPA et il ne doit pas être enregistré comme la facture. Pour la FatturaPA, utilisez compliance-artifact.
Ni le reçu de conservation ni file-artifact ne sont une représentation de la facture. Pour une version lisible par un humain, téléchargez le paquet de fichiers de la transmission — un ZIP contenant le XML FatturaPA (le document juridiquement contraignant), un rendu PDF de la facture en italien et un JSON de métadonnées — depuis son propre endpoint :
GET /files/{transmissionId}.zipDans l’environnement de test, l’archivage s’exécute de bout en bout, mais le résultat n’a aucune validité juridique — il est destiné uniquement aux tests d’intégration. Seules les factures traitées en live sont certifiées comme légalement conservées.
Paiements
Section intitulée « Paiements »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 IBANname: le titulaire du compte, c’est-à-dire vous, l’émetteur de la facturepayment_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.
Droit de timbre (imposta di bollo)
Section intitulée « Droit de timbre (imposta di bollo) »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-artifactLe 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.
Créditer une facture émise en dehors de fiskaly
Section intitulée « Créditer une facture émise en dehors de fiskaly »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é.