Pour les clients de SIGN DE

⚠️ 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).

Guide d’intégration de SIGN FR pour les clients de SIGN DE

Ce guide explique les différences clés par rapport à SIGN DE et vous aide à intégrer avec succès l’API fiskaly SIGN FR. Il décrit toutes les étapes nécessaires pour vous et vos commerçants.

Approche API unifiée

SIGN FR fait partie de l’approche API unifiée de fiskaly. Cela signifie qu’en intégrant SIGN FR, vous êtes déjà prêt à utiliser SIGN IT (Italie) et SIGN ES (Espagne), ainsi que d’autres pays à venir, avec un effort supplémentaire minimal.

Contrairement à SIGN DE, SIGN FR ne nécessite pas d’Management API séparée. Tous les endpoints nécessaires pour l’authentification, la création d’assets, la configuration et la gestion des enregistrements fiscaux sont inclus directement dans l’API SIGN FR, rendant l’intégration plus rapide et plus simple.

Environnements : TEST et LIVE

Dans SIGN FR, il y a deux URL de base séparées pour les différents environnements :

Environnement TEST : https://test.api.fiskaly.com
Environnement LIVE : https://live.api.fiskaly.com

C’est différent de SIGN DE, où il n’y a qu’une seule URL de base pour les deux environnements.
Dans SIGN DE, la Clé API elle-même détermine si des ressources TEST ou LIVE sont créées.
Un token créé avec une Clé API LIVE crée des ressources LIVE.
Un token créé avec une Clé API TEST crée des ressources TEST — même si l’URL reste la même.

Dans SIGN FR, l’environnement est sélectionné via l’URL de base.
Vous devez appeler chaque endpoint avec la bonne URL de base (test.api.fiskaly.com ou live.api.fiskaly.com), selon que vous souhaitez interagir avec l’environnement TEST ou LIVE.

Paramètres d’en-tête

Dans l’approche API unifiée, de nouveaux en-têtes HTTP ont été introduits pour simplifier vos processus.
Ils offrent de la flexibilité, garantissent l’intégrité des données et rendent les intégrations plus simples et plus fiables.

X-Api-Version

Pour toutes les solutions d’API unifiée, chaque requête doit inclure l’en-tête X-Api-Version.
La valeur correspond à la date de publication de la version. Cela vous donne un contrôle total sur le moment où vous passez à une version plus récente pour utiliser de nouvelles fonctionnalités.

Vous pouvez tester les modifications en premier dans l’environnement TEST et ne migrer vers la nouvelle version qu’une fois que tout a été vérifié. Cela vous permet également de maintenir certains clients sur une version plus ancienne si nécessaire, tout en intégrant directement les nouveaux clients avec la dernière version.

Avantage principal : plus de changements incompatibles dans votre version en cours d’exécution.

X-Idempotency-Key

Puisque les IDs de ressources n’ont plus besoin d’être définis par vous mais sont générés par l’API, l’X-Idempotency-Key garantit qu’un appel API est traité de manière idempotente.

Cela signifie que des requêtes identiques répétées avec le même X-Idempotency-Key produisent le même résultat et empêchent les créations en double.

L’X-Idempotency-Key est obligatoire pour toutes les requêtes POST et PATCH.

X-Scope-Identifier

L’en-tête X-Scope-Identifier remplace les paramètres de chemin précédemment utilisés dans la Management API pour établir des relations entre les ressources.

Il rend les intégrations plus propres et plus flexibles, car l’en-tête définit explicitement la portée (par exemple, à quel Asset::Unit appartient une Clé API).

Correspondance de terminologie : SIGN FR vs. SIGN DE

