Intégration Étape par Étape

Ce guide vous accompagne tout au long du processus complet d’intégration de l’API fiskaly SIGN FR pour la conformité fiscale française, en combinant le fiskaly HUB et des requêtes API. À la fin, vous disposerez d’un Système entièrement opérationnel avec des Enregistrements signés, journalisés et archivés.

Avant de commencer la configuration, voici ce que vous allez mettre en place :

🏢

Organization

AccountGénéré par HUB
Entité de niveau supérieur dans fiskaly HUB. Ne peut pas être imbriquée dans un autre Account.
GroupGénéré par HUB
Couche intermédiaire organisant les Units en clusters logiques (p. ex. un par pays).
UnitGénéré par API
Merchant / Taxpayer opérant au sein du Group.

🔑

API Key & Secret

Niveau GroupGénéré par HUB
Généré dans HUB pour l’Organization GROUP. Utilisé pour s’authentifier dans l’API SIGN FR afin de créer des Organization Units et leurs API Keys.
Niveau UnitGénéré par API
Généré via l’API (endpoint createSubject) pour l’Organization UNIT. Utilisé pour s’authentifier pour tous les appels opérationnels au niveau de l’Unit.

🧾

Taxpayer

Représentation d’une COMPANY ou d’un INDIVIDUAL enregistré auprès des autorités fiscales françaises.

COMPANY
Personne morale
INDIVIDUAL
Personne physique

📍

Location

HEAD_OFFICE
Créée automatiquement lors de la création du Taxpayer, partage le même UUID. Correspond à l’adresse légale.
BRANCH
Chaque boutique, magasin ou autre établissement commercial où se déroulent des opérations fiscales.

💻

System

FISCAL_DEVICE
Abstraction d’une caisse enregistreuse utilisée pour enregistrer les données de transaction conformément à la réglementation fiscale française (NF525).

📄

Record

Chaque opération commerciale effectuée dans le System. Nécessite deux appels successifs :

INTENTION
Identifie l’intention d’enregistrer une transaction dans le System.
TRANSACTION
Identifie un reçu fiscal émis par le System.

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 le code de votre application.

💡Environnements TEST et LIVE

Les API Keys générées dans l’environnement TEST créeront des ressources TEST, tandis que celles de l’environnement LIVE créeront des ressources LIVE. Pour plus de détails, consultez notre article sur les environnements TEST et LIVE.

Flux d’Intégration

Le diagramme ci-dessous illustre le flux de travail et met en évidence les étapes essentielles à accomplir pour réussir votre intégration. Chaque tuile renvoie directement à l’étape de configuration correspondante ci-dessous.

📘Important

Les étapes marquées en jaune doivent être effectuées directement sur le HUB, tandis que les étapes restantes doivent être gérées via l’API. Réaliser chaque action dans le bon contexte est une étape importante pour une intégration réussie.

Configuration Étape par Étape

S'inscrire sur le HUB
Commencez par vous inscrire sur le fiskaly HUB.
La création d’un compte fiskaly est la première étape, après laquelle vous pourrez configurer la première structure organisationnelle de votre entreprise et générer votre API Key.
📘Tutoriel vidéo
Regardez notre vidéo pour une explication étape par étape sur la configuration de votre compte et de votre première organisation.
Créer un Account et un Group
Continuez en créant votre Account et votre premier Group via le HUB. Dans l’API SIGN FR, le GROUP est une couche intermédiaire obligatoire au sein de votre ACCOUNT, utilisée pour organiser vos organisations de type UNIT.
Créer une API Key
L’étape suivante consiste à générer une API Key pour votre organisation via le HUB. Cette paire API Key et Secret est nécessaire pour créer vos organisations de type UNIT (Étape 5).
⚠️Conservez vos identifiants en lieu sûr
L’API Secret n’est affiché qu’une seule fois. Assurez-vous de le copier et de le conserver dans un endroit sécurisé avant de fermer la fenêtre.
À partir de la prochaine étape, vous utiliserez notre API SIGN FR.

