L'API Unifiée

L’API Unifiée de fiskaly est une architecture d’intégration unique qui couvre plusieurs pays. Intégrez-la une fois pour la France ou l’Italie, et ajouter le pays suivant signifie changer le schéma de payload — pas réécrire votre intégration.

Cette page documente comment fonctionne l’API Unifiée, à quoi ressemble son modèle de ressources et comment elle diffère des API Spécialisées (SIGN DE, SIGN AT, SIGN ES).

Deux architectures API

fiskaly propose deux architectures API. Les deux sont entièrement supportées et maintenues activement :

	API Unifiée	API Spécialisées
Pays	France (SIGN FR), Italie (SIGN IT), Suède (à venir)	Allemagne (SIGN DE), Autriche (SIGN AT), Espagne (SIGN ES)
URL de base	test.api.fiskaly.com / live.api.fiskaly.com	Spécifiques au produit (ex. kassensichv.fiskaly.com)
Gestion des orgs	Intégrée dans l’API du produit	Management API séparée (management.fiskaly.com)
ID des ressources	Générés par le serveur (utiliser X-Idempotency-Key)	UUID générés par le client
Contrôle de version	Header X-Api-Version (basé sur la date, pas de breaking change)	Pas de header de version (breaking changes possibles)
Portée des ressources	Header X-Scope-Identifier	Paramètres de chemin
Terminologie	Organization, Taxpayer, Location, System, Record	TSS, client, transaction (varie par produit)
Ajouter un pays	Changer le schéma payload dans le même modèle de ressources	Intégrer une API séparée avec des endpoints différents

📘Aucune architecture n'est legacy

Les API Spécialisées sont conçues sur mesure pour les réglementations spécifiques de leur pays. SIGN DE est le produit le plus mature de fiskaly avec plus de 10 000 intégrations et une certification BSI valable jusqu’en 2033. L’API Unifiée est l’architecture que fiskaly a construite pour une expansion multi-pays efficace.

Quelle architecture devriez-vous utiliser ?

Scénario	Recommandation
Vous avez besoin uniquement de l’Allemagne	SIGN DE (API Spécialisée)
Vous avez besoin uniquement de l’Autriche	SIGN AT (API Spécialisée)
Vous avez besoin uniquement de l’Espagne	SIGN ES (API Spécialisée)
Vous avez besoin uniquement de la France ou de l’Italie	API Unifiée
Vous avez besoin de la France + Italie (ou + Suède)	API Unifiée — intégrez une fois, ajoutez des pays via le schéma payload
Vous avez besoin de l’Allemagne + France	Les deux — SIGN DE (Spécialisée) + SIGN FR (Unifiée). Même schéma auth, modèles de ressources différents.
Vous démarrez de zéro et planifiez 3+ pays	Commencez par l’API Unifiée pour FR/IT, ajoutez les API Spécialisées pour DE/AT/ES selon les besoins

URL de base de l’API Unifiée

L’API Unifiée utilise des URL de base séparées pour chaque environnement :

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

C’est différent des API Spécialisées (ex. SIGN DE), où une seule URL de base est utilisée et la clé API détermine l’environnement.

Headers de l’API Unifiée

Chaque requête à l’API Unifiée inclut ces headers :

X-Api-Version

Obligatoire pour chaque requête. La valeur est la date de publication de la version API que vous ciblez (ex. 2026-02-03).

X-Api-Version: 2026-02-03

Cela vous donne un contrôle total sur le moment où adopter une nouvelle version. Vous pouvez :

• Tester une nouvelle version en TEST avant de migrer en LIVE
• Faire tourner différents clients sur différentes versions simultanément
• Garantir aucun breaking change dans une version bloquée

X-Idempotency-Key

Obligatoire pour toutes les requêtes POST et PATCH. Comme les ID de ressources sont générés par le serveur (pas fournis par le client comme dans SIGN DE), ce header garantit que les requêtes répétées ne créent pas de ressources en double.

X-Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

Utilisez un UUIDv4 ou UUIDv3 frais pour chaque opération distincte. Utilisez une nouvelle clé lors d’une nouvelle tentative après une requête échouée.

X-Scope-Identifier

Utilisé pour établir des relations entre ressources. Remplace les paramètres de chemin utilisés dans la Management API et les API Spécialisées.

X-Scope-Identifier: organization-unit-id

Par exemple, lors de la création d’une clé API pour une Organization::UNIT spécifique, le header X-Scope-Identifier contient l’ID de l’Unité au lieu de l’encoder dans le chemin URL.

