Intégration étape par étape

⚠️ Vous consultez la documentation pour la version API 2025-08-12. La dernière version est 2026-05-04. Les principaux changements incluent la terminologie mise à jour (Asset → Organization, Entity → Taxpayer/Location).

Pour commencer le processus d’intégration, veuillez vous référer aux instructions détaillées étape par étape fournies ici.

Le diagramme ci-joint illustre le flux de travail et met en évidence les étapes essentielles nécessaires pour compléter avec succès votre intégration, pour laquelle vous devrez utiliser notre SIGN IT.

Étape 1 : S’inscrire sur le Dashboard

Commencez par vous inscrire sur le Dashboard.

La création d’un compte fiskaly est la première étape, après quoi vous pouvez procéder à la mise en place de la première structure organisationnelle pour votre entreprise et générer votre API Key.

📘video tutorial

Regardez notre vidéo pour une explication étape par étape sur la façon de configurer votre compte et votre première organisation.

Étape 2 : Créer la première organisation

Continuez en créant votre première organisation via le Dashboard. Cette organisation représentera le fournisseur POS ou le détaillant avec son propre système POS.

Étape 3 : Créer une API Key

L’étape suivante consiste à générer une API Key pour votre organisation via le Dashboard. Cette paire API Key et secret est requise pour créer votre premier Asset de type UNIT (Étape 5).

Notez que les API Keys générées dans l’environnement TEST créeront des ressources TEST, tandis que celles de l’environnement LIVE créeront des ressources LIVE. Pour plus de détails, référez-vous à notre article sur les environnements TEST et LIVE.

À partir de l’étape suivante, vous utiliserez notre API SIGN IT. Vous pouvez télécharger notre collection Postman pour SIGN IT, qui pourrait faciliter votre intégration pour les étapes suivantes.

Étape 4 : MANAGEMENT - Créer un Token

Commencez à utiliser l’API SIGN IT via l’endpoint createToken. Vous devrez créer un token pour vous authentifier pour les étapes suivantes.

Étape 5 : MANAGEMENT - Créer un Asset UNIT

Continuez en créant un Asset de type UNIT via l’endpoint createAsset. Vous devrez créer un Asset UNIT pour chacune de vos représentations de contribuables.

Lors de la création de votre premier Asset de type UNIT, assurez-vous qu’il est associé à l’UUID de la première organisation que vous avez créée via le Dashboard. Pour ce faire, utilisez le token généré à partir des API Keys créées dans la première organisation. Cela reflète la structure hiérarchique où la UNIT est imbriquée sous la première organisation.

Étape 6 : MANAGEMENT - Créer un Subject (Clé API)

Créez un Subject de type API_KEY via l’endpoint createSubject. La connexion entre l’Asset UNIT et la API Key est établie via le X-Scope-Identifier (en utilisant l’id de l’Asset nouvellement créé).

Étape 7 : MANAGEMENT - Créer un nouveau Token

Ensuite, créez un token qui sera utilisé pour créer des ressources au sein de l’Asset UNIT correspondant.

Étape 8 : OPERATION - Créer une Entity COMPANY ou INDIVIDUAL

Vous êtes maintenant prêt à commencer à créer les parties opérationnelles requises pour la fiscalisation en Italie. Pour ce faire, utilisez l’endpoint createEntity pour créer la représentation d’un Contribuable comme suit :

• Vous devrez définir le Contribuable comme une Entity de type Company (personne morale) ou Individual (personne physique). Dans les deux cas, le name et l’address doivent être fournis.
• Dans les informations de fiscalization italiennes, les données de contribuable suivantes doivent être fournies :
  • tax_id_number : Code fiscal italien (Codice fiscale),
  • vat_id_number : Numéro de TVA italien (Partita IVA),
  • credentials : PIN et mot de passe requis pour accéder aux services de l’AdE. Pour plus d’informations, veuillez consulter notre section Identifiants.

Une fois que vous créez une Entity, de type Company ou Individual, son state sera défini sur ACQUIRED. Pour être entièrement fonctionnelle, l’état doit être mis à jour à COMMISSIONED en utilisant l’endpoint updateEntity.

📘Note

Seuls les identifiants Fisconline sont valides pour utiliser SIGN IT lite. Vos identifiants doivent être mis à jour tous les 60 jours.

