Pour les Clients SIGN DE

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

Guide d’Intégration SIGN IT pour les Clients SIGN DE

Ce guide explique les principales différences avec 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êt à 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 distinctes 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 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 de passer à une version plus récente pour utiliser de nouvelles fonctionnalités.

Vous pouvez tester les modifications d’abord 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.

Avantage principal : plus de changements disruptifs dans votre version en cours.

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, 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 l’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 API Key).

Correspondance de Terminologie : SIGN IT vs. SIGN DE

SIGN IT	SIGN DE	Explication
`Asset::TENANT`	(pas d’équivalent)	Structure de niveau supérieur dans le fiskaly HUB. Représente l’intégralité du compte client. Ne peut pas être imbriquée 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, partie de `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) (p. ex. boutiques) exploité(s) par le contribuable.
`System::FISCAL_DEVICE`	`client`	Représente le POS / système de caisse utilisé pour la fiscalisation.
`Subject::API_KEY`	`API key`	Objet d’authentification de 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 la finalisation 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 point, toutes les étapes d’intégration sont gérées directement via SIGN IT. Contrairement à SIGN DE, vous n’avez plus besoin d’utiliser Management pour créer ou gérer des structures organisationnelles. Toutes les fonctionnalités requises font partie de SIGN IT lui-même.

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éé avec la API Key de l’organisation (principale) et utilisé ensuite pour créer des managed_organizations.
Dans SIGN IT, ce token est désormais 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 managed_organization créé via Management 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 spécifique d’Asset::UNIT.
Pour cette raison, 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 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 avec portée.
Il sera utilisé pour toutes les opérations qui doivent être gérées dans 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 entité légale (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 IT suit l’approche API Unifiée, la structure d’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 du contribuable 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 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 point, 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 IT possède un attribut mode qui définit son statut 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.
S’il y a un problème avec l’Entity ou l’une de ses ressources dépendantes, le mode change automatiquement à DEGRADED (pas encore implémenté) jusqu’à ce que le problème soit résolu.
Une fois le problème résolu, le service SIGN IT remettra le mode à OPERATIVE.
Le mode SUSPENDED peut être défini manuellement pour les Entities dans l’état COMMISSIONED en utilisant l’endpoint updateEntity.
Ceci est utile pour mettre temporairement en pause les opérations fiscales, par exemple lors de la mise à jour des identifiants ou d’une 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é à 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 (pas encore implémenté) : Automatiquement défini par le service SIGN IT en raison d’un problème
SUSPENDED : Mode de maintenance manuelle

POST : Créer une Entity (LOCATION)

Définit l’emplacement physique de l’activité. 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 à l’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 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.
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 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 d’enregistrement é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 IT, cependant, cela se fait en une seule étape lors de la création du système.

PATCH : Mettre à jour 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 IT 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). 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 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 commissionné 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 point, les étapes suivantes décrivent les opérations fiscales quotidiennes effectuées au POS.
Cela inclut la création et le traitement d’enregistrements fiscaux représentant des ventes, des 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 commissionnées, 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 d’enregistrement unifié et plus riche en données.
Chaque transaction est représentée par un ou plusieurs Records, qui sont signés numériquement, journalisés et archivés pour assurer une conformité fiscale complète.

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 par 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 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 à 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, notamment :

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

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 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 fait référence au Record de type INTENTION créé précédemment.
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 dans une clôture de caisse (Kassenabschluss) dans DSFinV-K DE.

Il comprend :

Des informations sur le document telles que le numéro de document, la date et les montants bruts et nets totaux.
Des détails pour chaque ligne de vente (biens ou services), notamment la description, la quantité, le taux de TVA et le montant.
Des références à des reçus antérieurs lors de la création d’enregistrements CORRECTION ou CANCELLATION.

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

États et Modes des Enregistrements

Chaque Record dans SIGN IT (qu’il soit 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 – L’enregistrement a été reçu, validé et est prêt pour le traitement.
Rejected – L’enregistrement a été reçu mais n’a pas passé nos vérifications de validation internes. Les détails sont disponibles dans les messages de journal.
Completed – L’enregistrement a été traité avec succès.
Failed – L’enregistrement n’a pas pu être traité en raison d’un échec de transmission externe. Les détails sont disponibles dans les messages de journal.

Modes

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

Transitions

Transition	Description
POST → Accepted	L’enregistrement est créé et entre temporairement dans l’état `Accepted` si la validation réussit, passant immédiatement à l’étape suivante.
POST → Rejected	L’enregistrement échoue à la validation interne 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 est terminé, 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 transaction « Début → Fin » de SIGN DE par un modèle d’enregistrement 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 signée, journalisée et archivée individuellement, garantissant une traçabilité complète et la conformité avec la loi fiscale italienne.

Was this page helpful?