Modèle de ressources

L’API Unifiée utilise une hiérarchie de ressources standardisée dans tous les pays :

Organization::ACCOUNT       ← Votre entreprise (niveau supérieur, gérée dans le HUB)
  │
  └── Organization::GROUP   ← Cluster logique (région, enseigne, franchise)
        │
        └── Organization::UNIT   ← Commerçant individuel / contribuable
              │
              ├── Subject::API_KEY   ← Identifiants API pour cette unité
              │
              ├── Taxpayer (COMPANY ou INDIVIDUAL)
              │     │
              │     ├── Informations générales (nom, adresse — partagées entre pays)
              │     │
              │     └── Informations de fiscalisation (spécifiques au pays : SIREN pour FR,
              │         Codice Fiscale pour IT, etc.)
              │
              ├── Location   ← Emplacement physique de l'entreprise (boutique, magasin)
              │
              └── System::FISCAL_DEVICE   ← Terminal POS / caisse enregistreuse

États des ressources

Chaque ressource principale (Taxpayer, Location, System) suit la même machine à états :

ACQUIRED ──→ COMMISSIONED ──→ DECOMMISSIONED
(créée)        (active)          (retirée)

• ACQUIRED — la ressource est créée mais pas encore active. Mode : INACTIVE.
• COMMISSIONED — la ressource est active et prête pour la production. Mode : OPERATIVE. Cette transition est irréversible et déclenche la facturation.
• DECOMMISSIONED — la ressource est définitivement retirée. Mode : INACTIVE. Également irréversible.

Modes opérationnels à l’intérieur de l’état COMMISSIONED :

Mode	Signification	Défini par
OPERATIVE	Opération normale	Automatique (à la commission ou après résolution du problème)
DEGRADED	Problème détecté	Automatique (par le service)
SUSPENDED	Pause de maintenance	Manuel (par vous, via API)

Records (le modèle de transaction)

Dans l’API Unifiée, les transactions sont appelées Records et utilisent un modèle en deux étapes :

1. Record::INTENTION — marque le début d’une opération fiscale (équivalent à Start-Transaction dans SIGN DE)
2. Record::TRANSACTION — complète l’opération fiscale avec le payload complet (équivalent à Finish-Transaction dans SIGN DE)

Types d’opérations supplémentaires supportés uniquement via Record::INTENTION (pas de contrepartie TRANSACTION nécessaire) :

• EVENT — événements système (mode formation, opérations de test, redémarrages)
• DUPLICATE — duplicata d’un document fiscal existant
• EXPORT — génération d’export de données fiscales

📘Toutes les opérations ne sont pas disponibles dans chaque pays

La France supporte les intentions TRANSACTION, EVENT, DUPLICATE et EXPORT. L’Italie ne supporte actuellement que TRANSACTION. Consultez la documentation spécifique au pays pour la liste complète.

Correspondance des terminologies (API Unifiée vs SIGN DE)

Si vous venez d’une intégration SIGN DE, ce tableau met en correspondance les concepts :

API Unifiée	SIGN DE	Explication
Organization::ACCOUNT	(pas d’équivalent)	Structure de niveau supérieur dans le HUB
Organization::GROUP	organization	Organisation principale sous laquelle les contribuables sont imbriqués
Organization::UNIT	managed_organization	Commerçant individuel. Lié à un Taxpayer.
Taxpayer (COMPANY/INDIVIDUAL)	Partie de managed_organization ou taxpayer (SUBMIT DE)	L’entité fiscale
Location	establishment (SUBMIT DE)	Emplacement physique de l’entreprise
System::FISCAL_DEVICE	client	Terminal POS / caisse enregistreuse
Subject::API_KEY	API key	Identifiants d’authentification
Record	transaction	Une opération fiscale
Record::INTENTION	Start-Transaction	Marque le début d’un achat
Record::TRANSACTION	Finish-Transaction	Complète l’achat avec les données fiscales complètes

Ce qui change par pays

La proposition de valeur de l’API Unifiée est que la majeure partie de l’intégration est partagée. Voici ce qui reste identique et ce qui diffère :

