Référence API

Cette page est la référence centrale pour tous les endpoints API fiskaly, les URLs de base, l’authentification et les limites de débit. Utilisez-la comme point de départ pour toute intégration de produit.

fiskaly propose deux architectures d’API. Voir L’API unifiée pour la comparaison complète.

API unifiée

L’API unifiée utilise des URLs de base partagées et un modèle de ressources commun entre les pays. Couvre actuellement SIGN FR et SIGN IT (SIGN SE à venir).

	Détails
URL de base TEST	`https://test.api.fiskaly.com`
URL de base LIVE	`https://live.api.fiskaly.com`
Headers requis	`X-Api-Version` (date, ex. `2026-02-03`), `X-Idempotency-Key` (UUID, sur POST/PATCH), `X-Scope-Identifier` (portée des ressources)
IDs de ressources	Générés par le serveur (utilisez `X-Idempotency-Key` pour l’idempotence)
Gestion des org.	Intégrée dans l’API produit (pas de Management API séparée)

Produit	Dernière version API	Docs
SIGN FR	2026-05-04	Docs
SIGN IT	2026-05-04	Docs
SIGN SE	TCS (API unifiée à venir)	Docs actuels

APIs spécialisées

Chaque API spécialisée a sa propre URL de base et son propre modèle de ressources, conçue pour un pays spécifique. Utilise la Management API pour la gestion des organisations.

Produit	Version API	URL de base (TEST)	URL de base (LIVE)	Docs
SIGN DE	v2	`kassensichv-middleware.fiskaly.com/api/v2`	`kassensichv.fiskaly.com/api/v2`	Docs interactifs
SIGN AT	v1	`rksv-middleware.fiskaly.com/api/v1`	`rksv.fiskaly.com/api/v1`	Docs
SIGN ES	v1	Contacter fiskaly pour les endpoints	Contacter fiskaly pour les endpoints	Docs
Management	v0	`management.fiskaly.com/api/v0`	`management.fiskaly.com/api/v0`	Docs interactifs

APIs de produits complémentaires

Ces produits fonctionnent aux côtés de SIGN et ne sont pas liés à une architecture API spécifique :

Produit	URL de base (TEST)	URL de base (LIVE)	Docs
DSFinV-K (Allemagne)	`dsfinvk-middleware.fiskaly.com/api/v1`	`dsfinvk.fiskaly.com/api/v1`	Docs
SUBMIT DE (Allemagne)	Via le middleware SIGN DE	Via la production SIGN DE	Docs
SAFE	Contacter fiskaly pour les endpoints	Contacter fiskaly pour les endpoints	Docs
E-Invoice	Contacter fiskaly pour les endpoints	Contacter fiskaly pour les endpoints	Docs
eReceipt	`receipt.fiskaly.com/api/v1`	`receipt.fiskaly.com/api/v1`	Docs interactifs

📘Disponibilité des endpoints

Certains produits plus récents n’ont pas encore publié leurs URLs de base publiquement. Contactez votre responsable de compte ou sales@fiskaly.com pour accéder aux endpoints de SIGN FR, SIGN ES, SIGN IT, SAFE et E-Invoice.

Authentification

Toutes les APIs fiskaly utilisent le même schéma d’authentification par Bearer token :

POST /auth avec votre api_key et api_secret
Recevez un access_token (24h) et un refresh_token (48h)
Incluez le token avec Authorization: Bearer <token> dans toutes les requêtes suivantes
Sur 401, ré-authentifiez-vous — ne réessayez pas avec le même token expiré

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

Puis incluez le token dans les requêtes suivantes :

curl -X GET https://kassensichv-middleware.fiskaly.com/api/v2/tss \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

⚠️Gardez vos secrets en sécurité

Ne committez jamais les secrets API dans le contrôle de version et ne les exposez pas dans le code côté client. Stockez-les dans des variables d’environnement ou un gestionnaire de secrets.

💡Mettez en cache votre token

L’access token est valide pendant 24 heures. Se ré-authentifier à chaque requête ajoute une latence inutile. Mettez le token en cache et ne le renouvelez que sur 401.

Environnements

Chaque produit dispose d’un environnement TEST (sandbox) et d’un environnement LIVE (production) :

	TEST (Sandbox)	LIVE (Production)
Objectif	Développement et tests d’intégration	Transactions réelles, données pertinentes pour l’audit
Données	Éphémères — sûres pour expérimenter, peuvent être réinitialisées	Permanentes — enregistrements juridiquement contraignants
Facturation	Gratuit	Par contrat
Défaut	Toutes les nouvelles organisations démarrent ici	Activer via HUB
Préfixe URL de base	Inclut généralement `middleware`	Domaine direct du produit

⚠️TEST et LIVE sont séparés

Les ressources créées en TEST n’existent pas en LIVE. Lors du passage en production, vous devez re-provisionner toutes les ressources (TSS, clients, unités de signature, etc.).

Limites de débit

Les limites de débit API varient selon le produit et le plan d’abonnement. Directives générales :

Opération	Limite typique	Notes
Authentification	10 req/min	Mettez les tokens en cache — ne vous authentifiez pas par transaction
Signature de transactions	200 req/min	Ne devrait jamais être un goulot d’étranglement pour le paiement normal
Génération d’exports	Limites plus basses	Opérations lourdes — utilisez le polling asynchrone
Opérations de gestion	60 req/min	Gestion des organisations/clés API

