Intégration étape par étape

Ce guide vous accompagne tout au long du processus complet de configuration de votre système avec fiskaly SIGN DE, en utilisant une combinaison du fiskaly HUB, de la Management API et de l’API SIGN DE. À la fin, vous disposerez d’une organisation gérée entièrement provisionnée avec un TSS et un client prêts à signer des transactions.

Avant de plonger dans la configuration, voici ce que vous allez configurer :

🏢

Compte et Groupe

Votre Compte est l'entité de niveau supérieur créée lors de votre inscription sur le HUB — il représente votre entreprise en tant que fournisseur POS ou revendeur. Un Groupe est une couche intermédiaire au sein du Compte utilisée pour regrouper les organisations gérées de manière logique (p. ex. un Groupe par pays).

🔑

Clé API et Token

Identifiants générés dans le HUB et jetons obtenus depuis la Management API et SIGN DE, utilisés pour authentifier toutes les requêtes suivantes.

🏬

Organisation gérée

Représente un seul emplacement physique (p. ex. un magasin ou un restaurant), appelée Unit dans le HUB. Créée via la Management API et liée à un Groupe au sein de votre Compte.

🛡️

TSS (Système de sécurité technique)

Le composant de signature principal. Doit être créé, configuré avec un code PIN administrateur et initialisé avant de pouvoir signer des transactions.

💻

Client

Représente un terminal de point de vente ou une application qui crée des transactions contre un TSS.

🧾

Transaction

Un enregistrement fiscal signé. Une fois votre TSS et votre Client prêts, vous pouvez démarrer et terminer des transactions pour générer des signatures cryptographiques.

Prérequis

📘Avant de commencer

Vous avez besoin d’un compte fiskaly et d’un accès au fiskaly HUB. Si vous n’avez pas encore de compte, inscrivez-vous ici. Vous aurez également besoin d’un outil pour effectuer des requêtes HTTP — par exemple cURL, Postman ou votre propre code d’application.

Flux de travail d’intégration

Le diagramme ci-dessous montre les dix étapes de l’intégration SIGN DE. Cliquez sur n’importe quelle vignette pour accéder à l’étape de configuration correspondante.

Configuration étape par étape

S'inscrire sur le HUB
Accédez à hub.fiskaly.com et créez votre compte fiskaly. Vous recevrez un email de confirmation — cliquez sur le lien pour vérifier votre adresse et activer votre compte.
Créer un Compte et un Groupe
Lorsque vous vous connectez au HUB pour la première fois, vous êtes invité à configurer votre Compte — l’entité de niveau supérieur représentant votre entreprise (fournisseur POS ou revendeur). Le HUB vous guidera également pour créer un Groupe, une couche intermédiaire au sein de votre Compte pour regrouper les organisations gérées de manière logique (par exemple, un Groupe par pays).
💡Pas encore prêt pour la production ?
À des fins de test, vous n’avez pas besoin de remplir tous les champs. Vous pouvez laisser l’adresse de facturation vide et la compléter ultérieurement.
Après avoir terminé la configuration, le HUB affichera votre vue d’ensemble actuelle — initialement avec 0 TSS et 0 client.
Créer une clé API
Accédez à la section Clés API dans le fiskaly HUB et créez une nouvelle clé API pour votre Compte.
Vous recevrez une Clé API et un Secret API. Conservez-les en lieu sûr — vous en aurez besoin pour toutes les requêtes API suivantes.
⚠️Stockez vos identifiants en toute sécurité
Le Secret API n’est affiché qu’une seule fois. Assurez-vous de le copier et de le stocker dans un endroit sécurisé avant de fermer la fenêtre.

Créer un token (Management API)

Utilisez la Clé API et le Secret de l’étape précédente pour obtenir un jeton d’accès à la Management API.

curl -X POST https://dashboard.fiskaly.com/api/v0/auth \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "your_api_key",
    "api_secret": "your_api_secret"
  }'

const response = await fetch(
  "https://dashboard.fiskaly.com/api/v0/auth",
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      api_key: "your_api_key",
      api_secret: "your_api_secret",
    }),
  }
);

const { access_token } = await response.json();

Exemple de réponse (200 OK)

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "access_token_claims": {
    "env": "TEST",
    "organization_id": "00000000-0000-0000-0000-000000000000"
  },
  "access_token_expires_in": 300,
  "access_token_expires_at": 1577833200,
  "refresh_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token_expires_in": 300,
  "refresh_token_expires_at": 1577833200
}

Utilisez le access_token en tant que jeton Bearer dans l’en-tête Authorization pour toutes les requêtes de la Management API.

Créer une/des organisation(s) gérée(s)