Créer un Token (Management)
Commencez à utiliser l’API SIGN FR via l’endpoint createToken. Vous devrez créer un token pour vous authentifier lors des étapes suivantes.
curl -X POST https://test.api.fiskaly.com/api/v1/auth/token \ -H "Content-Type: application/json" \ -H "X-Api-Version: 2026-02-03" \ -d '{ "api_key": "YOUR_API_KEY", "api_secret": "YOUR_API_SECRET" }'
Exemple de réponse (200 OK)
{ "content": { "id": "tok_abc123", "authentication": { "type": "JWT", "bearer": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...", "expires_at": "2026-03-02T12:00:00Z" }, "organization": { "id": "YOUR_GROUP_ORG_ID" }, "subject": { "id": "sub_abc123" } }, "metadata": { "trace_identifier": "trace_abc123", "api_version": "2026-02-03" } }

Créer une Organization UNIT

Continuez en créant une Organization de type UNIT via l’endpoint createOrganization. Vous devrez créer une Organization UNIT pour chacune de vos représentations d’assujetti.

Lors de la création d’une Organization de type UNIT, assurez-vous qu’elle est associée à l’Organization de type GROUP précédemment créée via le HUB. Pour ce faire, utilisez le token généré à partir des API Keys créées pour votre Organization de type GROUP. Cela reflète la structure hiérarchique dans laquelle l’Organization de type UNIT est imbriquée sous votre Organization de type GROUP.

curl -X POST https://test.api.fiskaly.com/api/v1/organizations \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Api-Version: 2026-02-03" \
  -H "X-Idempotency-Key: YOUR_UNIQUE_UUID" \
  -H "X-Scope-Identifier: YOUR_GROUP_ORG_ID" \
  -d '{
    "type": "UNIT",
    "name": "My UNIT Organization",
    "parent_id": "YOUR_GROUP_ORG_ID"
  }'

const response = await fetch(
  "https://test.api.fiskaly.com/api/v1/organizations",
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${accessToken}`,
      "Content-Type": "application/json",
      "X-Api-Version": "2026-02-03",
      "X-Idempotency-Key": crypto.randomUUID(),
      "X-Scope-Identifier": "YOUR_GROUP_ORG_ID",
    },
    body: JSON.stringify({
      type: "UNIT",
      name: "My UNIT Organization",
      parent_id: "YOUR_GROUP_ORG_ID",
    }),
  }
);

const organization = await response.json();

Exemple de réponse (201 Created)

{
  "content": {
    "id": "org_unit_abc123",
    "state": "ENABLED",
    "type": "UNIT",
    "name": "My UNIT Organization",
    "organization": {
      "id": "YOUR_GROUP_ORG_ID"
    }
  },
  "metadata": {
    "trace_identifier": "trace_abc123",
    "api_version": "2026-02-03"
  }
}

Créer une Subject API Key

Créez un Subject de type API_KEY via l’endpoint createSubject. Le lien entre l’Organization de type UNIT et l’API Key est établi via X-Scope-Identifier (en utilisant l’id de l’Organization nouvellement créée).

curl -X POST https://test.api.fiskaly.com/api/v1/subjects \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Api-Version: 2026-02-03" \
  -H "X-Idempotency-Key: YOUR_UNIQUE_UUID" \
  -H "X-Scope-Identifier: YOUR_UNIT_ORG_ID" \
  -d '{
    "type": "API_KEY"
  }'

const response = await fetch(
  "https://test.api.fiskaly.com/api/v1/subjects",
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${accessToken}`,
      "Content-Type": "application/json",
      "X-Api-Version": "2026-02-03",
      "X-Idempotency-Key": crypto.randomUUID(),
      "X-Scope-Identifier": "YOUR_UNIT_ORG_ID",
    },
    body: JSON.stringify({
      type: "API_KEY",
    }),
  }
);

const subject = await response.json();
const { api_key, api_secret } = subject.content.credentials;

Exemple de réponse (201 Created)

{
  "content": {
    "id": "sub_abc123",
    "state": "ENABLED",
    "type": "API_KEY",
    "credentials": {
      "api_key": "fsk_unit_abc123",
      "api_secret": "secret_only_shown_once"
    }
  },
  "metadata": {
    "trace_identifier": "trace_abc123",
    "api_version": "2026-02-03"
  }
}

Créer un Token (UNIT)

Créez ensuite un token qui sera utilisé pour créer des ressources au sein de l’Organization de type UNIT correspondante.

curl -X POST https://test.api.fiskaly.com/api/v1/auth/token \
  -H "Content-Type: application/json" \
  -H "X-Api-Version: 2026-02-03" \
  -d '{
    "api_key": "YOUR_UNIT_API_KEY",
    "api_secret": "YOUR_UNIT_API_SECRET"
  }'

