Vous consultez la documentation de la version API 2026-06-01.
Ce guide s’adresse aux clients qui disposent déjà d’une intégration SIGN IT opérationnelle et souhaitent y ajouter la facturation électronique italienne (E-INVOICE IT) — B2B et B2C. Les deux produits reposent sur la même API Unifiée et partagent la même structure de Taxpayer et de Location — seuls quelques ajouts sont nécessaires.
E-INVOICE IT n’est disponible que sur 2026-06-01, et la version d’API s’applique à l’ensemble de votre intégration, et non par produit. Ajouter la facturation électronique implique donc de faire migrer aussi votre intégration SIGN IT existante vers 2026-06-01 : vos tickets ne peuvent pas rester sur 2025-08-12 pendant que les factures passent par 2026-06-01. Planifiez d’abord la migration de version ; les étapes ci-dessous supposent que vous êtes déjà sur 2026-06-01.
Vous venez de SIGN IT 2024-10-31 ou 2025-08-12 ? Développez et lisez ceci en premier.
Après la version 2025-08-12, certaines ressources ont été renommées et de nouvelles ont été ajoutées pour la facturation électronique. Les nouveaux endpoints peuvent être appelés avec les mêmes {id} déjà utilisés.
| Jusqu’à la version 2025-08-12 | Après la version 2025-08-12 | Remarques |
|---|---|---|
ASSET — /assets | ORGANIZATION — /organizations | Juste un renommage — même ID qu’avant. |
ENTITY (COMPANY/INDIVIDUAL) — /entities | TAXPAYER (COMPANY/INDIVIDUAL) — /taxpayers | Juste un renommage — même ID qu’avant. |
ENTITY (LOCATION) — /entities | LOCATION — /locations | Cette ressource est désormais divisée en deux types :
|
SYSTEM référençant entity: {id} | SYSTEM référençant location: {id} | Juste un renommage — même ID qu’avant. |
Avant de continuer :
- Mettez à jour votre en-tête
X-Api-Versionavec la version indiquée dans la bannière ci-dessus — pour tous vos appels, tickets compris. Il n’est pas possible de conserver les tickets sur l’ancienne version en parallèle de la facturation électronique. - Vérifiez que vous utilisez les bonnes URL de base :
test.api.fiskaly.com(TEST) etlive.api.fiskaly.com(LIVE). - Ajoutez
fiscalization.credentials.tax_id_numberà vos identifiants FISCONLINE, si ce n’est pas déjà fait. Ce champ n’était pas requis en 2024-10-31, était optionnel en 2025-08-12, mais est désormais obligatoire. - Consultez les principaux changements de structure des records dans la documentation de l’API — cette FAQ peut vous aider. Pour toute question, contactez dev-support@fiskaly.com.
Ce que votre intégration SIGN IT couvre déjà
Section intitulée « Ce que votre intégration SIGN IT couvre déjà »Avant de commencer, on suppose que votre intégration comprend :
- Un Taxpayer créé avec des données de fiscalisation italiennes (
fiscalization.type=IT,tax_id_number,vat_id_number,credentials) - Le Taxpayer mis en service (
state=COMMISSIONED,mode=OPERATIVE) - Un System
FISCAL_DEVICEmis en service sur la Location du Taxpayer - Un flux
INTENTION::TRANSACTION→TRANSACTION::RECEIPT/TRANSACTION::CORRECTION/TRANSACTION::CANCELLATIONpour les reçus fiscaux
Rien de tout cela ne doit changer. Les étapes ci-dessous ajoutent E-INVOICE IT à la configuration existante.
Compléter les données d'enregistrement du Taxpayer
Ajoutez les informations d'enregistrement d'entreprise supplémentaires requises par la facturation électronique italienne.
Mettre en service un System supplémentaire
Activez le service de facturation électronique sur votre Taxpayer — cela couvre l'envoi et, en option, la réception.
Ajouter le flux de transaction de facture
Commencez à émettre des factures et des notes de crédit aux entreprises et aux consommateurs.
Étape 1 — Compléter les données d’enregistrement du Taxpayer
Section intitulée « Étape 1 — Compléter les données d’enregistrement du Taxpayer »E-INVOICE IT prend actuellement en charge les Taxpayers de type COMPANY. 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é — ne peut pas encore être étendu ; la prise en charge arrive bientôt.
Deux ajouts sont nécessaires sur le Taxpayer dont SIGN IT seul n’a pas besoin :
-
address.region— le code de Provincia italien est obligatoire pour la transmission au SDI : deux lettres majuscules, par exempleMIouRM. S’il n’est pas déjà défini sur le Taxpayer, ajoutez-le via updateTaxpayer. -
fiscalization.registration— un nouveau bloc contenant les données du Registro delle Imprese / REA.Champs obligatoires :
company_id,office,entry,legal_form,capital,shareholder_status,liquidation_status. Le champtax_regimeprendORDINARYpar défaut si vous ne le renseignez pas.Le SDI exige ce bloc pour les entités enregistrées ; fournissez-le lors de l’enregistrement du Taxpayer.
address et fiscalization ne peuvent être modifiés que lorsque le Taxpayer est ACQUIRED, ou COMMISSIONED avec mode SUSPENDED. Sur un Taxpayer opérationnel, un PATCH est refusé (HTTP 405). Chaque bloc envoyé remplace intégralement le bloc enregistré : envoyez-le donc complet, valeurs existantes comprises. Voir Puis-je mettre à jour les données du Taxpayer ? et Comment mettre à jour les identifiants FISCONLINE.
Exemple : trois requêtes pour ajouter les données d’immatriculation
1. Suspendre le Taxpayer — PATCH /taxpayers/{taxpayer_id}
{ "content": { "mode": "SUSPENDED" }}2. Envoyer les blocs complets — PATCH /taxpayers/{taxpayer_id}. Reprenez vos valeurs existantes et ajoutez registration (et region, si elle manque) :
{ "content": { "address": { "line": { "type": "STREET_NUMBER", "street": "Via Milano", "number": "42" }, "code": "20121", "city": "Milano", "country": "IT", "region": "MI" }, "fiscalization": { "type": "IT", "tax_id_number": "12345678901", "vat_id_number": "12345678901", "credentials": { "type": "FISCONLINE", "tax_id_number": "RSSMRA85M01H501Z", "password": "<your-password>", "pin": "<your-pin>" }, "registration": { "company_id": "MI12345678901234567", "office": "MI", "entry": "1234567", "legal_form": "LIMITED_LIABILITY_COMPANY", "capital": "10000.00", "shareholder_status": "MULTIPLE_SHAREHOLDERS", "liquidation_status": "NOT_IN_LIQUIDATION" } } }}3. Remettre le Taxpayer en mode opérationnel — PATCH /taxpayers/{taxpayer_id}
{ "content": { "mode": "OPERATIVE" }}Si le Taxpayer a déjà address.region, n’incluez pas le bloc address dans la requête. Seuls les blocs envoyés sont remplacés, et chacun doit être complet : fiscalization exige toujours type, tax_id_number, vat_id_number et credentials à côté du nouveau registration.
Étape 2 — Mettre en service un System supplémentaire
Section intitulée « Étape 2 — Mettre en service un System supplémentaire »Le System E_INVOICE_SERVICE est le seul System qui crée et transmet des factures électroniques (et reçoit les factures entrantes). Il ne remplace pas vos Systems FISCAL_DEVICE : vous créez toujours l’enregistrement de facture (TRANSACTION::INVOICE) sur un System FISCAL_DEVICE (n’importe lequel sur le même Taxpayer), et le System E_INVOICE_SERVICE transforme ces données en facture électronique.
La réception est facultative. Si vous la souhaitez, définissez le code destinataire SDI de fiskaly JKKZDGR comme destination SDI de votre entreprise dans votre portail Agenzia delle Entrate (AdE) — à tout moment, avant ou après la mise en service. Sans cela, le Taxpayer ne recevra pas de factures, même une fois le System prêt. Ignorez cette étape si le Taxpayer ne fait qu’émettre.
Utilisez createSystem pour créer un System E_INVOICE_SERVICE sur la Location HEAD_OFFICE du Taxpayer, puis mettez-le en service via updateSystem en définissant son state sur COMMISSIONED.
Un seul System E_INVOICE_SERVICE peut être mis en service par Taxpayer, sur la Location HEAD_OFFICE (créée automatiquement avec le Taxpayer) — la mise en service d’un second échoue. Il reste distinct des Systems FISCAL_DEVICE utilisés pour la fiscalisation des reçus, qui ne sont pas affectés, quel que soit leur nombre.
La réponse de mise en service indique toujours TRANSMISSION_ONLY ; appelez ensuite retrieveSystem pour lire le compliance.state réel du System. S’il reste à TRANSMISSION_ONLY au lieu de passer à TRANSMISSION_RECEPTION, 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.
Pour le flux de réception complet, consultez Réception des factures électroniques sur la page Italie.
Étape 3 — Ajouter le flux de transaction de facture
Section intitulée « Étape 3 — Ajouter le flux de transaction de facture »SIGN IT utilise TRANSACTION::RECEIPT / TRANSACTION::CORRECTION / TRANSACTION::CANCELLATION.
E-INVOICE IT utilise différents types de transaction dans le même conteneur INTENTION::TRANSACTION :
- Facture (B2B ou B2C) → créez une
TRANSACTION::INVOICEsur un SystemFISCAL_DEVICE(comme à l’étape 2) - Note de crédit → créez une
TRANSACTION::CORRECTIONavecdata.type=INVOICE, faisant référence à la facture d’origine viarecord.id
Sur une note de crédit, définissez entries[].type = RETURN sur chaque ligne créditée. Toutes les lignes d’une TRANSACTION::CORRECTION avec data.type=INVOICE sont créditées, quel que soit leur type de ligne : une ligne envoyée avec SALE est donc acceptée et tout de même créditée. Une note de crédit ne peut pas facturer en plus de nouveaux articles ; émettez une facture distincte pour ceux-ci.
Les destinataires de type BUSINESS et CONSUMER sont tous deux pris en charge. Pour un destinataire professionnel, l’entrée du tableau recipients de la facture doit disposer d’un bloc invoicing de type SDI, ainsi que de la Provincia du destinataire :
recipients[].type=BUSINESSrecipients[].invoicing.type=SDIrecipients[].invoicing.destination_code— le code de boîte SDI du destinataire, sur 7 caractèresrecipients[].invoicing.pec— (le cas échéant) l’adresse PEC du destinatairerecipients[].address.region— la Provincia du destinataire (p. ex.MI,RM)
| Scénario | destination_code | pec |
|---|---|---|
| Le destinataire a une boîte SDI enregistrée | son code à 7 caractères, uniquement des lettres majuscules et des chiffres (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é |
Pour une entreprise hors d’Italie, envoyez destination_code: "XXXXXXX" avec le numéro de TVA étranger du destinataire ; voir Destinataires professionnels hors d’Italie.
Indiquez la Provincia du destinataire dans recipients[].address.region. Elle n’est pas marquée comme obligatoire dans le schéma Unified API partagé, 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.
Pour un destinataire consommateur (B2C), les champs diffèrent : pas de destination_code au choix du destinataire ni de numéro de TVA, mais le codice fiscale est obligatoire :
recipients[].type=CONSUMERrecipients[].identification.type=TAX, avecnumberdéfini sur le codice fiscale du consommateurrecipients[].name—gender,forenameetsurnamerecipients[].address— l’adresse de résidence du consommateur, y comprisregion(Provincia)recipients[].invoicing.destination_code="0000000", avecpecfacultatif
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 les exigences complètes relatives au destinataire, consultez Envoi de factures électroniques sur la page Italie.
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 »Vos deux flux déclarent à des endroits différents — le ticket à l’AdE, la facture au 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 sur votre System FISCAL_DEVICE à la place du ticket. C’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 »Résultat asynchrone
Section intitulée « Résultat asynchrone »Contrairement aux flux de reçus, le résultat du SDI est asynchrone. Après avoir créé la TRANSACTION::INVOICE, 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.
Pour plus de détails, consultez How to check the status of an e-invoice sur notre page d’assistance.
Les factures électroniques envoyées et reçues sont automatiquement conservées à long terme (conservazione a norma, au moins 10 ans), avec un reçu de conservation disponible depuis l’archive-artifact du Record. Aucune configuration n’est requise. Consultez Archivage sur la page Italie pour plus de détails.
L’artefact de conformité pour la facturation électronique italienne est le XML FatturaPA, accessible sur le Record E_INVOICE::TRANSMISSION.
Étapes d’erreur
Section intitulée « Étapes d’erreur »Les erreurs peuvent survenir à trois étapes distinctes, chacune avec un comportement différent :
| Étape | Quand | Comportement |
|---|---|---|
| Validation UAPI (synchrone) | Payload invalide | 4xx renvoyé immédiatement — aucun Record n’est créé. Corrigez le payload et réessayez sur le même INTENTION::TRANSACTION. |
| Validation de champ (asynchrone) | Données invalides dans un payload accepté, par ex. un codice fiscale au format incorrect ou à la clé de contrôle erronée, ou un recipients[].address.region manquant | Le Record se ferme en COMPLETED / FINISHED avec une entrée ERROR dans content.logs et sans content.used_in. Rien n’est transmis. Corrigez les données et démarrez une nouvelle chaîne. |
| Rejet du SDI (asynchrone) | Le SDI renvoie NS | Toute la chaîne atteint state=FAILED — une nouvelle chaîne est requise pour réessayer. |
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[].messagesur le RecordE_INVOICE::TRANSMISSIONpour obtenir le motif de rejet du SDI - 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.
Ce qui ne change pas
Section intitulée « Ce qui ne change pas »Les éléments suivants restent totalement inchangés :
- Le flux de mise en service du Taxpayer et les identifiants Fisconline
- Tous les Systems
FISCAL_DEVICEet les LocationsBRANCH - Votre flux de reçus
INTENTION::TRANSACTION→TRANSACTION::RECEIPT/TRANSACTION::CORRECTION/TRANSACTION::CANCELLATIONexistant