Pour les clients SIGN DE

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

Ce guide explique les principales différences avec SIGN DE et vous accompagne dans l’intégration réussie de l’API fiskaly SIGN IT. Il décrit toutes les étapes nécessaires pour vous et vos marchands.

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), ainsi que d’autres pays à venir, avec un effort supplémentaire minimal.

Contrairement à SIGN DE, SIGN IT ne nécessite pas d’API Management séparée. Tous les endpoints nécessaires pour l’authentification, la création d’organisations, la configuration et la gestion des registres fiscaux sont directement inclus dans SIGN IT — ce qui rend l’intégration plus rapide et plus simple.

Environnements : TEST et LIVE

Dans SIGN IT, il existe deux URLs 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’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 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é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 migrer vers la nouvelle version uniquement une fois que tout a été vérifié. Cela vous permet également de faire fonctionner certains clients sur une version antérieure si nécessaire, tout en embarquant de nouveaux clients directement avec la dernière version.

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

X-Idempotency-Key

Étant donné que les IDs 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 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 l’API Management 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 de terminologie : SIGN IT vs. SIGN DE

SIGN IT	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 marchand ou contribuable individuel. Chaque `Organization::UNIT` est liée à un `Taxpayer`.
`Taxpayer::COMPANY` ou `Taxpayer::INDIVIDUAL`	En Allemagne, fait partie de la `managed_organization` (DSFINVK DE) ou `taxpayer` (SUBMIT DE)	Définit le contribuable pour l’`Organization::UNIT` liée, nécessaire pour remplir les obligations fiscales.
`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 système POS / la caisse enregistreuse utilisé(e) 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. 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 d’un autre événement unique traité sur la caisse enregistreuse.
`Record::TRANSACTION`	`Finish-Transaction`	Marque la finalisation (clôture) 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 clé API 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 la Management API pour créer ou gérer des structures organisationnelles. Toutes les fonctionnalités requises font partie de SIGN IT lui-même.

POST : Create Token

Utilisez ce token pour authentifier la création de la structure organisationnelle pour l’Italie.
Il fonctionne de la même façon que le token dans SIGN DE (API Management), qui était créé à l’aide de la clé API de l’organisation (principale) puis utilisé pour créer des managed_organizations.
Dans SIGN IT, ce token est désormais nécessaire pour créer des ressources Organization::UNIT.

POST : Create Organization (UNIT)

Créez une Organization::UNIT (Organisation de type Unit) représentant votre premier client. C’est l’équivalent de la managed_organization créée via la 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 physique. Vous définirez ces détails à l’étape Taxpayer (COMPANY / INDIVIDUAL) ci-dessous.

POST : Create Subject (API Key)

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 : Create Token (scoped)

Ce token est 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 limité.
Il sera utilisé pour toutes les opérations devant être gérées au sein de cette Organization::UNIT spécifique.

POST : Create Taxpayer (COMPANY / INDIVIDUAL)

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

Un Taxpayer de type COMPANY ou INDIVIDUAL représente soit une personne morale (entreprise), soit une personne physique (entrepreneur individuel).
Chaque contribuable doit être créé avant que des opérations fiscales puissent être effectuées.

Comme SIGN IT 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) :
Comprend les attributs communs tels que le nom et l’adresse du contribuable.
Informations de fiscalisation (section spécifique au pays) :
Contient les attributs fiscaux requis par les réglementations nationales, tels que le numéro d’identification du contribuable et les identifiants fiscaux.
En Italie, cela comprend 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 : Update Taxpayer

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

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

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

Si un Taxpayer 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 que lorsque vous êtes certain que le client n’utilisera plus ce Taxpayer.

En plus des états, chaque Taxpayer dans SIGN IT possède un attribut mode qui définit son statut opérationnel.

Lorsque le Taxpayer 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 Taxpayer est mis à jour vers l’état COMMISSIONED, le service SIGN IT valide automatiquement toutes les configurations requises.
En cas de succès, le mode passe à OPERATIVE.
Si le Taxpayer rencontre des erreurs persistantes d’identifiants Fisconline, le mode passe automatiquement à DEGRADED. La récupération depuis cet état nécessite que l’utilisateur définisse d’abord le mode sur SUSPENDED, corrige les identifiants Fisconline et restaure le mode sur OPERATIVE.
Le mode SUSPENDED peut être défini manuellement pour les Taxpayers dans l’état COMMISSIONED via l’endpoint updateTaxpayer.
Cela est utile pour suspendre temporairement les opérations fiscales, par exemple lors de la mise à jour des identifiants ou de la réalisation d’une maintenance.

Résumé :

INACTIVE : Mode par défaut pour ACQUIRED et DECOMMISSIONED
OPERATIVE : Mode de production normal
DEGRADED : Défini automatiquement par le service SIGN IT en raison d’erreurs persistantes d’identifiants Fisconline.
SUSPENDED : Mode de maintenance manuel

POST : Create Location

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

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

PATCH : Update Location

Mettez à jour l’état de la Location à COMMISSIONED.

Comme pour Taxpayer::COMPANY ou Taxpayer::INDIVIDUAL, la Location doit également être mise à jour vers 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 : Create System

Un System de type FISCAL_DEVICE représente un système POS ou une caisse enregistreuse.
Il correspond au client dans SIGN DE.
Chaque System est lié à une 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 habituellement ajoutées ultérieurement dans le cadre du processus DSFinV-K DE ou Submit DE — dans SIGN IT, cela se fait cependant en une seule étape lors de la création du système.

PATCH : Update 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 mis à 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 mis à 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). Ces modes se comportent de la même manière que décrit pour Taxpayer.

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 désormais actives et prêtes pour la production.

À partir de ce moment, les étapes suivantes décrivent les opérations fiscales quotidiennes effectuées en caisse.
Cela comprend la création et le traitement des registres 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 comme requis en Italie.

Opérations quotidiennes en caisse

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 en caisse — comme 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 sous la forme d’un ou plusieurs Records, qui sont signés numériquement, journalisés et archivés pour assurer la conformité fiscale complète.

POST : Create Record

Dans SIGN IT, chaque transaction fiscale est représentée sous la 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 finalisé.
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 à la TRANSACTION.

Partie B) TRANSACTION

Dans SIGN DE, une transaction est finalisée via une mise à jour Finish-Transaction de la ressource de transaction qui clôture 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 clôture 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 requises pour l’opération.
Par rapport à 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 de document, la date et les montants bruts et nets totaux.
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 précédents lors de la création d’enregistrements CORRECTION ou CANCELLATION.

Ce type de Record fournit la représentation fiscale complète de la transaction conformément à la réglementation italienne.

États et modes des Records

Chaque Record dans SIGN IT (qu’il soit de type INTENTION, TRANSACTION ou autre) 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 à être traité.
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 journalisation.
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 journalisation.

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`, en fournissant des journaux 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 est terminé, quel que soit le succès ou l’échec.

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

Résumé

Dans les opérations quotidiennes, SIGN IT remplace le flux de transaction simple « Démarrer → Clôturer » 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 signée, journalisée et archivée individuellement, assurant une traçabilité complète et la conformité avec la législation fiscale italienne.

Was this page helpful?