Concepts fondamentaux

Avant d’intégrer un produit fiskaly, il est utile de comprendre les blocs de construction de la plateforme. Ces concepts s’appliquent à tous les pays et à tous les produits.

Organisations

fiskaly utilise un modèle organisationnel hiérarchique pour représenter la structure de votre entreprise :

🏢

Account

Votre entité de plus haut niveau. Créée lors de votre inscription sur le HUB. Représente le fournisseur de caisse ou le détaillant.

📂

Group

Un niveau intermédiaire permettant de regrouper plusieurs unités. Utile pour organiser par région ou par enseigne.

🏪

Unit

Représente un seul commerçant ou une entité juridique. Chaque unité possède ses propres données contribuable et ressources fiscales.

Dans les API plus récentes (SIGN PT, SIGN IT, SIGN FR, E-Invoice), celles-ci sont appelées types d’organisation GROUP et UNIT. Dans SIGN DE, les organisations gérées remplissent le même rôle.

Environnements

Chaque compte fiskaly dispose de deux environnements isolés :

Environnement	Objectif	Données
TEST	Développement et tests d’intégration	Simulées — aucune connexion avec les autorités fiscales
LIVE	Opérations en production	Réelles — les transactions sont signalées aux autorités fiscales

⚠️LIVE est permanent

Les enregistrements créés dans l’environnement LIVE ont valeur légale et sont transmis aux autorités fiscales. Développez et testez toujours d’abord dans l’environnement TEST.

Les clés API générées en TEST créent des ressources TEST ; les clés générées en LIVE créent des ressources LIVE. Les deux environnements sont complètement séparés — il n’y a pas de partage de données entre eux.

Authentification

Toutes les API fiskaly utilisent l’authentification basée sur JWT :

POST /auth  (ou POST /tokens)
  { "api_key": "...", "api_secret": "..." }
    → { "access_token": "...", "refresh_token": "..." }

Token	Durée	Utilisation
access_token	24 heures	Inclure comme Authorization: Bearer <token> dans toutes les requêtes API
refresh_token	48 heures	Utiliser pour obtenir un nouveau token d’accès sans se ré-authentifier

💡Mettez vos tokens en cache

Ne vous ré-authentifiez pas à chaque requête. Mettez le token d’accès en cache et ne le rafraîchissez que lorsque vous recevez une réponse 401. Se ré-authentifier à chaque appel ajoute une latence inutile à votre processus de paiement.

Authentification avec portée (SIGN PT, SIGN IT, SIGN FR, E-Invoice)

Les API plus récentes utilisent des headers supplémentaires pour limiter les requêtes à une organisation spécifique :

Header	Objectif
Authorization: Bearer <token>	Authentification
X-Api-Version: 2026-02-03	Sélection de la version de l’API
X-Scope-Identifier: <org_id>	Limite les requêtes à une unité organisationnelle spécifique
X-Idempotency-Key: <uuid>	Garantit l’idempotence des opérations d’écriture

Modèle de ressources

Bien que les ressources exactes varient selon les pays, la plupart des produits fiskaly suivent un schéma commun :

Account / Group
  └── Unit (Organisation)
        └── Taxpayer (Contribuable)
              └── Location (Branch / Head Office)
                    └── System (Dispositif fiscal / Caisse)
                          └── Record / Transaction

Cycle de vie des ressources

La plupart des ressources suivent une machine à états :

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

• ACQUIRED : la ressource est créée mais pas encore active
• COMMISSIONED : la ressource est active et peut traiter des transactions
• DECOMMISSIONED : la ressource est retirée et n’accepte plus de nouvelles opérations

Dans SIGN DE, les états équivalents sont CREATED → INITIALIZED → DISABLED.

Ressources spécifiques par pays

Concept	Allemagne (SIGN DE)	Autriche (SIGN AT)	Espagne (SIGN ES)	Italie (SIGN IT)	Portugal (SIGN PT)	France (SIGN FR)
Unité de signature	TSS	SCU	Signer	System	System	System
Terminal POS	Client	Cash Register	Client	System	System	System
Enregistrement fiscal	Transaction	Receipt	Invoice	Record	Record	Record
Autorité fiscale	BSI / BZSt	FinanzOnline	AEAT / DFAs Basques	AdE (Agenzia delle Entrate)	AT (Autoridade Tributária e Aduaneira)	DGFiP

URL de base

Chaque produit possède son propre endpoint API. Consultez la référence URL de base et environnements pour une liste complète.

Produit	Environnement de test	Environnement live
SIGN DE	kassensichv-middleware.fiskaly.com/api/v2	kassensichv.fiskaly.com/api/v2
SIGN AT	rksv.fiskaly.com/api/v1	rksv.fiskaly.com/api/v1
SIGN ES	test.es.sign.fiskaly.com/api/v1	live.es.sign.fiskaly.com/api/v1
SIGN IT	test.api.fiskaly.com	live.api.fiskaly.com
SIGN FR	test.api.fiskaly.com	live.api.fiskaly.com

Et maintenant ?

Démarrage rapide

Effectuez votre premier appel API en moins de 5 minutes

Référence Authentification

Guide d'authentification détaillé avec les flux de rafraîchissement de token

Codes d'erreur

Comprendre et dépanner les erreurs API