Guide pour les nouveaux clients

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 et des requêtes API. À la fin, vous disposerez d’un TSS entièrement fonctionnel avec un client prêt à signer des transactions.

Vue d’ensemble

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

🏢

Organisation

Votre entité de niveau supérieur dans fiskaly. Les organisations gérées représentent des emplacements physiques individuels.

🔑

Clé API et secret

Identifiants générés dans le HUB, utilisés pour authentifier toutes les requêtes API suivantes.

🔐

Authentification

Utilisez votre clé API et votre secret pour générer un jeton d'accès utilisé dans tous les appels API ultérieurs.

🛡️

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

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

💻

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 créer et signer des transactions.

Regardez notre tutoriel vidéo pour une explication visuelle du processus de configuration.

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 (ligne de commande), Postman ou votre propre code d’application.

Configuration étape par étape

Créer une organisation
Lorsque vous vous connectez au HUB pour la première fois, vous êtes invité à créer une organisation. Il s’agit de votre organisation principale, et toutes les organisations gérées sont créées en dessous.
En général, chaque organisation gérée correspond à un emplacement physique (p. ex. un magasin ou un restaurant).
💡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 créé votre organisation, le HUB affichera votre configuration actuelle — initialement avec 0 TSS et 0 client.
Générer une clé API et un secret
Accédez à la section Clés API dans le fiskaly HUB et créez une nouvelle clé API.
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.
Notre tutoriel vidéo montre le processus de génération d’une clé et d’un secret API.

S'authentifier avec l'API

Utilisez votre clé et votre secret API pour obtenir un jeton d’accès. Ce jeton est requis pour toutes les requêtes suivantes.

curl -X POST https://kassensichv-middleware.fiskaly.com/api/v2/auth \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "your_api_key",
    "api_secret": "your_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: "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": "TESTING",
    "organization_id": "your-org-id"
  },
  "access_token_expires_in": 86400,
  "access_token_expires_at": "2026-03-02T12:00:00Z",
  "refresh_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token_expires_in": 172800,
  "refresh_token_expires_at": "2026-03-03T12:00:00Z"
}

La réponse contient un access_token que vous devez inclure en tant que jeton Bearer dans l’en-tête Authorization de toutes les requêtes 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).

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 '{
    "description": "My first TSS"
  }'

const tssId = crypto.randomUUID();

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

Exemple de réponse (200 OK)

{
  "_id": "your-tss-id",
  "_type": "TSS",
  "_env": "TESTING",
  "_version": 1,
  "admin_puk": "initial-puk-from-creation",
  "state": "CREATED",
  "certificate": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----",
  "serial_number": "a1b2c3d4e5f6...",
  "public_key": "BHxw...",
  "signature_algorithm": "ECDSA",
  "signature_timestamp_format": "ISO8601",
  "transaction_data_encoding": "UTF-8",
  "max_number_registered_clients": 100,
  "max_number_active_transactions": 1000,
  "time_creation": "2026-03-01T10:00:00Z",
  "metadata": {}
}

Après la création, vous devez initialiser le TSS. Cela implique trois sous-étapes :

a) Modifier le code PIN administrateur

Le TSS est créé dans un état UNINITIALIZED. Vous devez définir un nouveau code PIN administrateur avant l’initialisation.

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": "initial-puk-from-creation",
    "new_admin_pin": "your-secure-admin-pin"
  }'

await fetch(
  `https://kassensichv-middleware.fiskaly.com/api/v2/tss/${tssId}/admin`,
  {
    method: "PATCH",
    headers: {
      "Authorization": `Bearer ${accessToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      admin_puk: "initial-puk-from-creation",
      new_admin_pin: "your-secure-admin-pin",
    }),
  }
);

b) 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"
  }'

await fetch(
  `https://kassensichv-middleware.fiskaly.com/api/v2/tss/${tssId}/admin/auth`,
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${accessToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      admin_pin: "your-secure-admin-pin",
    }),
  }
);

c) 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"
  }'