Partagé dans tous les pays de l’API Unifiée	Spécifique au pays
Authentification (POST /tokens)	Section fiscalization du Taxpayer (ex. SIREN pour FR ; Codice Fiscale, TVA et identifiants pour IT)
Hiérarchie organisationnelle (ACCOUNT > GROUP > UNIT)	Schéma payload du Record (structure du reçu, gestion de la TVA, types de document)
Headers (X-Api-Version, X-Idempotency-Key, X-Scope-Identifier)	Opérations d’intention supportées (FR a EVENT/DUPLICATE/EXPORT ; IT a uniquement TRANSACTION)
Cycle de vie des ressources (ACQUIRED > COMMISSIONED > DECOMMISSIONED)	Exigences réglementaires (certification NF525 pour FR, loterie des reçus pour IT)
Gestion des états et modes (OPERATIVE, DEGRADED, SUSPENDED)	Gestion des pertes de connexion (protocoles différents par pays)
URL de base (test.api.fiskaly.com / live.api.fiskaly.com)	—

Effort typique pour ajouter un deuxième pays de l’API Unifiée : ~1 semaine pour une équipe déjà intégrée avec le premier pays. Vous adaptez la section fiscalisation du Taxpayer et le schéma payload du Record — tout le reste est réutilisable.

Procédure d’intégration

Voici le flux de configuration complet pour un pays de l’API Unifiée (en utilisant SIGN FR comme exemple). Le flux est identique pour SIGN IT.

1. Créer le Token

   POST /tokens avec votre clé et votre secret API (identique à tous les produits fiskaly). Ce token est utilisé pour créer la structure organisationnelle.

2. Créer Organization::UNIT

   POST /organizations avec X-Idempotency-Key. Seul le nom est requis à ce stade. Représente votre client (commerçant).

3. Créer Subject::API_KEY

   POST /subjects avec X-Scope-Identifier défini sur l’ID Organization::UNIT. Chaque client a besoin de sa propre clé API.

4. Créer un Token avec portée

   POST /tokens en utilisant la clé API du client. Ce token avec portée est utilisé pour toutes les opérations spécifiques au contribuable.

5. Créer le Taxpayer

   POST /taxpayers avec les informations générales (nom, adresse) et la section fiscalization spécifique au pays (ex. numéro SIREN pour la France, Codice Fiscale, TVA et identifiants pour IT).

6. Commissionner le Taxpayer

   PATCH /taxpayers/{id} — mettre à jour l’état de ACQUIRED à COMMISSIONED. C’est irréversible et active la facturation.

7. Créer et commissionner la Location

   POST /locations puis PATCH /locations/{id} pour commissionner. Représente un emplacement physique de l’entreprise.

8. Créer et commissionner le System

   POST /systems puis PATCH /systems/{id} pour commissionner. Représente un terminal POS. Dans SIGN FR, vous fournissez également les détails du système de conservation électronique à cette étape.

9. Créer Record::INTENTION

   POST /records avec le type d’opération (ex. TRANSACTION) et l’ID du System. Ceci démarre l’opération fiscale.

10. Créer Record::TRANSACTION

    POST /records référençant le record INTENTION. Contient le payload fiscal complet (articles, montants, TVA, moyens de paiement). La réponse inclut la signature cryptographique.

Pas de Management API séparée

Contrairement aux API Spécialisées (SIGN DE, SIGN AT, SIGN ES), l’API Unifiée ne nécessite pas la Management API (management.fiskaly.com). Toute la gestion des organisations, la création de clés API et la configuration sont gérées directement dans l’API du produit.

Cela signifie moins de surfaces API à intégrer, moins d’identifiants à gérer et une architecture globale plus simple.

Pays sur l’API Unifiée

France (SIGN FR)

Certification NF525, clôtures de période, replay hors ligne, archives

Italie (SIGN IT)

API cloud pour la transmission des reçus fiscaux à l'autorité fiscale italienne (AdE).

Suède (SIGN SE)

InfraSec TCS — en cours d'intégration dans l'API Unifiée

Pays sur les API Spécialisées

Allemagne (SIGN DE)

Cloud-TSS certifié BSI, KassenSichV, DSFinV-K, SUBMIT DE

Autriche (SIGN AT)

Conformité RKSV, signature basée sur SCU, enregistrement FinanzOnline

Espagne (SIGN ES)

TicketBAI + Verifactu + SII depuis une seule API, signature de factures XML

Prochaines étapes

SIGN FR pour clients SIGN DE

Guide de migration détaillé avec appels API étape par étape

SIGN IT pour clients SIGN DE

Guide de migration détaillé avec appels API étape par étape

Planification de l'intégration

Estimations d'effort, calendriers et listes de contrôle de conformité