Démarrage rapide

fiskaly fournit des API de conformité fiscale dans toute l’Europe. Choisissez votre pays ci-dessous pour accéder directement au guide d’intégration, ou faites défiler vers le bas pour une procédure pratique SIGN DE.

Choisissez votre pays

🇩🇪

Allemagne flagLive

Allemagne(SIGN DE)

KassenSichV — TSS, Client, Transaction

🇦🇹

Autriche flagLive

Autriche(SIGN AT)

RKSV — SCU, Cash Register, Receipt

🇫🇷

France flagLive

France(SIGN FR)

NF 525 — Organization, System, Record

🇮🇹

Italie flagLive

Italie(SIGN IT)

Conformité RT — Taxpayer, Location, System, Record

🇪🇸

Espagne flagLive

Espagne(SIGN ES)

TicketBAI et Verifactu — Taxpayer, Signer, Invoice

🇵🇹

Portugal flagLive

Portugal(SIGN PT)

AT — Taxpayer, System, Document

🇧🇪

Belgique flagLive

Belgique(E-Invoice)

Facturation électronique B2B Peppol via l'API Unifiée

🇸🇪

Suède flagLive

Suède(SIGN SE)

InfraSec TCS — codes de contrôle basés sur des certificats

💡Déploiement multi-pays ?

La France, l’Italie et la Belgique partagent l’API Unifiée — une seule intégration couvre les trois. Consultez la Planification de l’intégration pour les estimations d’effort et les calendriers de déploiement.

---

Pratique : SIGN DE en 5 minutes

La procédure ci-dessous utilise l’Allemagne (SIGN DE) comme exemple concret. Le flux est : s’authentifier → créer un TSS → signer une transaction.

📘Cette procédure utilise l'API Spécialisée SIGN DE

L’Allemagne, l’Autriche et l’Espagne ont chacune une API Spécialisée dédiée. La France et l’Italie utilisent l’API Unifiée avec un modèle de ressources partagé. Choisissez votre pays ci-dessus pour accéder au bon guide.

Temps de réalisation : ~5 minutes avec cURL, ~15 minutes si vous l’intégrez dans le code de l’application.

Prérequis

Vous avez besoin de trois choses avant de commencer :

1. Un compte fiskaly — inscrivez-vous gratuitement sur hub.fiskaly.com
2. Des identifiants API — générez une clé et un secret API dans le HUB au sein de votre organisation
3. Un client HTTP — cURL, Postman ou la bibliothèque HTTP de votre langage

⚠️Votre secret API n'est affiché qu'une seule fois

Copiez le secret immédiatement lors de sa génération. Si vous le perdez, vous devrez générer une nouvelle paire de clés. Stockez les identifiants dans des variables d’environnement ou un gestionnaire de secrets — jamais dans le code source.

Environnement

Ce guide utilise l’environnement sandbox (TEST). Toutes les nouvelles organisations démarrent ici. Aucune donnée fiscale réelle n’est créée et vous ne serez pas facturé.

	Sandbox (TEST)	Production (LIVE)
URL de base	https://kassensichv-middleware.fiskaly.com/api/v2	https://kassensichv.fiskaly.com/api/v2
Données	Éphémères — sûres pour expérimenter	Permanentes — pertinentes pour l’audit
Facturation	Gratuite	Selon contrat
Basculement	Par défaut pour les nouvelles orgs	Activer via HUB

Étape 1 : S’authentifier

Échangez votre clé et votre secret API contre un token Bearer.

cURLJavaScriptPythonJavaC#

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, refresh_token } = await response.json();

import requests

response = requests.post(
    "https://kassensichv-middleware.fiskaly.com/api/v2/auth",
    json={
        "api_key": "YOUR_API_KEY",
        "api_secret": "YOUR_API_SECRET",
    },
)

data = response.json()
access_token = data["access_token"]
refresh_token = data["refresh_token"]

HttpClient client = HttpClient.newHttpClient();
String body = """ 
    {"api_key":"YOUR_API_KEY","api_secret":"YOUR_API_SECRET"}
    """;

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://kassensichv-middleware.fiskaly.com/api/v2/auth"))
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(body))
    .build();

HttpResponse<String> response = client.send(
    request, HttpResponse.BodyHandlers.ofString());
// Analyser response.body() pour access_token

using var client = new HttpClient();
var payload = new {
    api_key = "YOUR_API_KEY",
    api_secret = "YOUR_API_SECRET"
};

var response = await client.PostAsJsonAsync(
    "https://kassensichv-middleware.fiskaly.com/api/v2/auth",
    payload);

var result = await response.Content
    .ReadFromJsonAsync<JsonElement>();
var accessToken = result
    .GetProperty("access_token").GetString();

Réponse attendue (200 OK) :

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "access_token_expires_in": 86400,
  "refresh_token": "eyJhbGciOiJSUzI1NiIs...",
  "refresh_token_expires_in": 172800
}

L’access_token est valable 24 heures. Le refresh_token est valable 48 heures. Incluez le token d’accès comme Authorization: Bearer <token> dans toutes les requêtes suivantes.

💡Ne vous ré-authentifiez pas à chaque requête

Mettez le token en cache et ne le rafraîchissez que lorsque vous recevez une réponse 401. Se ré-authentifier par requête ajoute une latence inutile à votre flux de paiement.