Créez une ou plusieurs organisations gérées (également appelées Units dans le HUB) sous votre Groupe. Chaque Unit représente généralement un seul emplacement physique tel qu’un magasin ou un restaurant.

curl -X POST "https://dashboard.fiskaly.com/api/v0/organizations" \
  -H "Authorization: Bearer ${MANAGEMENT_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Store Berlin",
    "managed_by_organization_id": "your-group-id",
    "address_line1": "Unter den Linden 1",
    "zip": "10117",
    "town": "Berlin",
    "country_code": "DEU"
  }'

const response = await fetch(
  "https://dashboard.fiskaly.com/api/v0/organizations",
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${managementToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: "My Store Berlin",
      managed_by_organization_id: "your-group-id",
      address_line1: "Unter den Linden 1",
      zip: "10117",
      town: "Berlin",
      country_code: "DEU",
    }),
  }
);

const { _id: orgId } = await response.json();

Exemple de réponse (200 OK)

{
  "_id": "your-managed-org-id",
  "_type": "ORGANIZATION",
  "name": "My Store Berlin",
  "managed_by_organization_id": "your-group-id",
  "address_line1": "Unter den Linden 1",
  "zip": "10117",
  "town": "Berlin",
  "country_code": "DEU",
  "state": "active",
  "time_creation": "2026-03-01T10:00:00Z"
}

Notez le _id de la réponse — il s’agit de votre identifiant d’organisation gérée, nécessaire pour l’étape suivante.

💡Où trouver votre identifiant de Groupe

Votre identifiant de Groupe (managed_by_organization_id) est visible dans le fiskaly HUB sous Paramètres → Organisation, ou vous pouvez le récupérer depuis le champ organization_id dans la réponse du jeton de l’API de gestion (POST /api/v0/auth).

Créer une clé API (organisation gérée)

Générez une clé API dédiée pour l’organisation gérée. Cette clé sera utilisée pour authentifier les requêtes API SIGN DE limitées à cette organisation.

curl -X POST "https://dashboard.fiskaly.com/api/v0/organizations/${ORG_ID}/api-keys" \
  -H "Authorization: Bearer ${MANAGEMENT_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "sign-de-key",
    "status": "enabled",
    "managed_by_organization_id": "your-group-id"
  }'

const response = await fetch(
  `https://dashboard.fiskaly.com/api/v0/organizations/${orgId}/api-keys`,
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${managementToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: "sign-de-key",
      status: "enabled",
      managed_by_organization_id: "your-group-id",
    }),
  }
);

const { key: apiKey, secret: apiSecret } = await response.json();

⚠️Enregistrez ces identifiants

Le secret pour la clé API de l’organisation gérée n’est affiché qu’une seule fois. Conservez-le en lieu sûr avant de continuer.

Exemple de réponse (200 OK)

{
  "_id": "your-api-key-id",
  "_type": "MANAGED_API_KEY",
  "_envs": ["TEST"],
  "name": "sign-de-key",
  "key": "your-api-key",
  "secret": "your-api-secret",
  "status": "enabled",
  "managed_by_organization_id": "your-group-id",
  "created_at": 1577833200
}

Créer un token (SIGN DE)

Utilisez la clé et le secret API de l’organisation gérée pour obtenir un jeton d’accès SIGN DE.

curl -X POST https://kassensichv-middleware.fiskaly.com/api/v2/auth \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "managed_org_api_key",
    "api_secret": "managed_org_api_secret"
  }'

const response = await fetch(
  "https://kassensichv-middleware.fiskaly.com/api/v2/auth",
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      api_key: "managed_org_api_key",
      api_secret: "managed_org_api_secret",
    }),
  }
);

const { access_token } = await response.json();

Exemple de réponse (200 OK)

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "access_token_claims": {
    "env": "TESTING",
    "organization_id": "your-managed-org-id"
  },
  "access_token_expires_in": 86400,
  "refresh_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token_expires_in": 172800
}

Utilisez ce access_token en tant que jeton Bearer pour toutes les requêtes API SIGN DE suivantes.

