Pour les clients SIGN DE

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

Guide d’intégration SIGN IT 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 IT. Il décrit toutes les étapes nécessaires pour vous et vos commerçants.

Approche API unifiée

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

Contrairement à SIGN DE, SIGN IT 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 SIGN IT — rendant l’intégration plus rapide et plus simple.

Environnements : TEST et LIVE

Dans SIGN IT, 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 utilisée pour les deux environnements.
Dans SIGN DE, la API Key elle-même détermine si des ressources TEST ou LIVE sont créées.
Un token créé avec une API Key LIVE crée des ressources LIVE.
Un token créé avec une API Key TEST crée des ressources TEST — même si l’URL reste la même.

Dans SIGN IT, 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 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ù passer à une version plus récente pour utiliser de nouvelles fonctionnalités.

Vous pouvez tester les modifications d’abord dans l’environnement TEST et migrer vers la nouvelle version uniquement 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 aucun changement cassant dans votre version en cours d’exécution.

X-Idempotency-Key

Étant donné que les ID de ressources n’ont plus besoin d’être définis par vous mais sont générés par l’API, la 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 la même X-Idempotency-Key produisent le même résultat et empêchent les créations en double.

La 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 le scope (par exemple, à quel Asset::UNIT appartient une API Key).

Correspondance terminologique : SIGN IT vs. SIGN DE

SIGN IT	SIGN DE	Explication
`Asset::TENANT`	(pas d’équivalent)	Structure de niveau supérieur dans fiskaly HUB. Représente l’ensemble du compte client. Ne peut pas être imbriqué dans d’autres assets.
`Asset::GROUP` (optionnel)	`organisation` (avec `billing_options`)	Couche intermédiaire optionnelle utilisée pour organiser plusieurs contribuables en clusters logiques.
`Asset::UNIT`	`managed_organization`	Représente un commerçant ou contribuable individuel. Chaque `Asset::UNIT` est lié à un contribuable via une `Entity`.
`Entity::COMPANY` ou `Entity::INDIVIDUAL`	En Allemagne, fait 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 le(s) emplacement(s) physique(s) (par ex. boutiques) 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 API Key, utilisé pour autoriser l’accès.
`Record`	`transaction`	Représente une opération effectuée sur la caisse enregistreuse. 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 autre événement unique traité sur la caisse enregistreuse.
`Record::TRANSACTION`	`Finish-Transaction`	Marque l’achèvement (fin) d’un processus d’achat.

SIGN IT étape par étape

Première organisation

Pour commencer, vous devez créer une organisation séparée spécifiquement pour l’Italie dans le fiskaly HUB et une API Key dédiée pour l’intégration italienne.

À partir de ce moment, toutes les étapes d’intégration sont gérées directement via SIGN IT. Contrairement à SIGN DE, vous n’avez plus besoin d’utiliser le Management pour créer ou gérer des structures organisationnelles. Toutes les fonctionnalités requises font partie directement de SIGN IT.

POST : Créer un Token

Utilisez ce token pour authentifier la création de la structure organisationnelle pour l’Italie.
Il fonctionne de la même manière que le token dans SIGN DE (Management API), qui était créé à l’aide de la API Key de l’organisation (principale) et ensuite utilisé pour créer des managed_organizations.
Dans SIGN IT, 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. C’est l’équivalent de la managed_organization créée via le Management utilisé 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 API Key pour créer des ressources dans le scope spécifique de son Asset::UNIT.
Pour cette raison, un Subject::API_KEY (Subject de type Clé API) doit être créé.

Liez votre API Key à l’Asset::UNIT en utilisant l’en-tête X-Scope-Identifier.

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

POST : Créer un Token (scopé)

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

Avec la API Key précédemment créée pour l’Asset::UNIT, vous devez créer ce token scopé.
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 correspondante.

