Pour les clients SIGN DE

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

Ce guide explique les principales différences 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’organisations, la configuration et la gestion des enregistrements fiscaux sont inclus directement dans SIGN FR — ce qui rend l’intégration plus rapide et plus simple.

Environnements : TEST et LIVE

Dans SIGN FR, il existe deux URL de base distinctes pour les différents environnements :

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

Cela diffère de SIGN DE, où il n’existe qu’une seule URL de base utilisée pour les deux environnements.
Dans SIGN DE, c’est la clé API elle-même qui 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 identique.

Dans SIGN FR, l’environnement est sélectionné via l’URL de base.
Vous devez appeler chaque endpoint avec l’URL de base correcte (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 API unifiées, 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 souhaitez passer à une version plus récente pour utiliser de nouvelles fonctionnalités.

Vous pouvez d’abord tester les modifications 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 de nouveaux clients directement avec la dernière version.

Principal avantage : plus de changements majeurs dans votre version en cours d’exécution.

X-Idempotency-Key

Puisque les ID de ressources n’ont plus besoin d’être définis par vous mais sont générés par l’API, le 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.

Le X-Idempotency-Key est requis 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 le périmètre (par exemple, à quelle Organization::Unit appartient une clé API).

Correspondance des termes : SIGN FR vs. SIGN DE

SIGN FR	SIGN DE	Explication
`Organization::ACCOUNT`	(pas d’équivalent)	Structure de niveau supérieur dans le fiskaly HUB. Représente l’ensemble du compte client.
`Organization::GROUP`	`organization` (avec `billing_options`)	Représente l’organisation principale, sous laquelle les contribuables sont imbriqués
`Organization::UNIT`	`managed_organization`	Représente un commerçant ou contribuable individuel. Chaque `Organization::UNIT` est liée à un `Taxpayer`.
`Taxpayer::COMPANY` or `Taxpayer::INDIVIDUAL`	En Allemagne, fait partie de la `managed_organization` (DSFINVK DE) ou `taxpayer` (SUBMIT DE)	Définit le contribuable pour l’`Organization::UNIT` associée, requis pour remplir les obligations fiscales.
`Location`	Comparable : `establishment` (SUBMIT DE)	Représente le(s) lieu(x) physique(s) (par ex. des magasins) exploité(s) par le contribuable.
`System::FISCAL_DEVICE`	`client`	Représente le POS / 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 des événements spéciaux, il peut ne se composer que d’un `Record::INTENTION`. Pour les transactions, deux appels sont toujours requis : un `Record::INTENTION` et un `Record::TRANSACTION`.
`Record::INTENTION`	`Start-Transaction`	Marque le début d’un processus d’achat, ou un autre événement unique 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 distincte 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 point, toutes les étapes d’intégration sont gérées directement via SIGN FR. Contrairement à SIGN DE, vous n’avez plus besoin d’utiliser l’Management API pour créer ou gérer des structures organisationnelles. Toutes les fonctionnalités requises font 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éé à l’aide de la clé API de l’organisation (principale) et utilisé ensuite pour créer des managed_organizations.
Dans SIGN FR, ce token est désormais requis pour créer des ressources Organization::UNIT.

POST : Créer une Organisation (UNIT)

Créez une Organization::UNIT (Organisation 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’Organization::UNIT est requis.
Contrairement à SIGN DE, les informations sur le contribuable appartiennent à la ressource Taxpayer, qui peut être de type COMPANY ou INDIVIDUAL, selon que le contribuable est une personne morale ou une personne physique. Vous définirez ces détails à l’étape Contribuable (COMPANY / INDIVIDUAL) ci-dessous.

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

Chacun de vos clients a besoin de sa propre clé API pour créer des ressources dans le périmètre de son Organization::UNIT spécifique.
Pour cette raison, un Subject::API_KEY (Subject de type Clé API) doit être créé.

Associez votre clé API à l’Organization::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’Organization::UNIT à laquelle appartient la clé API.

POST : Créer un Token (délimité)

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

Avec la clé API précédemment créée pour l’Organization::UNIT, vous devez créer ce token délimité.
Il sera utilisé pour toutes les opérations devant être traitées au sein de cette Organization::UNIT spécifique.

POST : Créer un Contribuable (COMPANY / INDIVIDUAL)

Définit la représentation du contribuable pour l’Organization::UNIT correspondante.

Un Taxpayer de type COMPANY ou INDIVIDUAL représente le contribuable — soit une personne morale (société) soit une personne physique (auto-entrepreneur).
Chaque contribuable doit être créé avant que des opérations fiscales puissent être effectuées.

Comme SIGN FR suit l’approche API unifiée, la structure Taxpayer 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 les attributs fiscaux requis par les réglementations nationales, tels que le numéro d’identification du contribuable et les identifiants fiscaux.
En France, cela inclut des attributs fiscaux tels que le numéro SIREN et la date d’exercice fiscal qui sont requis par les réglementations nationales.

PATCH : Mettre à jour le Contribuable

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

Contrairement à SIGN DE, les Contribuables dans SIGN FR ont un attribut state.
Lorsqu’un Contribuable est créé, son état initial est ACQUIRED.
Avant de pouvoir être utilisé, le Contribuable doit être mis à jour vers l’état COMMISSIONED.

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

Si un Contribuable n’est plus utilisé, il peut être mis à jour vers l’état DECOMMISSIONED.
Cette étape est également irréversible et ne doit être effectuée qu’une fois qu’il est certain que le client n’utilisera plus ce Contribuable.

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

Lorsque le Contribuable est dans l’état ACQUIRED ou DECOMMISSIONED, son mode est toujours INACTIVE.
Dans ce mode, la ressource ne peut pas être utilisée.
Lorsque le Contribuable est mis à jour vers l’état COMMISSIONED, le service SIGN FR valide automatiquement toutes les configurations requises.
En cas de succès, le mode passe à OPERATIVE.
S’il y a un problème avec le Contribuable 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 Contribuables dans l’é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 maintenance.
Si le service SIGN FR met le Contribuable 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 remis à OPERATIVE une fois le problème résolu.

Résumé :

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

POST : Créer un Emplacement

Définit l’emplacement commercial physique. Commence également dans l’état ACQUIRED.

Pour chaque emplacement d’un contribuable, un Location séparé doit être créé.
Dans la solution SIGN FR, cela ne nécessite pas d’Organization::UNIT séparée.
Tous les emplacements d’un contribuable sont représentés dans la même Organization::UNIT et sont liés au Taxpayer::COMPANY ou Taxpayer::INDIVIDUAL correspondant.
Chaque contribuable doit avoir au moins un Location associé.

PATCH : Mettre à jour l’Emplacement

Mettez à jour l’état du Location à COMMISSIONED.

Comme pour Taxpayer::COMPANY ou Taxpayer::INDIVIDUAL, le Location doit également être mis à jour vers l’état COMMISSIONED avant de pouvoir être utilisé.
Ce n’est qu’après cette étape que l’emplacement devient actif et utilisable.

POST : Créer un System

Un System de type FISCAL_DEVICE représente un POS ou une caisse enregistreuse.
Il correspond au client dans SIGN DE.
Chaque System est lié à un 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 de POS.
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 est 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’un Taxpayer.
Une fois défini sur COMMISSIONED, le système devient actif et la facturation s’applique automatiquement (lors de l’utilisation dans l’environnement LIVE).
S’il n’est plus utilisé, il peut être défini sur 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 Taxpayer, vous permettant de suspendre temporairement les opérations ou d’indiquer automatiquement une performance dégradée 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’Organization::UNIT au Taxpayer 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 POS.
Cela inclut la création et le traitement des enregistrements fiscaux représentant les ventes, les retours et autres événements — équivalents aux transactions dans SIGN DE, mais avec des données fiscales étendues requises en France.

Opérations quotidiennes au POS

Une fois la configuration terminée et toutes les ressources mises en service, le processus de fiscalisation dans SIGN FR continue avec les opérations quotidiennes.
Ces opérations représentent les activités commerciales quotidiennes au POS — 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 d’enregistrement 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 complète.

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 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 mis à jour vers 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 listé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 termine le processus fiscal.
Dans SIGN FR, cette étape est représentée par une ressource distincte : 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 inclut :

Les informations sur le document telles que le numéro de document, la date et les montants bruts et nets totaux.
Les détails de chaque ligne de vente (biens ou services), y compris 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 de records de type CORRECTION ou CANCELLATION.
Des types d’opération supplémentaires sont également pris en charge dans Record::TRANSACTION, selon le processus métier 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 soit de type INTENTION, TRANSACTION ou d’autres types) suit son propre état et mode, reflétant son cycle de vie dans le 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 log.
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 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, puis passe immédiatement à l’étape suivante.
POST → Rejected	Le Record échoue à la validation et passe automatiquement à l’état `Rejected`, fournissant des logs d’erreur.
Accepted → Completed	Défini automatiquement 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 est terminé, quel qu’en soit le résultat (succès ou échec).

Cette conception basée sur les événements permet à chaque opération fiscale d’être suivie indépendamment — sans mise à jour de 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 les opérations fiscales non transactionnelles :

EVENT — Utilisé pour enregistrer 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 comme des Records de type INTENTION uniquement et ne nécessitent pas de contrepartie TRANSACTION.
Elles étendent la traçabilité fiscale à toutes les activités POS pertinentes au-delà des transactions de vente.

Résumé

Dans les opérations quotidiennes, SIGN FR remplace le flux de transaction simple “Début → Fin” de SIGN DE par un modèle d’enregistrement piloté par événements et multi-ressources.
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 individuellement, journalisée et archivée, garantissant une traçabilité complète et la conformité avec la loi fiscale française.

Was this page helpful?