Créer un TSS
Créez un nouveau Système de Sécurité Technique (TSS) en envoyant une requête PUT avec un identifiant TSS unique (UUID). Le TSS doit ensuite être initialisé avant de pouvoir signer des transactions.
TSS_ID=$(uuidgen) curl -X PUT "https://kassensichv-middleware.fiskaly.com/api/v2/tss/${TSS_ID}" \ -H "Authorization: Bearer ${ACCESS_TOKEN}" \ -H "Content-Type: application/json" \ -d '{"metadata": {}}'
Exemple de réponse (200 OK)
{ "_id": "your-tss-id", "_type": "TSS", "_env": "TEST", "_version": "2.2.2", "admin_puk": "initial-puk-from-creation", "state": "CREATED", "serial_number": "a1b2c3d4e5f6...", "public_key": "MFkwEwYH...", "certificate": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----", "signature_algorithm": "ECDSA", "signature_timestamp_format": "unixTime", "transaction_data_encoding": "UTF-8", "max_number_registered_clients": 100, "max_number_active_transactions": 1000, "time_creation": 1577833200, "metadata": {} }
⚠️Utiliser un délai d'attente généreux
La création et la personnalisation du TSS peuvent prendre jusqu’à 30 secondes. Définissez un délai d’attente de requête d’au moins 30 secondes pour les deux appels afin d’éviter des échecs prématurés.
Après la création, initialisez le TSS en quatre sous-étapes :
a) Personnaliser le TSS
Faites passer le TSS de l’état CREATED à l’état UNINITIALIZED avant de modifier le code PIN administrateur :
curl -X PATCH "https://kassensichv-middleware.fiskaly.com/api/v2/tss/${TSS_ID}" \ -H "Authorization: Bearer ${ACCESS_TOKEN}" \ -H "Content-Type: application/json" \ -d '{"state": "UNINITIALIZED"}'
b) Modifier le code PIN administrateur
Le TSS est créé dans un état UNINITIALIZED. Vous devez définir un nouveau code PIN administrateur en utilisant le admin_puk de la réponse de création.
curl -X PATCH "https://kassensichv-middleware.fiskaly.com/api/v2/tss/${TSS_ID}/admin" \ -H "Authorization: Bearer ${ACCESS_TOKEN}" \ -H "Content-Type: application/json" \ -d '{ "admin_puk": "puk-from-creation-response", "new_admin_pin": "your-secure-admin-pin" }'
c) S’authentifier en tant qu’administrateur
curl -X POST "https://kassensichv-middleware.fiskaly.com/api/v2/tss/${TSS_ID}/admin/auth" \ -H "Authorization: Bearer ${ACCESS_TOKEN}" \ -H "Content-Type: application/json" \ -d '{ "admin_pin": "your-secure-admin-pin" }'
d) Initialiser le TSS
Mettez à jour l’état du TSS à INITIALIZED :
curl -X PATCH "https://kassensichv-middleware.fiskaly.com/api/v2/tss/${TSS_ID}" \ -H "Authorization: Bearer ${ACCESS_TOKEN}" \ -H "Content-Type: application/json" \ -d '{ "state": "INITIALIZED" }'
Exemple de réponse (200 OK)
{ "_id": "your-tss-id", "_type": "TSS", "state": "INITIALIZED", "certificate": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----", "serial_number": "a1b2c3d4e5f6...", "signature_algorithm": "ECDSA", "max_number_registered_clients": 100, "max_number_active_transactions": 1000, "time_creation": "2026-03-01T10:00:00Z" }
💡Déconnecter l'administrateur une fois terminé
Une fois le TSS initialisé, déconnectez l’utilisateur administrateur comme bonne pratique de sécurité — requis avant l’utilisation en production.
curl -X POST "https://kassensichv-middleware.fiskaly.com/api/v2/tss/${TSS_ID}/admin/logout" \ -H "Authorization: Bearer ${ACCESS_TOKEN}"

Créer un client

Une fois le TSS initialisé, créez un client représentant votre terminal de point de vente ou votre application.

CLIENT_ID=$(uuidgen)

curl -X PUT "https://kassensichv-middleware.fiskaly.com/api/v2/tss/${TSS_ID}/client/${CLIENT_ID}" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "serial_number": "POS-001"
  }'

const clientId = crypto.randomUUID();