Headers de limites de débit

Chaque réponse API inclut des headers pour vous aider à gérer votre budget de requêtes :

Header	Description
`X-RateLimit-Limit`	Maximum de requêtes autorisées dans la fenêtre actuelle
`X-RateLimit-Remaining`	Requêtes restantes dans la fenêtre actuelle
`X-RateLimit-Reset`	Timestamp Unix quand la fenêtre de limite se réinitialise
`Retry-After`	Secondes à attendre avant de réessayer (uniquement sur les réponses 429)

Si vous recevez un 429 Too Many Requests, attendez avec un délai exponentiel. Voir la stratégie de réessai pour des indications d’implémentation.

Pour des limites enterprise ou des besoins personnalisés, contactez votre responsable de compte.

Pagination

Les APIs fiskaly utilisent deux patterns de pagination différents selon l’architecture API.

APIs spécialisées (SIGN DE, DSFinV-K)

Les APIs spécialisées utilisent la pagination basée sur l’offset avec les paramètres de requête limit et offset.

Paramètre	Défaut	Maximum	Description
`limit`	100	1000	Nombre d’éléments à retourner par page
`offset`	0	—	Nombre d’éléments à ignorer depuis le début

La réponse inclut count (total d’éléments), data (tableau de résultats), offset et limit.

curl -X GET "https://kassensichv-middleware.fiskaly.com/api/v2/tss?limit=50&offset=100" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

const response = await fetch(
  "https://kassensichv-middleware.fiskaly.com/api/v2/tss?limit=50&offset=100",
  {
    headers: { Authorization: "Bearer YOUR_ACCESS_TOKEN" },
  }
);

const { count, data, offset, limit } = await response.json();
// count: 250, data: [...50 items], offset: 100, limit: 50

API unifiée (SIGN FR, SIGN IT)

L’API unifiée utilise la pagination basée sur curseur avec les paramètres de requête page[limit] et page[after].

Paramètre	Défaut	Maximum	Description
`page[limit]`	25	100	Nombre d’éléments à retourner par page
`page[after]`	—	—	Curseur opaque du `next_cursor` d’une réponse précédente

La réponse inclut data (tableau de résultats), pagination.has_more (booléen) et pagination.next_cursor (chaîne, présent quand has_more est true).

# Première page
curl -X GET "https://test.api.fiskaly.com/signing-units?page[limit]=25" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Api-Version: 2026-05-04"

# Page suivante (utiliser next_cursor de la réponse précédente)
curl -X GET "https://test.api.fiskaly.com/signing-units?page[limit]=25&page[after]=eyJpZCI6ImFiYzEyMyJ9" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Api-Version: 2026-05-04"

let cursor = null;
let allItems = [];

do {
  const url = new URL("https://test.api.fiskaly.com/signing-units");
  url.searchParams.set("page[limit]", "25");
  if (cursor) url.searchParams.set("page[after]", cursor);

  const response = await fetch(url, {
    headers: {
      Authorization: "Bearer YOUR_ACCESS_TOKEN",
      "X-Api-Version": "2026-05-04",
    },
  });

  const { data, pagination } = await response.json();
  allItems.push(...data);
  cursor = pagination.has_more ? pagination.next_cursor : null;
} while (cursor);

💡Choisissez le bon pattern

Vérifiez quelle architecture API votre produit utilise (Unifiée vs. Spécialisée) pour déterminer quel pattern de pagination implémenter. Voir les tableaux en haut de cette page.

APIs SIGN

SIGN DE v2

Référence API interactive — documentation complète des endpoints avec try-it-out

SIGN AT v1

RKSV autrichien — guide d'intégration et référence des endpoints

SIGN FR

NF525 français — signature, clôtures, archives, mode hors ligne

SIGN ES v1

TicketBAI & Verifactu espagnols — génération XML, signature, envoi

SIGN IT

Registratore Telematico italien — RT cloud, loterie des reçus

SIGN SE (TCS)

Fiscalisation suédoise — X.509, API XML, codes de contrôle

APIs de produits complémentaires

DSFinV-K v1

Export de données fiscales allemandes — clôtures de caisse, exports d'audit

SUBMIT DE v1

Dépôt ELSTER — enregistrement des contribuables et envoi des déclarations

SAFE

Archivage fiscal conforme — automatisé ou piloté par API

E-Invoice

Facturation électronique B2B/B2G via Peppol — Belgique live, d'autres pays à venir

eReceipt v1

Génération de reçus numériques — livraison par QR, email et lien

Management API v0

Gestion des organisations, utilisateurs et clés API

SDKs et outils

Collections Postman

Requêtes préconfigurées pour SIGN DE — exploration interactive de l'API

Quick Start

Première transaction signée en moins de 5 minutes avec des exemples de code

Codes d'erreur

Chaque code d'erreur, sa cause et comment le corriger

📘Pas de SDKs client (encore)

fiskaly ne fournit pas encore de SDKs client officiels. Toutes les intégrations sont des appels directs à l’API REST. La surface d’API est suffisamment petite pour qu’un wrapper HTTP léger dans votre langage préféré soit généralement suffisant. Consultez le Changelog pour les annonces de SDK.

Was this page helpful?