FFakturBi Documentation

Intégrer FakturBi avec l'aide d'une IA

Mise à jour : novembre 20265 min de lectureAPI v1

Claude, ChatGPT ou l'assistant de votre choix peut écrire une grande partie de votre intégration. Donnez-lui le bon cadre : votre contexte, les règles de l'API et ce que vous attendez. Voici une consigne prête à copier.

Ne collez jamais une clé dans une conversation avec une IA. Ni clé réelle eiv_live_, ni clé d'essai, ni secret de webhook whsec_, ni donnée personnelle de vos clients. Le code produit lit la clé dans une variable d'environnement.

1. Préparez ce que l'IA doit savoir

Avant de copier la consigne, rassemblez :

  • une description courte de votre logiciel et de ce que vous voulez automatiser ;
  • le langage et les bibliothèques de votre projet ;
  • l'identifiant de votre entreprise émettrice (issuerId), visible dans FakturBi, menu Développeurs › Clés API ;
  • un exemple de commande ou de vente de votre système, avec des données inventées ;
  • le contrat fakturbi-v1.json, à joindre à la conversation.

2. Copiez la consigne

Choisissez votre langage, copiez, puis remplacez les passages entre crochets. La consigne est la même pour toutes les IA.

Tu es un développeur expérimenté. Aide-moi à intégrer l'API de facturation électronique FakturBi dans mon logiciel.

## Mon contexte
- Mon logiciel : [décris-le : type d'application, ce qu'il vend, où sont stockées les commandes ou les ventes]
- Langage et outils : un script shell (bash) qui utilise curl et jq
- Ce que je veux automatiser : [ex. créer une facture à chaque commande validée, la finaliser, récupérer le PDF, être prévenu par webhook]
- Mon entreprise émettrice (issuerId) : [colle l'identifiant affiché dans FakturBi]
- Exemple de donnée de mon système à transformer en facture : [colle un exemple de commande, sans donnée personnelle réelle]

## Règles de l'API FakturBi (à respecter strictement)
- Adresse de base : variable d'environnement EINVOICING_API_BASE_URL (forme [URL_API]/v1/einvoicing).
- Authentification : en-tête Authorization: Bearer <clé>. Clé d'essai eiv_test_…, clé réelle eiv_live_…. La clé est lue dans EINVOICING_API_KEY, jamais écrite dans le code ni envoyée au navigateur ou à une application mobile.
- L'espace (essai ou réel) est celui de la clé. On commence toujours en essai.
- Créer un brouillon : POST /invoices avec l'en-tête Idempotency-Key (200 caractères au plus, lié à mon opération, par exemple le numéro de commande) et un corps JSON :
  issuerId (uuid), currency (XOF, EUR, USD ou NGN), recipient (name obligatoire ; address, country sur 2 lettres, taxId, email, phone), lines (200 au plus ; description, quantity, unitPrice), amountIncludesTax (vrai si mes prix sont TTC), invoiceDate et dueDate (AAAA-MM-JJ), sourceRef (app, type, id : la référence dans mon système ; une même référence ne crée jamais deux factures).
- La réponse donne invoiceNumber, status (DRAFT), environment, les totaux (subtotal, totalTax, totalAmount) et lineId pour chaque ligne.
- Lire : GET /invoices/{invoiceNumber}. Aperçu PDF d'un document d'essai : GET /invoices/{invoiceNumber}/preview. Finaliser : POST /invoices/{invoiceNumber}/finalize (avec Idempotency-Key). Une facture finalisée ne se modifie plus.
- Corriger une facture finalisée : avoir, POST /credit-notes avec originalInvoiceNumber, kind (TOTAL ou PARTIAL), reasonCode (majuscules, chiffres et _), reasonText et, pour un avoir partiel, lines (originalLineId, netAmount), puis POST /credit-notes/{numéro}/finalize.
- Erreurs : corps JSON avec code, message et requestId. La logique se base sur code, jamais sur message. 401 CORE-401 clé absente ou invalide ; 403 CORE-403 droit manquant ; 404 document introuvable pour cette clé ; 409 FISC-IDEMPOTENCY-CONFLICT (même clé d'idempotence, autre contenu) ou FISC-SOURCE-REFERENCE-CONFLICT ; 400 FISC-ISSUER-REQUIRED si issuerId manque.
- Réessayer avec la même Idempotency-Key seulement après une coupure réseau ou une réponse 5xx, en espaçant les essais (1 s, 2 s, 4 s…) et en respectant l'en-tête Retry-After s'il est présent. Ne jamais réessayer une réponse 4xx sans corriger la requête.
- Webhooks (si je les utilise) : vérifier l'en-tête FakturBi-Signature (t=…,v1=…, HMAC SHA-256 de « t.corps brut » avec mon secret whsec_…), refuser un message de plus de 5 minutes, répondre 2xx en moins de 10 secondes, ignorer les doublons grâce à id.
- Le contrat complet est dans le fichier OpenAPI fakturbi-v1.json, que je joins : en cas de doute, il fait foi.

## Ce que j'attends de toi
1. Pose-moi d'abord les questions qui te manquent sur mon contexte, sans inventer de champ ni de route.
2. Écris des fonctions shell réutilisables, lis la clé dans une variable d'environnement, et arrête le script avec un message clair si une réponse n'est pas 2xx.
3. Une fonction qui transforme mon exemple de donnée en requête de création de facture, avec sourceRef rempli.
4. Le parcours complet en mode essai : créer le brouillon, lire, récupérer l'aperçu, finaliser, avec la gestion des erreurs et des reprises décrite ci-dessus.
5. La liste de ce que je dois vérifier avant de passer en clé réelle.

N'utilise jamais de vraie clé dans tes exemples : écris eiv_test_… à la place.

3. Vérifiez ce que l'IA vous rend

Relisez le code comme celui d'un collègue, puis contrôlez au moins ces points avant de l'exécuter :

  • la clé est lue dans une variable d'environnement et n'apparaît nulle part ailleurs ;
  • chaque création et chaque finalisation envoient Idempotency-Key ;
  • les erreurs sont traitées sur code, et requestId est journalisé ;
  • les routes et les champs existent dans fakturbi-v1.json : une IA peut en inventer ;
  • tout le parcours passe d'abord en mode essai, sur des factures TEST-….

4. Et ensuite

Quand le parcours d'essai fonctionne, suivez Passer en réel. En cas de blocage, l'assistance FakturBi a besoin du requestId de l'appel, jamais de votre clé.