const response = await fetch(
  "https://test.api.fiskaly.com/api/v1/auth/token",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-Api-Version": "2026-02-03",
    },
    body: JSON.stringify({
      api_key: "YOUR_UNIT_API_KEY",
      api_secret: "YOUR_UNIT_API_SECRET",
    }),
  }
);

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

Exemple de réponse (200 OK)

{
  "content": {
    "id": "tok_unit_abc123",
    "authentication": {
      "type": "JWT",
      "bearer": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
      "expires_at": "2026-03-02T12:00:00Z"
    },
    "organization": {
      "id": "org_unit_abc123"
    },
    "subject": {
      "id": "sub_abc123"
    }
  },
  "metadata": {
    "trace_identifier": "trace_abc123",
    "api_version": "2026-02-03"
  }
}

Créer un Taxpayer

Vous êtes maintenant prêt à créer les éléments opérationnels nécessaires à la fiscalisation en France. Utilisez l’endpoint createTaxpayer pour créer la représentation d’un assujetti :

Définissez le Taxpayer comme type COMPANY (personne morale) ou INDIVIDUAL (personne physique). Dans les deux cas, name et address doivent être fournis.
Dans les informations de fiscalization françaises, indiquez :
- tax_id_number : numéro d’identification d’entreprise français (SIREN) délivré par l’INSEE
- credentials : identifiants du portail de fiscalisation français

Une fois créé, le state du Taxpayer est défini sur ACQUIRED. Mettez-le à jour avec COMMISSIONED via l’endpoint updateTaxpayer.

# Créer Taxpayer
curl -X POST https://test.api.fiskaly.com/api/v1/taxpayers \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Api-Version: 2026-02-03" \
  -H "X-Idempotency-Key: YOUR_UNIQUE_UUID" \
  -H "X-Scope-Identifier: YOUR_UNIT_ORG_ID" \
  -d '{
    "type": "COMPANY",
    "name": "My Company",
    "address": {
      "street": "123 Rue de Rivoli",
      "postal_code": "75001",
      "city": "Paris",
      "country_code": "FR"
    },
    "fiscalization": {
      "tax_id_number": "123456789",
      "credentials": {
        "type": "PORTAL_ACCESS",
        "username": "YOUR_PORTAL_USERNAME",
        "password": "YOUR_PORTAL_PASSWORD"
      }
    }
  }'

# Commissionner Taxpayer
curl -X PATCH https://test.api.fiskaly.com/api/v1/taxpayers/YOUR_TAXPAYER_ID \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Api-Version: 2026-02-03" \
  -H "X-Scope-Identifier: YOUR_UNIT_ORG_ID" \
  -d '{
    "state": "COMMISSIONED"
  }'

// Créer Taxpayer
const createResponse = await fetch(
  "https://test.api.fiskaly.com/api/v1/taxpayers",
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${accessToken}`,
      "Content-Type": "application/json",
      "X-Api-Version": "2026-02-03",
      "X-Idempotency-Key": crypto.randomUUID(),
      "X-Scope-Identifier": "YOUR_UNIT_ORG_ID",
    },
    body: JSON.stringify({
      type: "COMPANY",
      name: "My Company",
      address: {
        street: "123 Rue de Rivoli",
        postal_code: "75001",
        city: "Paris",
        country_code: "FR",
      },
      fiscalization: {
        tax_id_number: "123456789",
        credentials: {
          type: "PORTAL_ACCESS",
          username: "YOUR_PORTAL_USERNAME",
          password: "YOUR_PORTAL_PASSWORD",
        },
      },
    }),
  }
);

const taxpayer = await createResponse.json();

// Commissionner Taxpayer
await fetch(
  `https://test.api.fiskaly.com/api/v1/taxpayers/${taxpayer.content.id}`,
  {
    method: "PATCH",
    headers: {
      "Authorization": `Bearer ${accessToken}`,
      "Content-Type": "application/json",
      "X-Api-Version": "2026-02-03",
      "X-Scope-Identifier": "YOUR_UNIT_ORG_ID",
    },
    body: JSON.stringify({
      state: "COMMISSIONED",
    }),
  }
);

Créer une Location

Pour chaque établissement commercial, créez une Location de type BRANCH via l’endpoint createLocation.