const response = await fetch(
  `https://kassensichv-middleware.fiskaly.com/api/v2/tss/${tssId}/client/${clientId}`,
  {
    method: "PUT",
    headers: {
      "Authorization": `Bearer ${accessToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ serial_number: "POS-001" }),
  }
);

Exemple de réponse (200 OK)

{
  "_id": "your-client-id",
  "_type": "CLIENT",
  "serial_number": "POS-001",
  "state": "REGISTERED",
  "tss_id": "your-tss-id",
  "time_creation": "2026-03-01T10:00:00Z"
}

⚠️serial_number est permanent

Le serial_number que vous attribuez à un client ne peut pas être modifié après sa création. Choisissez un identifiant stable et unique pour chaque terminal POS (p. ex. un numéro de série matériel ou un UUID stable que vous contrôlez).

💡Automatiser la configuration

Toute cette séquence de provisionnement (Étapes 1–9) peut être intégrée dans un flux de travail entièrement automatisé. Une fois implémenté, l’intégration d’un nouvel emplacement ne nécessite aucune interaction manuelle.

Opérations quotidiennes : Créer une transaction

Maintenant que votre TSS et votre Client sont provisionnés, vous êtes prêt pour les opérations quotidiennes. Les transactions suivent un cycle de vie en deux étapes qui correspond au flux de paiement réel :

Démarrer la transaction (ouvrir la caisse) — envoyez uniquement state: "ACTIVE" et client_id. Aucun schéma de reçu n’est requis à ce stade.
Terminer la transaction (après le paiement) — envoyez le schéma de reçu complet avec les montants et le type de paiement pour générer la signature cryptographique.

a) Démarrer la transaction

TX_ID=$(uuidgen)

curl -X PUT "https://kassensichv-middleware.fiskaly.com/api/v2/tss/${TSS_ID}/tx/${TX_ID}?tx_revision=1" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "state": "ACTIVE",
    "client_id": "your-client-id"
  }'

const txId = crypto.randomUUID();

const startResponse = await fetch(
  `https://kassensichv-middleware.fiskaly.com/api/v2/tss/${tssId}/tx/${txId}?tx_revision=1`,
  {
    method: "PUT",
    headers: {
      "Authorization": `Bearer ${accessToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      state: "ACTIVE",
      client_id: clientId,
    }),
  }
);

b) Terminer la transaction

curl -X PUT "https://kassensichv-middleware.fiskaly.com/api/v2/tss/${TSS_ID}/tx/${TX_ID}?tx_revision=2" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "state": "FINISHED",
    "client_id": "your-client-id",
    "schema": {
      "standard_v1": {
        "receipt": {
          "receipt_type": "RECEIPT",
          "amounts_per_vat_rate": [
            { "vat_rate": "NORMAL", "amount": "10.00" }
          ],
          "amounts_per_payment_type": [
            { "payment_type": "CASH", "amount": "10.00" }
          ]
        }
      }
    }
  }'

const finishResponse = await fetch(
  `https://kassensichv-middleware.fiskaly.com/api/v2/tss/${tssId}/tx/${txId}?tx_revision=2`,
  {
    method: "PUT",
    headers: {
      "Authorization": `Bearer ${accessToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      state: "FINISHED",
      client_id: clientId,
      schema: {
        standard_v1: {
          receipt: {
            receipt_type: "RECEIPT",
            amounts_per_vat_rate: [
              { vat_rate: "NORMAL", amount: "10.00" },
            ],
            amounts_per_payment_type: [
              { payment_type: "CASH", amount: "10.00" },
            ],
          },
        },
      },
    }),
  }
);

Exemple de réponse (200 OK)

{
  "_id": "your-tx-id",
  "_type": "TRANSACTION",
  "state": "FINISHED",
  "client_id": "your-client-id",
  "tss_id": "your-tss-id",
  "time_start": "2026-03-01T10:00:00Z",
  "time_end": "2026-03-01T10:05:00Z",
  "qr_code_data": "V0;955002-00;Kassenbeleg-V1;...",
  "signature": {
    "value": "MEUCIQDx...",
    "timestamp": "2026-03-01T10:05:00Z",
    "serial_number": "a1b2c3d4e5f6..."
  }
}

La réponse inclut la transaction signée avec une chaîne qr_code_data pour le code QR du reçu et une signature cryptographique du TSS.

Prochaines étapes

Référence API SIGN DE

Documentation API complète pour l'endpoint KassenSichV v2 — toutes les ressources, paramètres et réponses.

Guide pour les nouveaux clients

Guide détaillé du processus de configuration avec téléchargements de collections Postman et tutoriels vidéo.

Manuel utilisateur HUB

Apprenez à gérer les organisations, les clés API et les TSS via l'interface du fiskaly HUB.

Validation du code QR

Comprenez le format des données du code QR sur vos reçus et comment valider les transactions signées.

Was this page helpful?

Intégration étape par étape

Compte et Groupe

Clé API et Token

Organisation gérée

TSS (Système de sécurité technique)

Client

Transaction

Prérequis

Flux de travail d’intégration

Configuration étape par étape

S'inscrire sur le HUB

Créer un Compte et un Groupe

Créer une clé API

Créer un token (Management API)

Créer une/des organisation(s) gérée(s)

Créer une clé API (organisation gérée)

Créer un token (SIGN DE)

Créer un TSS

Créer un client

Opérations quotidiennes : Créer une transaction

Prochaines étapes

Référence API SIGN DE

Guide pour les nouveaux clients

Manuel utilisateur HUB

Validation du code QR