Intégrer FakturBi avec l'aide d'une IA
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.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 : Java 21, avec java.net.http.HttpClient et Jackson
- 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. Propose une classe FakturbiClient avec des records pour les requêtes et les réponses, une exception typée qui porte code, message et requestId, et des tests JUnit 5.
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.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 : TypeScript sur Node.js 20 ou plus, avec fetch natif
- 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. Propose un module fakturbi.ts typé strictement (types des requêtes et réponses, erreur typée avec code, message et requestId) et des tests avec le framework de test de mon projet.
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.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 : Python 3.11 ou plus, avec httpx
- 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. Propose un module fakturbi.py avec des dataclasses ou TypedDict pour les données, une exception FakturbiError qui porte code, message et request_id, et des tests pytest.
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, etrequestIdest 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é.