await fetch(
  `https://kassensichv-middleware.fiskaly.com/api/v2/tss/${tssId}`,
  {
    method: "PATCH",
    headers: {
      "Authorization": `Bearer ${accessToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      state: "INITIALIZED",
    }),
  }
);

Exemple de réponse (200 OK)

{
  "_id": "your-tss-id",
  "_type": "TSS",
  "_env": "TESTING",
  "_version": 2,
  "state": "INITIALIZED",
  "certificate": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----",
  "serial_number": "a1b2c3d4e5f6...",
  "public_key": "BHxw...",
  "signature_algorithm": "ECDSA",
  "signature_timestamp_format": "ISO8601",
  "transaction_data_encoding": "UTF-8",
  "max_number_registered_clients": 100,
  "max_number_active_transactions": 1000,
  "time_creation": "2026-03-01T10:00:00Z",
  "metadata": {}
}

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",
  "_env": "TESTING",
  "_version": 1,
  "serial_number": "POS-001",
  "state": "REGISTERED",
  "tss_id": "your-tss-id",
  "time_creation": "2026-03-01T10:00:00Z",
  "metadata": {}
}

Créer une transaction

Vous pouvez maintenant créer votre première transaction signée. Les transactions suivent un cycle de vie : démarrer la transaction, puis la terminer.

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,
    }),
  }
);

Exemple de réponse (200 OK)

{
  "_id": "your-tx-id",
  "_type": "TRANSACTION",
  "_env": "TESTING",
  "_version": 1,
  "number": 1,
  "state": "ACTIVE",
  "client_id": "your-client-id",
  "client_serial_number": "POS-001",
  "tss_id": "your-tss-id",
  "tss_serial_number": "a1b2c3d4e5f6...",
  "time_start": "2026-03-01T10:00:00Z",
  "revision": 1,
  "latest_revision": 1,
  "log": {
    "operation": "START",
    "timestamp": "2026-03-01T10:00:00Z",
    "timestamp_format": "ISO8601"
  },
  "signature": {
    "value": "MEUCIQDx...",
    "timestamp": "2026-03-01T10:00:00Z",
    "timestamp_format": "ISO8601",
    "serial_number": "a1b2c3d4e5f6..."
  },
  "metadata": {}
}

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",
  "_env": "TESTING",
  "_version": 2,
  "number": 1,
  "state": "FINISHED",
  "client_id": "your-client-id",
  "client_serial_number": "POS-001",
  "tss_id": "your-tss-id",
  "tss_serial_number": "a1b2c3d4e5f6...",
  "time_start": "2026-03-01T10:00:00Z",
  "time_end": "2026-03-01T10:05:00Z",
  "revision": 2,
  "latest_revision": 2,
  "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" }
        ]
      }
    }
  },
  "qr_code_data": "V0;955002-00;Kassenbeleg-V1;...",
  "log": {
    "operation": "FINISH",
    "timestamp": "2026-03-01T10:05:00Z",
    "timestamp_format": "ISO8601"
  },
  "signature": {
    "value": "MEUCIQDx...",
    "timestamp": "2026-03-01T10:05:00Z",
    "timestamp_format": "ISO8601",
    "serial_number": "a1b2c3d4e5f6..."
  },
  "metadata": {}
}

La réponse inclut les données de transaction signées avec une signature cryptographique du TSS.

Déconnecter l'administrateur
Après avoir terminé la configuration, déconnectez l’utilisateur administrateur du TSS.
curl -X POST "https://kassensichv-middleware.fiskaly.com/api/v2/tss/${TSS_ID}/admin/logout" \ -H "Authorization: Bearer ${ACCESS_TOKEN}"

💡Automatiser la configuration

Toute cette séquence de requêtes peut être intégrée dans une solution de provisionnement “en un clic” ne nécessitant aucune interaction manuelle de l’utilisateur. Les détails d’implémentation vous appartiennent.

Collection Postman

Vous pouvez également exécuter ces requêtes avec Postman. Téléchargez les fichiers de collection et d’environnement pour démarrer rapidement :

Télécharger la collection Postman

Télécharger l’environnement Postman

Consultez le tutoriel Postman pour des instructions détaillées.

Prochaines étapes

Documentation API SIGN DE

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

Guide HUB

Apprenez à gérer les organisations, les clés API et les TSS via le fiskaly HUB.

Was this page helpful?

Guide pour les nouveaux clients

Vue d’ensemble

Organisation

Clé API et secret

Authentification

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

Client

Transaction

Prérequis

Configuration étape par étape

Créer une organisation

Générer une clé API et un secret

S'authentifier avec l'API

Créer un TSS

Créer un client

Créer une transaction

Déconnecter l'administrateur

Collection Postman

Prochaines étapes

Documentation API SIGN DE

Guide HUB