Une fois créée, le state de la Location est défini sur ACQUIRED. Mettez-le à jour avec COMMISSIONED via l’endpoint updateLocation.

# Créer Location
curl -X POST https://test.api.fiskaly.com/api/v1/locations \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Api-Version: 2026-02-03" \
  -H "X-Idempotency-Key: YOUR_UNIQUE_UUID" \
  -H "X-Scope-Identifier: YOUR_UNIT_ORG_ID" \
  -d '{
    "type": "BRANCH",
    "address": {
      "street": "123 Rue de Rivoli",
      "postal_code": "75001",
      "city": "Paris",
      "country_code": "FR"
    }
  }'

# Commissionner Location
curl -X PATCH https://test.api.fiskaly.com/api/v1/locations/YOUR_LOCATION_ID \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Api-Version: 2026-02-03" \
  -H "X-Scope-Identifier: YOUR_UNIT_ORG_ID" \
  -d '{
    "state": "COMMISSIONED"
  }'

// Créer Location
const createResponse = await fetch(
  "https://test.api.fiskaly.com/api/v1/locations",
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${accessToken}`,
      "Content-Type": "application/json",
      "X-Api-Version": "2026-02-03",
      "X-Idempotency-Key": crypto.randomUUID(),
      "X-Scope-Identifier": "YOUR_UNIT_ORG_ID",
    },
    body: JSON.stringify({
      type: "BRANCH",
      address: {
        street: "123 Rue de Rivoli",
        postal_code: "75001",
        city: "Paris",
        country_code: "FR",
      },
    }),
  }
);

const location = await createResponse.json();

// Commissionner Location
await fetch(
  `https://test.api.fiskaly.com/api/v1/locations/${location.content.id}`,
  {
    method: "PATCH",
    headers: {
      "Authorization": `Bearer ${accessToken}`,
      "Content-Type": "application/json",
      "X-Api-Version": "2026-02-03",
      "X-Scope-Identifier": "YOUR_UNIT_ORG_ID",
    },
    body: JSON.stringify({
      state: "COMMISSIONED",
    }),
  }
);

Créer un System

L’endpoint createSystem vous permet de créer une abstraction pour chaque appareil utilisé pour émettre des tickets. Chaque caisse enregistreuse ou terminal POS doit être fourni comme nouveau System de type FISCAL_DEVICE.

Un System sera connecté à une Location de type BRANCH précédemment créée.
Pour chaque appareil, fournissez les informations produit (MPN, marque, date de début d’utilisation) et les détails du logiciel.

Une fois créé, le state du System est défini sur ACQUIRED. Mettez-le à jour avec COMMISSIONED via l’endpoint updateSystem.

# Créer System
curl -X POST https://test.api.fiskaly.com/api/v1/systems \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Api-Version: 2026-02-03" \
  -H "X-Idempotency-Key: YOUR_UNIQUE_UUID" \
  -H "X-Scope-Identifier: YOUR_UNIT_ORG_ID" \
  -d '{
    "type": "FISCAL_DEVICE",
    "location_id": "YOUR_LOCATION_ID",
    "product": {
      "mpn": "POS-1000",
      "brand": "My POS Brand",
      "usage_start_date": "2026-03-01",
      "software": {
        "name": "My POS Software",
        "version": "1.0.0"
      }
    }
  }'

# Commissionner System
curl -X PATCH https://test.api.fiskaly.com/api/v1/systems/YOUR_SYSTEM_ID \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Api-Version: 2026-02-03" \
  -H "X-Scope-Identifier: YOUR_UNIT_ORG_ID" \
  -d '{
    "state": "COMMISSIONED"
  }'

// Créer System
const createResponse = await fetch(
  "https://test.api.fiskaly.com/api/v1/systems",
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${accessToken}`,
      "Content-Type": "application/json",
      "X-Api-Version": "2026-02-03",
      "X-Idempotency-Key": crypto.randomUUID(),
      "X-Scope-Identifier": "YOUR_UNIT_ORG_ID",
    },
    body: JSON.stringify({
      type: "FISCAL_DEVICE",
      location_id: "YOUR_LOCATION_ID",
      product: {
        mpn: "POS-1000",
        brand: "My POS Brand",
        usage_start_date: "2026-03-01",
        software: {
          name: "My POS Software",
          version: "1.0.0",
        },
      },
    }),
  }
);

const system = await createResponse.json();

// Commissionner System
await fetch(
  `https://test.api.fiskaly.com/api/v1/systems/${system.content.id}`,
  {
    method: "PATCH",
    headers: {
      "Authorization": `Bearer ${accessToken}`,
      "Content-Type": "application/json",
      "X-Api-Version": "2026-02-03",
      "X-Scope-Identifier": "YOUR_UNIT_ORG_ID",
    },
    body: JSON.stringify({
      state: "COMMISSIONED",
    }),
  }
);

