E-INVOICE IT pour les clients SIGN IT

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 B2B italienne (E-INVOICE IT). 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.

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 pour les reçus fiscaux

Rien de tout cela ne doit changer. Les étapes ci-dessous ajoutent E-INVOICE IT à la configuration existante.

Étape 1 — Compléter les données d’enregistrement du Taxpayer

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. tax_regime est facultatif (valeur par défaut ORDINARY). Ce bloc est facultatif au niveau de l’API, mais le SDI l’exige pour les entités enregistrées et il doit être fourni lors de l’enregistrement.

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

Utilisez createSystem pour créer un System E_INVOICE_SERVICE sur la Location du Taxpayer, puis mettez-le en service via updateSystem.

📘Note

Un seul System E_INVOICE_SERVICE est nécessaire par Taxpayer, lié à la Location HEAD_OFFICE — qui est créée automatiquement lors de la création du Taxpayer. Cela est distinct des Systems FISCAL_DEVICE utilisés pour la fiscalisation des reçus, qui sont liés à des Locations BRANCH individuelles et peuvent exister en nombre illimité à côté.

Étape 3 — Ajouter le flux de transaction de facture

SIGN IT utilise TRANSACTION::RECEIPT. E-INVOICE IT utilise un type de transaction différent dans le même conteneur INTENTION::TRANSACTION :

Facture B2B → créez une TRANSACTION::INVOICE liée au System E_INVOICE_SERVICE
Note de crédit → créez une TRANSACTION::CORRECTION avec data.type=INVOICE, faisant référence à la facture d’origine via record.id

📘B2B uniquement

Seuls les destinataires de type BUSINESS sont pris en charge. Le destinataire doit disposer d’un bloc invoicing de type SDI avec un destination_code valide. Les factures B2C sont actuellement hors périmètre.

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.

📘Note

L’artefact de conformité pour la facturation électronique italienne est le XML FatturaPA, accessible 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.

É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 Invopop (asynchrone)	Invopop rejette 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 existant

Was this page helpful?