SIGN FR	SIGN DE	Explication
`Asset::Tenant`	(pas d’équivalent)	Structure de niveau supérieur dans le fiskaly HUB. Représente l’ensemble du compte client. Ne peut pas être imbriquée dans d’autres assets.
`Asset::Group` (optionnel)	`organization` (avec `billing_options`)	Couche intermédiaire optionnelle utilisée pour organiser plusieurs contribuables en groupes logiques.
`Asset::Unit`	`managed_organization`	Représente un commerçant ou un contribuable individuel. Chaque `Asset::Unit` est lié à un contribuable via une `Entity`.
`Entity::COMPANY` ou `Entity::INDIVIDUAL`	En Allemagne, partie de la `managed_organization` (DSFINVK DE) ou `taxpayer` (SUBMIT DE)	Définit le contribuable pour l’`Asset::Unit` lié, nécessaire pour remplir les obligations fiscales.
`Entity::LOCATION`	Comparable : `establishment` (SUBMIT DE)	Représente les emplacements physiques (ex. boutiques) exploités par le contribuable.
`System::FISCAL_DEVICE`	`client`	Représente le système de caisse / caisse enregistreuse utilisé pour la fiscalisation.
`Subject::API_KEY`	`API key`	Objet d’authentification par clé API, utilisé pour autoriser l’accès.
`Record`	`transaction`	Représente une opération effectuée sur la caisse enregistreuse. Pour les événements spéciaux, il peut ne consister qu’en un `Record::INTENTION`. Pour les transactions, il nécessite toujours deux appels : un `Record::INTENTION` et un `Record::TRANSACTION`.
`Record::INTENTION`	`Start-Transaction`	Marque le début d’un processus d’achat, ou un seul autre événement traité sur la caisse enregistreuse.
`Record::TRANSACTION`	`Finish-Transaction`	Marque l’achèvement (fin) d’un processus d’achat.

SIGN FR étape par étape

Première organisation

Pour commencer, vous devez créer une organisation séparée spécifiquement pour la France dans le fiskaly HUB et une Clé API dédiée pour l’intégration française.

À partir de ce moment, toutes les étapes d’intégration sont gérées directement via l’API SIGN FR. Contrairement à SIGN DE, vous n’avez plus besoin d’utiliser l’Management API pour créer ou gérer des structures organisationnelles. Toute la fonctionnalité requise fait partie de l’API SIGN FR elle-même.

POST : Créer un Token

Utilisez ce token pour authentifier la création de la structure organisationnelle pour la France.
Il fonctionne de la même manière que le token dans SIGN DE (Management API), qui était créé avec la Clé API de l’organisation (principale) et ensuite utilisé pour créer des managed_organizations.
Dans SIGN FR, ce token est maintenant requis pour créer des ressources Asset::Unit.

POST : Créer un Asset (UNIT)

Créez un Asset::UNIT (Asset de type Unit) représentant votre premier client. Cela équivaut à la managed_organization créée via l’Management API utilisée pour SIGN DE.

À cette étape, seul le nom de l’Asset::Unit est requis.
Contrairement à SIGN DE, les informations sur le contribuable appartiennent à la ressource Entity, qui peut être de type COMPANY ou INDIVIDUAL, selon que le contribuable est une personne morale ou physique. Vous définirez ces détails à l’étape Entity (COMPANY / INDIVIDUAL) ci-dessous.

POST : Créer un Subject (Clé API)

Chacun de vos clients nécessite sa propre Clé API pour créer des ressources dans sa portée Asset::Unit spécifique.
C’est pourquoi un Subject::API_KEY (Subject de type Clé API) doit être créé.

Liez votre Clé API à l’Asset::Unit en utilisant l’en-tête X-Scope-Identifier.

Contrairement à SIGN DE, les informations sur l’Unit à laquelle appartient la Clé API ne sont plus fournies via le paramètre de chemin, mais via le paramètre d’en-tête X-Scope-Identifier.
Cet en-tête doit contenir l’ID de l’Asset::UNIT auquel appartient la Clé API.

POST : Créer un Token (avec portée)

Ce token est délimité à l’Asset::Unit. Utilisez-le pour toutes les opérations spécifiques au contribuable.

Avec la Clé API précédemment créée pour l’Asset::Unit, vous devez créer ce token délimité.
Il sera utilisé pour toutes les opérations qui doivent être gérées au sein de cet Asset::Unit spécifique.

POST : Créer une Entity (COMPANY / INDIVIDUAL)

