Correspondance des ressources entre produits

Cette référence montre comment les concepts clés se correspondent entre les architectures API de fiskaly. Utilisez-la lors de la migration entre produits ou de l’intégration de plusieurs pays.

Tableau de correspondance des ressources

Concept	SIGN DE (Spécialisée)	API Unifiée (FR/IT)	Management API
Entité de niveau supérieur	Organisation (via HUB)	Organisation GROUP	Organisation
Unité commerciale	Organisation gérée	Organisation UNIT	Organisation gérée
Dispositif de signature	TSS (Technical Security System)	System FISCAL_DEVICE	—
Terminal POS	Client	— (implicite via System)	—
Transaction	Transaction (PUT avec état)	Record (Intention → Transaction)	—
Entité fiscale	— (via SUBMIT DE)	Taxpayer (COMPANY / INDIVIDUAL)	—
Emplacement	— (via DSFinV-K)	Location BRANCH	—
Identifiants	Clé API + Secret (HUB)	Subject API_KEY (API)	Clé API (HUB)
Endpoint auth	POST /api/v2/auth	POST /api/v1/auth/token	POST /api/v0/auth
ID des ressources	UUID généré par le client	Généré par le serveur	UUID généré par le client
Idempotence	PUT avec UUID dans l’URL	Header X-Idempotency-Key	PUT avec UUID dans l’URL

États du cycle de vie

Les ressources dans chaque architecture suivent des machines à états différentes :

SIGN DE — États du TSS

UNINITIALIZED → INITIALIZED → DISABLED

• Doit définir le PIN Admin et s’authentifier avant l’initialisation
• Ne peut pas être réactivé une fois désactivé

API Unifiée — États des ressources

ACQUIRED → COMMISSIONED → DECOMMISSIONED

S’applique à : Taxpayer, Location, System

• Les ressources sont créées en état ACQUIRED
• Doivent être mises à jour à COMMISSIONED avant l’utilisation opérationnelle
• DECOMMISSIONED est terminal

SIGN DE — États de la transaction

ACTIVE (révision 1) → FINISHED (révision 2)

API Unifiée — Flux des Records

INTENTION → TRANSACTION

• Deux appels API séparés sont requis
• La Transaction référence l’Intention par ID

Comparaison des séquences de configuration

SIGN DE (Allemagne)

1. Créer une Organisation (HUB)
2. Générer une Clé API (HUB)
3. S’authentifier (POST /auth)
4. Créer un TSS (PUT /tss/{id})
5. Initialiser le TSS (PIN Admin → Auth → Changement d’état)
6. Créer un Client (PUT /tss/{id}/client/{id})
7. Créer une Transaction (PUT /tss/{id}/tx/{id})

API Unifiée (France/Italie)

1. S’inscrire sur le HUB
2. Créer une Organisation GROUP (HUB)
3. Générer une Clé API (HUB)
4. Créer un Token (POST /auth/token)
5. Créer une Organisation UNIT
6. Créer un Subject API_KEY
7. Créer un Token (pour UNIT)
8. Créer un Taxpayer → Commissionner
9. Créer une Location → Commissionner
10. Créer un System → Commissionner
11. Créer un Record (Intention → Transaction)

📘Plus d'étapes, plus de structure

L’API Unifiée comporte plus d’étapes de configuration car elle inclut la gestion des organisations (hiérarchie GROUP/UNIT), les données du contribuable et le suivi des emplacements directement dans l’API du produit — des fonctionnalités que SIGN DE gère via des produits séparés (Management API, SUBMIT DE, DSFinV-K).

Différences clés

Aspect	API Spécialisées	API Unifiée
URL de base	Par produit (ex. kassensichv.fiskaly.com)	Partagée (test.api.fiskaly.com)
Gestion des orgs	Via Management API + HUB	Intégrée dans l’API du produit
Création de ressources	PUT avec UUID généré par le client	POST avec ID généré par le serveur
Versioning	Chemin URL (/api/v2)	Header (X-Api-Version: 2026-02-03)
Portée	Implicite (via token auth)	Explicite (header X-Scope-Identifier)
Modèle de transaction	Ressource unique avec changements d’état	Deux étapes : Intention puis Transaction

Ressources connexes

Vue d'ensemble de l'API Unifiée

Comparaison complète des deux architectures API

Configuration SIGN DE

Guide étape par étape pour la fiscalisation allemande

Configuration SIGN FR

Guide étape par étape pour la fiscalisation française