📘important

Le contribuable doit effectuer manuellement une première connexion au portail web de l’Agence des impôts afin de s’assurer que les identifiants fonctionnent correctement et d’accepter les conditions, termes et clauses supplémentaires prévus.

Étape 9 : OPERATION - Créer une Entity LOCATION

Pour chaque emplacement commercial opérationnel, vous devez créer une Entity de type Location via l’endpoint createEntity.

Lorsque vous créez une Entity de type Location, son state est initialement défini sur ACQUIRED. Pour continuer, vous devez changer l’état à COMMISSIONED en utilisant l’endpoint updateEntity.

Étape 10 : OPERATION - Créer un System

L’endpoint createSystem vous permet de créer une abstraction de chaque appareil que vous utilisez pour émettre des reçus. Cela signifie que chaque caisse enregistreuse ou point de vente doit être fourni comme un nouveau System dans l’API SIGN IT. Pour cela, le type de System FISCAL_DEVICE doit être sélectionné.

• Un System sera connecté à une Entity déjà créée (qu’il s’agisse de type Company ou Individual, ou d’un Location spécifique si différent de l’adresse légale).
• Pour chaque appareil, vous devrez fournir des informations sur le produit telles que le MPN, la marque et la date de début d’utilisation, ainsi que le nom et la version du logiciel installé sur l’appareil. Ces informations garantissent un suivi correct de quel appareil effectue les transactions fiscales.

Lorsque vous créez un System, son état initial est défini sur ACQUIRED. Pour créer des Records, son state doit être mis à jour à COMMISSIONED en utilisant l’endpoint updateSystem.

Étape 11 : OPERATION - Créer un Record

💡Tip

La création d’un Record dans l’API SIGN IT nécessitera toujours deux appels successifs : Partie A) INTENTION (au début du processus de vente) et Partie B) TRANSACTION (directement après le processus de paiement).

PARTIE A) Intention

Pour chaque opération commerciale effectuée dans la caisse enregistreuse ou le POS, l’endpoint createRecord de l’API SIGN IT sera utilisé en deux appels : le premier pour enregistrer l’intention de démarrer une transaction, et le second pour fournir les données de la transaction.

Un Record de type Intention contiendra les informations suivantes :

• Association avec un System qui effectuera la transaction.
• Operation de type Transaction : Cela signifie que l’opération que le System a l’intention d’effectuer est l’enregistrement d’une transaction.

Partie B) Transaction

La dernière étape pour émettre un reçu conforme en Italie est d’effectuer un autre appel à l’endpoint createRecord, en indiquant un Record de type Transaction.

Tout document Transaction sera associé à l’identifiant interne d’un Record de type Intention déjà créé, et peut contenir des détails à des fins de formation (documents émis en mode formation ou test).

La Transaction peut être utilisée pour effectuer l’une des opérations suivantes en Italie :

• RECEIPT : Cette opération contient toutes les informations requises pour la création d’un Document commercial de vente en Italie :
  • Informations sur le document telles que le numéro, le code d’activité (le cas échéant), la date de la transaction et les montants totaux du document (TVA incluse et exclue)
  • Informations de chaque entrée ou ligne vendue dans l’opération :
    • Identification d’une Vente
    • Description
    • Indication si c’est un bien ou un service
• CORRECTION : Ce type d’opération est utilisé pour représenter tout processus de retour effectué. Il contient les mêmes données qu’une opération de type RECEIPT, et en plus :
  • id de référence à un reçu déjà créé (document de transaction original)
• CANCELLATION : Cette opération est utilisée pour invalider une transaction entière. Pour cela, l’id d’un enregistrement précédemment créé doit être fourni.

Dans tous les cas, une fois la transaction correctement enregistrée et les informations du document commercial transmises avec succès au portail web de l’AdE, la réponse conforme de la création de l’enregistrement indiquera le numéro progressif attribué par l’AdE au document commercial et le code Loterie du consommateur (si fourni dans le payload transmis).

📘Note

Tous les enregistrements créés dans l’environnement LIVE sont transmis aux Autorités Fiscales et génèrent des documents commerciaux valides. Par conséquent, ces documents doivent toujours refléter des transactions réelles.