Créer un Record

La création d’un Record dans SIGN FR nécessite deux appels successifs :

Partie A) INTENTION — au début du processus de vente
Partie B) TRANSACTION — après le processus de paiement

# Partie A) Créer Record — INTENTION
curl -X POST https://test.api.fiskaly.com/api/v1/records \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Api-Version: 2026-02-03" \
  -H "X-Idempotency-Key: YOUR_UNIQUE_UUID_1" \
  -H "X-Scope-Identifier: YOUR_UNIT_ORG_ID" \
  -d '{
    "type": "INTENTION",
    "system_id": "YOUR_SYSTEM_ID",
    "operation": {
      "type": "TRANSACTION"
    }
  }'

# Partie B) Créer Record — TRANSACTION
curl -X POST https://test.api.fiskaly.com/api/v1/records \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Api-Version: 2026-02-03" \
  -H "X-Idempotency-Key: YOUR_UNIQUE_UUID_2" \
  -H "X-Scope-Identifier: YOUR_UNIT_ORG_ID" \
  -d '{
    "type": "TRANSACTION",
    "intention_id": "YOUR_INTENTION_RECORD_ID",
    "operation": {
      "type": "RECEIPT",
      "document": {
        "number": "R-2026-0001",
        "date": "2026-03-01T12:00:00Z",
        "amounts": {
          "total_including_vat": "12000",
          "total_excluding_vat": "10000"
        }
      },
      "entries": [
        {
          "type": "SALE",
          "description": "Product A",
          "good_or_service": "GOOD"
        }
      ]
    }
  }'

// Partie A) Créer Record — INTENTION
const intentionResponse = await fetch(
  "https://test.api.fiskaly.com/api/v1/records",
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${accessToken}`,
      "Content-Type": "application/json",
      "X-Api-Version": "2026-02-03",
      "X-Idempotency-Key": crypto.randomUUID(),
      "X-Scope-Identifier": "YOUR_UNIT_ORG_ID",
    },
    body: JSON.stringify({
      type: "INTENTION",
      system_id: "YOUR_SYSTEM_ID",
      operation: {
        type: "TRANSACTION",
      },
    }),
  }
);

const intention = await intentionResponse.json();

// Partie B) Créer Record — TRANSACTION
const transactionResponse = await fetch(
  "https://test.api.fiskaly.com/api/v1/records",
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${accessToken}`,
      "Content-Type": "application/json",
      "X-Api-Version": "2026-02-03",
      "X-Idempotency-Key": crypto.randomUUID(),
      "X-Scope-Identifier": "YOUR_UNIT_ORG_ID",
    },
    body: JSON.stringify({
      type: "TRANSACTION",
      intention_id: intention.content.id,
      operation: {
        type: "RECEIPT",
        document: {
          number: "R-2026-0001",
          date: "2026-03-01T12:00:00Z",
          amounts: {
            total_including_vat: "12000",
            total_excluding_vat: "10000",
          },
        },
        entries: [
          {
            type: "SALE",
            description: "Product A",
            good_or_service: "GOOD",
          },
        ],
      },
    }),
  }
);

const transaction = await transactionResponse.json();

Une fois l’enregistrement correctement créé, les données seront signées, journalisées et archivées pour répondre aux trois obligations fiscales principales en France.

💡Automatiser la configuration

L’ensemble de cette séquence de requêtes peut être intégré dans une solution de provisionnement « en un clic » ne nécessitant aucune interaction manuelle de la part de l’utilisateur. Les détails d’implémentation vous appartiennent.

Prochaines Étapes

Référence API SIGN FR

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

Mode Offline Replay

Découvrez comment gérer les scénarios hors ligne et rejouer les transactions lorsque la connectivité est rétablie.

Glossaire

Termes et définitions clés pour le système de conformité fiscale française.

Guide HUB

Découvrez comment gérer les organisations, les API Keys et les ressources via fiskaly HUB.

Was this page helpful?