Une Entity de type COMPANY ou INDIVIDUAL représente le contribuable — respectivement une personne morale (entreprise) ou 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 IT 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 les attributs fiscaux requis par les réglementations nationales, tels que le numéro d’identification fiscale et les identifiants fiscaux.
En Italie, cela inclut des attributs fiscaux tels que le numéro fiscal (Codice Fiscale) et le numéro de TVA (Partita IVA) 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 IT ont un attribut state.
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 qu’une fois certain que le client n’utilisera plus cette Entity.

En plus des états, chaque Entity dans SIGN IT 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 IT valide automatiquement toutes les configurations requises.
En cas de succès, le mode passe à OPERATIVE.
En cas de problème avec l’Entity ou l’une de ses ressources dépendantes, le mode change automatiquement à DEGRADED (pas encore implémenté) jusqu’à la résolution du problème.
Une fois le problème résolu, le service SIGN IT ramènera le mode à OPERATIVE.
Le mode SUSPENDED peut être défini manuellement pour les Entities dans l’état COMMISSIONED en utilisant l’endpoint updateEntity.
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 IT met l’Entity en mode DEGRADED (pas encore implémenté) 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 (pas encore implémenté) : Défini automatiquement par le service SIGN IT 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 dans l’état ACQUIRED.

Pour chaque emplacement d’un contribuable, une Entity séparée de type LOCATION doit être créée.
Dans la solution SIGN IT, cela ne nécessite pas un 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 à la Entity::COMPANY ou Entity::INDIVIDUAL correspondante.
Chaque contribuable (Entity::COMPANY ou Entity::INDIVIDUAL) doit avoir au moins une Entity::LOCATION associée.

PATCH : Mettre à jour l’Entity (LOCATION)

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.
C’est seulement 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 POS 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 tenue électronique lui-même doivent être fournies.
La plupart de ces détails sont généralement définis par le fournisseur POS.
En Allemagne, ces informations sont généralement ajoutées plus tard dans le cadre du processus DSFinV-K DE ou Submit DE — dans SIGN IT, 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 sur 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 sur DECOMMISSIONED, ce qui — comme dans SIGN IT en général — est irréversible.

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

Configuration terminée

Avec le System correctement mis en service, 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 POS.
Cela inclut 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 Italie.

Opérations quotidiennes au POS

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

Bien que le concept général soit similaire à SIGN DE, SIGN IT introduit un modèle de Record unifié et plus riche en données.
Chaque transaction est représentée comme un ou plusieurs Records, 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 italien.

POST : Créer un Record

Dans SIGN IT, chaque transaction fiscale est représentée comme 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 mis à jour vers un état terminé.
Dans SIGN IT, 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.
En Italie, l’opération d’intention prise en charge est TRANSACTION.

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

Le System (System::FISCAL_DEVICE) effectuant l’opération.
Le type d’opération, correspondant à la TRANSACTION.

Partie B) TRANSACTION

Dans SIGN DE, une transaction est finalisée via une mise à jour Finish-Transaction de la ressource transaction qui complète le processus fiscal.
Dans SIGN IT, 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 référence le Record de type INTENTION précédemment créé.
Il contient toutes les données fiscales et transactionnelles nécessaires à l’opération.
Par rapport à SIGN DE, la portée et la structure des données sont plus larges et 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 sur le document telles que le numéro de document, la date et les montants totaux bruts et nets.
Les détails pour 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.

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

États et modes des Records

Chaque Record dans SIGN IT (qu’il soit INTENTION, TRANSACTION ou autre type) suit son propre state 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 — Le Record a été reçu mais n’a pas passé nos contrôles de validation internes. 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 de transmission externe. Les détails sont disponibles dans les messages de log.

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 interne et passe automatiquement à `Rejected`, fournissant des logs d’erreurs.
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 a été complété, qu’il soit réussi ou non.

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

Résumé

Dans les opérations quotidiennes, SIGN IT remplace le simple flux de transactions “Démarrer → Terminer” 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 (RECEIPT), d’un retour (CORRECTION) ou d’une annulation (CANCELLATION) — est individuellement signée, journalisée et archivée, assurant une traçabilité complète et la conformité avec la loi fiscale italienne.

Was this page helpful?