Définit la représentation du contribuable pour l’Asset::Unit correspondant.

Une Entity de type COMPANY ou INDIVIDUAL représente le contribuable — soit une personne morale (entreprise) soit une personne physique (travailleur indépendant).
Chaque contribuable doit être créé en tant qu’Entity avant que des opérations fiscales puissent être effectuées.

Comme SIGN FR suit l’approche API unifiée, la structure Entity est conçue de manière standardisée et divisée en deux parties principales :

Informations générales (partagées entre tous les pays) :
Cela inclut des attributs communs tels que le nom et l’adresse du contribuable.
Informations de fiscalisation (section spécifique au pays) :
Cela contient des attributs fiscaux requis par les réglementations nationales, tels que le numéro d’identification fiscale et les identifiants fiscaux.
En France, cela inclut des attributs fiscaux tels que le numéro SIREN et la date de l’exercice fiscal requis par les réglementations nationales.

PATCH : Mettre à jour l’Entity

Mettez à jour l’état de ACQUIRED à COMMISSIONED pour activer l’Entity.

Contrairement à SIGN DE, les Entities dans SIGN FR ont un attribut état.
Lorsqu’une Entity est créée, son état initial est ACQUIRED.
Avant de pouvoir être utilisée, l’Entity doit être mise à jour à l’état COMMISSIONED.

Cette étape est irréversible. À partir de ce moment, la ressource devient facturable selon le modèle de facturation applicable.

Si une Entity n’est plus utilisée, elle peut être mise à jour à l’état DECOMMISSIONED.
Cette étape est également irréversible et ne doit être effectuée que lorsqu’il est certain que le client n’utilisera plus cette Entity.

En plus des états, chaque Entity dans SIGN FR a un attribut mode qui définit son état opérationnel.

Lorsque l’Entity est dans l’état ACQUIRED ou DECOMMISSIONED, son mode est toujours INACTIVE.
Dans ce mode, la ressource ne peut pas être utilisée.
Lorsque l’Entity est mise à jour à l’état COMMISSIONED, le service SIGN FR valide automatiquement toutes les configurations requises.
En cas de succès, le mode passe à OPERATIVE.
Si un problème survient avec l’Entity ou l’une de ses ressources dépendantes, le mode change automatiquement en DEGRADED jusqu’à ce que le problème soit résolu.
Une fois le problème résolu, le service SIGN FR remettra le mode à OPERATIVE.
Le mode SUSPENDED peut être défini manuellement pour les Entities en état COMMISSIONED en utilisant l’endpoint de mise à jour.
Cela est utile pour suspendre temporairement les opérations fiscales, par exemple lors de la mise à jour des identifiants ou de la réalisation de maintenance.
Si le service SIGN FR met l’Entity en mode DEGRADED en raison d’un problème nécessitant une action de l’utilisateur, le mode doit d’abord être changé en SUSPENDED pendant l’exécution des actions nécessaires,
puis mis à jour à OPERATIVE une fois le problème résolu.

Résumé :

INACTIVE : Mode par défaut pour ACQUIRED et DECOMMISSIONED
OPERATIVE : Mode productif normal
DEGRADED : Automatiquement défini par le service SIGN FR en raison d’un problème
SUSPENDED : Mode de maintenance manuel

POST : Créer une Entity (LOCATION)

Définit l’emplacement physique de l’entreprise. Commence également en état ACQUIRED.

Pour chaque emplacement d’un contribuable, une Entity séparée de type LOCATION doit être créée.
Dans la solution SIGN FR, cela ne nécessite pas d’Asset::Unit séparé.
Tous les emplacements d’un contribuable sont représentés au sein du même Asset::Unit et sont liés à l’Entity::COMPANY ou Entity::INDIVIDUAL correspondant.
Chaque contribuable (Entity::COMPANY ou Entity::INDIVIDUAL) doit avoir au moins une Entity::LOCATION associée.

PATCH : Mettre à jour l’Entity

Mettez à jour l’état de l’Entity::LOCATION à COMMISSIONED.