Étape 2 : Créer et initialiser un TSS

Un TSS (Technical Security System) est la ressource de signature certifiée. Vous en avez besoin d’un par emplacement physique. La création d’un TSS comporte trois sous-étapes : créer, définir le PIN Admin et initialiser.

a) Créer le TSS

cURLJavaScript

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": "Mon premier TSS"
  }'

const tssId = crypto.randomUUID();

const tssResponse = 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: "Mon premier TSS",
    }),
  }
);

const tss = await tssResponse.json();
// Sauvegardez tss.admin_puk — vous en avez besoin pour définir le PIN Admin

Réponse attendue (200 OK) — notez le champ admin_puk :

{
  "_id": "a1b2c3d4-...",
  "description": "Mon premier TSS",
  "state": "UNINITIALIZED",
  "admin_puk": "123456"
}

b) Définir le PIN Admin (en utilisant l’admin_puk de la réponse ci-dessus) :

cURLJavaScript

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": "123456",
    "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: tss.admin_puk,
      new_admin_pin: "your-secure-admin-pin",
    }),
  }
);

c) S’authentifier en tant qu’Admin et initialiser :

cURLJavaScript

# S'authentifier en tant qu'admin
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" }'

# Initialiser le TSS
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" }'

// S'authentifier en tant qu'admin
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" }),
  }
);

// Initialiser le TSS
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" }),
  }
);

Après l’initialisation, le state du TSS passe à INITIALIZED. Vous êtes prêt à créer des clients et à signer des transactions.

Étape 3 : Créer un client

Un client représente un seul terminal POS ou une instance d’application connectée au TSS.

cURLJavaScript

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();

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

Étape 4 : Signer une transaction

Les transactions ont un cycle de vie : démarrage (état ACTIVE) puis finalisation (état FINISHED). La réponse de finalisation contient la signature cryptographique.

a) Démarrer la transaction :

cURLJavaScript

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();

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) Finaliser la transaction (c’est là que la signature est générée) :

cURLJavaScript

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

const signedTx = await finishResponse.json();
console.log(signedTx.signature);

Réponse attendue (200 OK) — les champs clés sont signature et qr_code_data :

{
  "_id": "tx-uuid-...",
  "state": "FINISHED",
  "number": 1,
  "time_start": 1700000000,
  "time_end": 1700000001,
  "signature": {
    "value": "dGVzdC1zaWduYXR1cmU=",
    "algorithm": "ecdsa-plain-SHA384",
    "counter": 1,
    "public_key": "BHHz..."
  },
  "qr_code_data": "V0;TSS-ID;TX-NUMBER;..."
}

La chaîne qr_code_data est celle que vous encodez dans le QR code imprimé sur le reçu.

Étape 5 : Déconnecter l’Admin

Une fois la configuration terminée, déconnectez l’admin du TSS :

curl -X POST "https://kassensichv-middleware.fiskaly.com/api/v2/tss/${TSS_ID}/admin/logout" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}"

Erreurs courantes lors de la première utilisation

Erreur	Cause	Solution
401 Unauthorized	Token expiré ou incorrect	Ré-authentifiez-vous avec /auth. Vérifiez que vous utilisez la bonne clé API pour cet environnement.
400 E_TSS_NOT_INITIALIZED	Tentative de créer un client ou une transaction sur un TSS non initialisé	Suivez les trois étapes de configuration du TSS : créer, définir le PIN Admin, initialiser.
400 avec erreur “admin_puk”	PUK incorrect lors de la définition du PIN Admin	Utilisez la valeur admin_puk de la réponse de création du TSS, pas une valeur que vous avez choisie.
409 Conflict	UUID réutilisé qui existe déjà	Générez un nouveau UUID pour chaque ressource (TSS, client, transaction).
422 E_TX_INVALID_STATE	Tentative de finaliser une transaction qui n’est pas ACTIVE	Démarrez d’abord la transaction (révision 1 avec state: ACTIVE), puis finalisez (révision 2).

Pour la référence complète des erreurs, consultez Codes d’erreur.

Utiliser Postman à la place

Si vous préférez un workflow basé sur une interface graphique, téléchargez la collection Postman préconfigurée :

1. Télécharger

   Obtenez les fichiers Postman Collection et Environment.

2. Importer

   Importez les deux fichiers dans Postman.
3. Configurer

   Définissez api_key et api_secret dans les variables d’environnement.

4. Exécuter

   Exécutez les requêtes dans l’ordre — la collection utilise des variables pour enchaîner automatiquement les réponses.

Consultez le Tutoriel Postman pour une procédure détaillée.

Que construire ensuite

Guide complet SIGN DE

Configuration complète incluant la hiérarchie organisationnelle, le provisionnement en production et les QR codes des reçus

Gestion des erreurs

Stratégie de timeout, logique de retry et que faire quand le TSS est indisponible

Intégration DSFinV-K

Obligatoire pour l'Allemagne : générez des exports de données fiscales conformes pour les audits

Référence API

Documentation complète des endpoints, tous les URL de base des produits et les limites de fréquence

S'étendre à un autre pays

Ce qui change quand vous ajoutez l'Autriche, la France, l'Espagne, l'Italie ou la Suède

Planification de l'intégration (PM)

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