Intégration étape par étape

⚠️ Vous consultez la documentation de la version d’API 2025-08-12. La dernière version est 2026-05-04. Les changements clés 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 réussir votre intégration, pour laquelle vous devrez utiliser notre SIGN FR.

Étape 1 : Inscription

Commencez par vous inscrire sur le HUB.

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 Clé API.

📘Tutoriel vidéo

Consultez notre vidéo pour une explication étape par étape sur la configuration de votre compte et de votre première organisation.

Étape 2 : Création de votre première organisation

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

Étape 3 : Génération de la Clé API

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

Notez que les Clés API 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, consultez notre article sur les environnements TEST et LIVE.

À partir de l’étape suivante, vous utiliserez notre API SIGN FR.

Étape 4 : GESTION - Création d’un Token

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

Étape 5 : GESTION - Création d’un Asset (Structure organisationnelle)

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 HUB. Pour ce faire, utilisez le token généré à partir des clés API créées dans la première organisation. Cela reflète la structure hiérarchique dans laquelle le UNIT est imbriqué sous la première organisation.

Étape 6 : GESTION - Création d’un Subject

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

Étape 7 : GESTION - Création d’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 : OPÉRATION - Création d’une Entity (Représentation du contribuable)

Vous êtes maintenant prêt à commencer à créer les parties opérationnelles nécessaires à la fiscalisation en France. 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 (entreprise) ou Individual (travailleur indépendant/entrepreneur individuel). Dans les deux cas, le name et l’address doivent être fournis.
• Au sein des informations de fiscalization françaises, les données suivantes du contribuable doivent être fournies :
  • tax_id_number : Numéro d’identification d’entreprise française (numéro SIREN) délivré par l’INSEE,
  • credentials : Identifiants de fiscalisation française.

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

Étape 9 : OPÉRATION - Création d’une Entity Localisation

Pour chaque emplacement d’exploitation, 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 procéder, vous devez changer l’état en COMMISSIONED en utilisant l’endpoint updateEntity.

Étape 10 : OPÉRATION - Création d’un System (Représentation du système de caisse)

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 en tant que nouveau System dans SIGN FR. Pour ce faire, 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 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 du logiciel et la version installée sur l’appareil. Ces informations garantissent un suivi correct de l’appareil effectuant 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 sur COMMISSIONED en utilisant l’endpoint updateSystem.

Étape 11 : OPÉRATION - Création d’un Record

💡Tip

La création d’un Record dans SIGN FR nécessitera dans la plupart des cas deux appels successifs :

• Partie A) INTENTION - au début du processus de vente - Partie B) TRANSACTION - directement après le processus de paiement

Opération de transaction

PARTIE A) Intention

Pour chaque opération commerciale de type RECEIPT effectuée dans la caisse enregistreuse ou le système de caisse, l’endpoint createRecord de l’API SIGN FR 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 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 entend effectuer est l’enregistrement d’une transaction.

Partie B) Transaction

L’étape finale pour émettre un reçu conforme en France 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 France :

• RECEIPT : Cette opération contient toutes les informations requises pour la création d’un document commercial de vente en France :
  • 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 sur 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 record précédemment créé doit être fourni.

Opérations supplémentaires

En plus du flux standard Intention → Transaction, SIGN FR prend en charge les opérations suivantes :

• DUPLICATE
• EXPORT
• EVENT

Ces opérations sont créées en tant que Record de type Intention (avec l’opération DUPLICATE, EXPORT ou EVENT) et ne nécessitent pas d’appel Transaction ultérieur. Elles permettent que des activités supplémentaires du système de caisse soient signées, journalisées et archivées au-delà du flux de transactions standard.

---

Dans tous les cas, une fois que le record est correctement créé, les données seront signées, journalisées et archivées pour satisfaire aux trois obligations fiscales clés en France.