Comme pour Entity::COMPANY ou Entity::INDIVIDUAL, l’Entity::LOCATION doit également être mise à jour à l’état COMMISSIONED avant de pouvoir être utilisée.
Ce n’est qu’après cette étape que l’emplacement devient actif et peut être utilisé.

POST : Créer un System

Un System de type FISCAL_DEVICE représente un système de caisse ou une caisse enregistreuse.
Il correspond au client dans SIGN DE.
Chaque System est lié à une Entity::LOCATION.

Contrairement à SIGN DE, lors de la création d’un FISCAL_DEVICE, des informations supplémentaires sur le système de conservation électronique lui-même doivent être fournies.
La plupart de ces détails sont généralement définis par le fournisseur du système de caisse.
En Allemagne, ces informations sont généralement ajoutées ultérieurement dans le cadre du processus DSFinV-K DE ou Submit DE — dans SIGN FR, cependant, cela se fait en une seule étape lors de la création du système.

PATCH : Mettre à jour le System

Mettez à jour le System de l’état ACQUIRED à COMMISSIONED pour l’activer.

La ressource System suit la même logique d’état et de mode qu’une Entity.
Une fois défini à COMMISSIONED, le système devient actif et la facturation s’applique automatiquement (lorsqu’utilisé dans l’environnement LIVE).
S’il n’est plus utilisé, il peut être défini à DECOMMISSIONED, ce qui — comme dans SIGN FR en général — est irréversible.

L’attribut mode reflète la condition opérationnelle du système (par exemple, OPERATIVE, SUSPENDED ou DEGRADED).
Ces modes se comportent de la même manière que décrit pour Entity, vous permettant de suspendre temporairement les opérations ou d’indiquer automatiquement des performances dégradées en raison de problèmes de configuration.

Configuration terminée

Avec le System mis en service avec succès, la phase de configuration initiale est terminée.
Toutes les structures organisationnelles et fiscales — de l’Asset::Unit à l’Entity et au System — sont maintenant actives et prêtes pour la production.

À partir de ce moment, les étapes suivantes décrivent les opérations fiscales quotidiennes effectuées au niveau du système de caisse.
Cela comprend la création et le traitement des enregistrements fiscaux représentant les ventes, les retours et d’autres événements — équivalents aux transactions dans SIGN DE, mais avec des données fiscales étendues telles que requises en France.

Opérations quotidiennes au niveau du système de caisse

Une fois la configuration terminée et toutes les ressources mises en service, le processus de fiscalisation dans SIGN FR se poursuit avec les opérations quotidiennes.
Ces opérations représentent les activités commerciales quotidiennes au niveau du système de caisse — comme l’émission de reçus, le traitement des retours ou la gestion des annulations.

Bien que le concept global soit similaire à SIGN DE, SIGN FR introduit un modèle de Record unifié et plus riche en données.
Chaque transaction est représentée sous forme d’un ou plusieurs Records, qui sont signés numériquement, journalisés et archivés pour garantir une conformité fiscale totale.

Les sections suivantes décrivent comment créer, traiter et gérer ces Records dans l’environnement fiscal français.

POST : Créer un Record

Dans SIGN FR, chaque transaction fiscale est représentée sous forme d’un ou plusieurs Records.
Ce modèle remplace le processus de mise à jour de transaction en deux étapes de SIGN DE (ACTIVE → FINISHED) par deux ressources indépendantes : un Record de type INTENTION et un autre Record de type TRANSACTION.

Partie A) INTENTION

Dans SIGN DE, une transaction commence par un événement Start-Transaction qui marque le début d’un processus fiscal et est ensuite mise à jour à un état terminé.
Dans SIGN FR, cette logique est remplacée par une ressource dédiée : un Record de type INTENTION.

Un Record de type INTENTION marque le début d’une opération fiscale ou effectue directement des opérations qui ne nécessitent qu’une seule étape, telles que EVENT, EXPORT ou DUPLICATE.
En France, les opérations d’intention prises en charge sont TRANSACTION, EVENT, EXPORT et DUPLICATE.

