Section navigation

E-INVOICE IT pour les clients SIGN IT

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.

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 : `HEAD_OFFICE` location : créée automatiquement à la création du Taxpayer — même ID que votre ancien `ENTITY` (`COMPANY`/`INDIVIDUAL`) `BRANCH` location : tout emplacement supplémentaire. Créée via l’endpoint `createLocation` — même ID que votre ancien `ENTITY` (`LOCATION`)
`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-Version avec la version indiquée dans la bannière ci-dessus.
Vérifiez que vous utilisez les bonnes URL de base : test.api.fiskaly.com (TEST) et live.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à

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_DEVICE mis en service sur la Location du Taxpayer
Un flux INTENTION::TRANSACTION → TRANSACTION::RECEIPT / TRANSACTION::CORRECTION / TRANSACTION::CANCELLATION pour 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

📘Pour l'instant, uniquement les Taxpayers COMPANY

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 (par ex. MI, RM) est obligatoire pour la transmission au SDI. 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 champ tax_regime prend ORDINARY par 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.

Exemple : PATCH /taxpayers/{taxpayer_id}

{
  "content": {
    "address": {
      "region": "MI"
    },
    "fiscalization": {
      "type": "IT",
      "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"
      }
    }
  }
}

💡Vous avez déjà address.region ?

Si votre intégration SIGN IT collecte déjà l’adresse complète du Taxpayer, y compris region, aucun changement n’est nécessaire ici — ajoutez simplement le bloc registration.

É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.

📘Vous souhaitez aussi recevoir ?

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.

⚠️Caution

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.

📘Si le System reste en TRANSMISSION_ONLY

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

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::INVOICE sur un System FISCAL_DEVICE (comme à l’étape 2)
Note de crédit → créez une TRANSACTION::CORRECTION avec data.type=INVOICE, faisant référence à la facture d’origine via record.id

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 = BUSINESS
recipients[].invoicing.type = SDI
recipients[].invoicing.destination_code — le code de boîte SDI du destinataire, sur 7 caractères
recipients[].invoicing.pec — (le cas échéant) l’adresse PEC du destinataire
recipients[].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 hors d’Italie	`"XXXXXXX"`	non utilisé

⚠️Indiquez la region (Provincia) du destinataire

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. Elle n’est pas vérifiée à la création de l’enregistrement : createRecord réussit et la transmission échoue plus tard, faisant passer toute la chaîne à FAILED.

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 = CONSUMER
recipients[].identification.type = TAX, avec number défini sur le codice fiscale du consommateur
recipients[].name — gender, forename et surname
recipients[].address — l’adresse de résidence du consommateur, y compris region (Provincia)
recipients[].invoicing.destination_code = "0000000", avec pec facultatif

📘Si vous ne disposez pas du sexe du consommateur

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

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 le System E_INVOICE_SERVICE à 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.

📘Le passage du ticket à la facture est en cours de développement

Nous construisons un parcours pris en charge qui relie un ticket fiscalisé et une facture électronique, afin qu’une même opération porte une seule facture et une seule piste d’audit. En attendant, recueillez la demande de facture avant la clôture de la transaction.

Traitement des réponses du SDI

Résultat asynchrone

Contrairement aux flux de reçus, le résultat du SDI est asynchrone. Après avoir créé la TRANSACTION::INVOICE, interrogez ou écoutez les mises à jour du Record E_INVOICE::TRANSMISSION.

💡Tip

Les résultats du SDI arrivent généralement en quelques minutes. Cependant, la spécification du SDI autorise jusqu’à 48 heures.

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, le motif de rejet du SDI est disponible dans logs[].message sur les trois Records.

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.

📘Note

L’artefact de conformité pour la facturation électronique italienne est le XML FatturaPA, accessible sur le Record E_INVOICE::TRANSMISSION.

É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 pré-SDI (asynchrone)	La facture est rejetée avant d’atteindre le SDI	Toute la chaîne atteint `state=FAILED` — une nouvelle chaîne est requise pour réessayer.
Rejet du SDI (asynchrone)	Le SDI renvoie `NS`	Toute la chaîne atteint `state=FAILED` — une nouvelle chaîne est requise pour réessayer.

Échecs et nouvelle soumission

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

Lisez logs[].message sur l’un des trois Records pour obtenir le motif de rejet du SDI
Créez une nouvelle INTENTION::TRANSACTION et une nouvelle TRANSACTION::INVOICE avec les données corrigées
Le même document.number peut être réutilisé dans les 5 jours suivant le rejet NS
La chaîne ayant échoué reste FAILED de façon permanente — elle est conservée à des fins d’audit

⚠️Aucune nouvelle tentative automatique

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

Les éléments suivants restent totalement inchangés :

Le flux de mise en service du Taxpayer et les identifiants Fisconline
Tous les Systems FISCAL_DEVICE et les Locations BRANCH
Votre flux de reçus INTENTION::TRANSACTION → TRANSACTION::RECEIPT / TRANSACTION::CORRECTION / TRANSACTION::CANCELLATION existant