Bonnes Pratiques pour les Agents

Ce guide décrit l’approche recommandée pour les agents IA intégrant les APIs fiskaly — de la découverte jusqu’au déploiement en production. Il met en évidence les erreurs courantes et les nuances par pays qui compliquent les intégrations automatisées.

Flux d’intégration recommandé

1. Découvrir

   Récupérez /products.json pour identifier le bon produit pour votre pays cible. Vérifiez apiArchitecture pour déterminer si vous travaillez avec une API spécialisée ou unifiée.

2. Authentifier

   POST /auth avec la clé API et le secret fournis par l’utilisateur. Mettez en cache le token d’accès (TTL 24h) — ne vous ré-authentifiez pas par requête.

3. Provisionner

   Créez l’infrastructure de signature pour le pays cible : TSS + Client (DE), Taxpayer + Location + System (FR/IT) ou équivalent. Vérifiez /human-interventions.json pour les étapes nécessitant une saisie humaine.

4. Effectuer des transactions

   Signez les transactions via l’endpoint approprié. SIGN DE utilise un pattern PUT à deux appels (ACTIVE → FINISHED). SIGN FR et SIGN IT utilisent un pattern POST à deux appels (Intention → Transaction).

Actions automatisables vs. nécessitant un humain

Toutes les étapes d’une intégration fiskaly ne peuvent pas être automatisées. Avant de construire un flux de travail d’agent, vérifiez quelles actions nécessitent un humain :

Catégorie	Nombre	Exemples
Entièrement automatisable	11	Authentification, création TSS, signature de transactions
Partiellement automatisable	2	Saisie des données du contribuable (l’humain fournit l’identifiant fiscal, l’agent effectue l’appel API)
Nécessite un humain	7	Création de compte, génération de clé API, mise en production

Concevez votre agent pour qu’il fasse une pause et invite l’utilisateur lors des étapes nécessitant un humain, puis reprenne l’automatisation. Voir le Registre des Interventions Humaines complet pour plus de détails.

💡Tip

La version lisible par machine sur /human-interventions.json peut être interrogée à l’exécution pour ajuster dynamiquement le flux de travail de votre agent.

Anti-patterns courants

Coder en dur les URLs de base

Les URLs de base diffèrent entre les environnements TEST et LIVE, et entre les APIs spécialisées et unifiées. Récupérez-les toujours depuis /products.json plutôt que de les coder en dur.

// Ne faites pas ça
const BASE_URL = "https://kassensichv-middleware.fiskaly.com/api/v2";

// Faites ça — lisez depuis products.json
const product = products.find(p => p.id === "sign-de");
const baseUrl = product.baseUrls.test;

Se ré-authentifier par requête

Le token d’accès est valide 24 heures. Mettez-le en cache et ne vous ré-authentifiez qu’en réponse à des erreurs 401. Se ré-authentifier par requête fait perdre du temps et peut déclencher des limites de taux.

Passer l’environnement TEST

Développez et testez toujours d’abord contre l’environnement TEST (sandbox). TEST est gratuit, utilise la même surface API que LIVE et permet d’itérer sans affecter les données fiscales réelles.

Réutiliser les UUIDs

Pour les APIs spécialisées (SIGN DE, SIGN AT, SIGN ES), les IDs de ressources sont des UUIDs générés par le client. Générez toujours des UUIDs frais — réutiliser un UUID provoque un 409 Conflict.

Ignorer les clés d’idempotence

Pour les APIs unifiées (SIGN FR, SIGN IT), les requêtes POST et PATCH nécessitent un header X-Idempotency-Key. Générez un UUID frais pour chaque opération unique. Les nouvelles tentatives de la même opération doivent réutiliser la même clé.

Interroger les exports de manière synchrone

Les exports DSFinV-K et autres opérations d’export sont asynchrones. Déclenchez l’export, puis interrogez l’achèvement — ne bloquez pas sur la requête initiale.

Particularités par pays

Allemagne (SIGN DE)

⚠️PIN administrateur requis

L’initialisation du TSS nécessite la définition d’un PIN administrateur via PATCH /tss/{id} avant de changer l’état en INITIALIZED. Le PIN doit être conservé en toute sécurité — le perdre nécessite le remplacement du TSS.

• Machine d’états du TSS : UNINITIALIZED → INITIALIZED → DISABLED
• UUIDs générés par le client pour tous les IDs de ressources
• Les transactions utilisent un modèle de révisions : révision 1 (ACTIVE) → révision 2 (FINISHED)
• L’export DSFinV-K est légalement obligatoire pour les audits

France (SIGN FR)

• Nécessite une hiérarchie d’organisations : Organization GROUP → Organization UNIT → Subject → Taxpayer → Location → System → Record
• La création d’un contribuable nécessite un vrai numéro SIREN (fourni par un humain)
• Pattern d’enregistrement à deux appels : Intention (type: INTENTION) → Transaction (type: TRANSACTION)
• Headers obligatoires sur chaque requête : X-Api-Version, X-Idempotency-Key, X-Scope-Identifier

Italie (SIGN IT)

• Même architecture d’API unifiée que la France
• Le contribuable a besoin des identifiants de l’Agenzia delle Entrate (AdE) — fournis par un humain
• Supporte la Lotteria degli Scontrini (loterie de reçus) — incluez lottery_code dans les enregistrements lorsque le client en fournit un
• Le reporting en temps réel à l’AdE signifie que la signature des transactions n’est pas sûre à réessayer sans clés d’idempotence

Autriche (SIGN AT)

• Réglementation RKSV avec intégration FinanzOnline
• URL de base séparée : rksv-middleware.fiskaly.com/api/v1
• Export DEP (Datenerfassungsprotokoll) pour la piste d’audit

Espagne (SIGN ES)

• Réglementations TicketBAI et Verifactu
• Signature et soumission de factures en XML (pas JSON comme d’autres produits)
• Variations régionales entre communautés autonomes

Scripts de démarrage rapide

Des scripts de démarrage rapide de bout en bout sont disponibles pour les tests automatisés :

• scripts/sign-de-quickstart.mjs — Flux SIGN DE complet : authentification → TSS → client → transaction
• scripts/sign-fr-quickstart.mjs — Flux SIGN FR complet : authentification → org → contribuable → emplacement → système → enregistrement

Ces scripts démontrent le parcours heureux complet et peuvent servir d’implémentations de référence pour les intégrations construites par des agents.