Il contient des informations contextuelles qui définissent l’intention de l’opération, notamment :

Le System (System::FISCAL_DEVICE) effectuant l’opération.
Le type d’opération, correspondant à l’une des opérations d’intention prises en charge répertoriées ci-dessus.

Partie B) TRANSACTION

Dans SIGN DE, une transaction est finalisée via une mise à jour Finish-Transaction de la ressource de transaction qui complète le processus fiscal.
Dans SIGN FR, cette étape est représentée par une ressource séparée : un Record de type TRANSACTION.

Un Record de type TRANSACTION complète l’opération fiscale et fait référence au Record de type INTENTION précédemment créé.
Il contient toutes les données fiscales et transactionnelles requises pour l’opération.
Comparé à SIGN DE, la portée et la structure des données sont plus larges et sont plus étroitement alignées avec les informations contenues dans une transaction au sein d’une clôture de caisse (Kassenabschluss) dans DSFinV-K DE.

Il comprend :

Les informations du document telles que le numéro du document, la date et les montants totaux bruts et nets.
Les détails de chaque ligne de vente (biens ou services), incluant la description, la quantité, le taux de TVA et le montant.
Les références aux reçus antérieurs lors de la création d’enregistrements CORRECTION ou CANCELLATION.
Des types d’opération supplémentaires sont également pris en charge au sein de Record::TRANSACTION, selon le processus commercial et le contexte fiscal.

Ce type de Record fournit la représentation fiscale complète de la transaction telle que requise par la réglementation française.

États et modes des Records

Chaque Record dans SIGN FR (qu’il s’agisse de INTENTION, TRANSACTION ou d’autres types) suit son propre état et mode, reflétant son cycle de vie au sein du processus de fiscalisation.

États

Accepted – Le Record a été reçu, validé et est prêt pour le traitement.
Rejected – La validation a échoué ; les détails sont disponibles dans les messages de journal.
Completed – Le Record a été traité avec succès.
Failed – Le Record n’a pas pu être traité en raison d’une défaillance d’un composant externe.

Modes

Processing – Le Record est actuellement en cours de traitement.
Finished – Le Record a été traité, avec succès ou non.

Transitions

Transition	Description
POST → Accepted	Le Record est créé et entre temporairement dans l’état `Accepted` si la validation réussit, et passe immédiatement à l’étape suivante.
POST → Rejected	Le Record échoue à la validation et passe automatiquement à `Rejected`, fournissant des journaux d’erreurs.
Accepted → Completed	Automatiquement défini lorsque le traitement se termine avec succès.
Accepted → Failed	Défini lorsque le traitement échoue en raison d’un composant externe.
Processing → Finished	Indique que le traitement a été terminé, qu’il soit réussi ou non.

Cette conception basée sur les événements permet à chaque opération fiscale d’être suivie indépendamment — sans mettre à jour la même ressource — garantissant une piste d’audit transparente et immuable pour chaque transaction.

Opérations supplémentaires (non transactionnelles)

Au-delà du flux standard INTENTION → TRANSACTION, SIGN FR prend également en charge des opérations fiscales non transactionnelles :

EVENT – Utilisé pour journaliser des événements système ou de configuration (par exemple, mode formation, opérations de test ou redémarrages du système).
DUPLICATE – Crée un duplicata d’un document fiscal existant.
EXPORT – Génère un export de données fiscales.

Ces opérations sont représentées sous forme de Records de type INTENTION uniquement et ne nécessitent pas de contrepartie TRANSACTION.
Elles étendent la traçabilité fiscale à toutes les activités pertinentes du système de caisse au-delà des transactions de vente.

Résumé

Dans les opérations quotidiennes, SIGN FR remplace le simple flux de transactions « Début → Fin » de SIGN DE par un modèle de Record multi-ressources et piloté par les événements.
Chaque opération — qu’il s’agisse d’une vente, d’une correction, d’un export ou d’un autre événement fiscal — est signée, journalisée et archivée individuellement, garantissant une traçabilité complète et la conformité avec la législation fiscale française.

Was this page helpful?