Intégration Étape par Étape

⚠️ Vous consultez la documentation de la version API 2024-10-31. La version la plus récente est 2026-05-04. Les principaux changements incluent une 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 laquelle vous pouvez procéder à la configuration de la première structure organisationnelle pour votre entreprise et à la génération de 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 de POS ou le détaillant avec son propre système POS.

Étape 3 : Créer la 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 nécessaire 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, reportez-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 dans les prochaines étapes.

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

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ù l’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 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 (entité légale) ou Individual (personne physique). Dans les deux cas, name et address doivent être fournis.
• Dans les informations de fiscalization italiennes, les données du 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 nécessaires 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 pleinement 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 revenus afin de s’assurer que les identifiants fonctionnent correctement et d’accepter les conditions générales et clauses supplémentaires fournies.

Étape 9 : OPERATION - Créer Entity LOCATION

Pour chaque emplacement d’activité 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 dispositif 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’elle soit de type Company ou Individual, ou un emplacement spécifique si différent de l’adresse légale).
• Pour chaque dispositif, 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 le dispositif. Ces informations assurent un suivi correct du dispositif effectuant des 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 (dès le 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.
• Opération 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 consiste à effectuer un autre appel à l’endpoint createRecord, indiquant un Record de type Transaction.

Tout document de 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 transaction et les montants totaux du document (TVA comprise et hors TVA)
  • Informations de chaque entrée ou ligne d’article vendu dans l’opération :
    • Identification d’une Vente
    • Description
    • Indication s’il s’agit d’un bien ou d’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 (s’il est 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.