FacturX API

Docs · Agents IA

Utiliser FacturX API depuis un agent

Branchez FacturX API sur votre agent IA. Il transforme les données de facture de votre ERP en Factur-X PDF/A-3 EN16931, lit les règles en erreur, corrige le JSON et vérifie le fichier produit, sans code d’intégration.

1. Le serveur MCP officiel

FacturX API a son serveur MCP officiel, publié sur PyPI (facturx-mcp, version 0.1.2). Il donne à votre agent quatre outils : contrôler une facture, la convertir en Factur-X, valider un fichier et retrouver les champs liés à une règle EN16931. Il fonctionne en stdio pour un client de bureau et en streamable HTTP pour un agent hébergé.

Installer le serveur

pip install facturx-mcp   # installe aussi le SDK facturx-api
export FACTURX_BASE_URL=https://api.facturxapi.com
export FACTURX_API_KEY=VOTRE_CLE_API

Puis lancez-le en stdio, pour un client de bureau :

facturx-mcp

ou en HTTP, pour un agent hébergé :

facturx-mcp --transport streamable-http --port 8765   # http://127.0.0.1:8765/mcp

Déclaration type d’un serveur stdio dans un client MCP (format mcpServers) : 

{
  "mcpServers": {
    "facturx": {
      "command": "facturx-mcp",
      "env": {
        "FACTURX_BASE_URL": "https://api.facturxapi.com",
        "FACTURX_API_KEY": "VOTRE_CLE_API"
      }
    }
  }
}

Dans Claude Code

claude mcp add facturx --scope project -e FACTURX_BASE_URL=https://api.facturxapi.com -e FACTURX_API_KEY=VOTRE_CLE_API -- uvx facturx-mcp

Le nom facturx vient avant les options. Le serveur est enregistré pour le dossier du projet ; claude mcp list l’affiche alors « Pending approval ».

Dans Codex

codex mcp add facturx --env FACTURX_BASE_URL=https://api.facturxapi.com --env FACTURX_API_KEY=VOTRE_CLE_API -- uvx facturx-mcp

Ces deux commandes lancent le serveur avec uvx : il faut uv installé. Remplacez VOTRE_CLE_API par votre clé.

Essayé le 11/11/2026, avec la version 0.1.1 du serveur, dans Claude Code 2.1.322 et Codex CLI 0.167.0 avec l’outil facturx_explain_error. Les outils qui demandent une clé (facturx_dry_run, facturx_convert, facturx_validate) ont été essayés le 06/11/2026, avec la version 0.1.1, avec le client MCP officiel en Python. La version 0.1.2 n’a pas été essayée dans ces clients. Cursor : non essayé.

Notre serveur s’installe uniquement depuis PyPI. Le paquet npm qui porte le même nom (facturx-mcp sur npm) n’est pas le nôtre.

Sans agent, les mêmes appels existent en SDK : pip install facturx-api (Python) et npm install @facturxapi/sdk (Node.js), version 0.1.2. Sources : github.com/facturxapi/sdk.

2. Obtenir une clé

Créez une clé Sandbox sur /api-key, sans carte bancaire. Le serveur lit deux variables d’environnement, une seule est obligatoire :

FACTURX_API_KEY
Votre clé API (en-tête X-API-Key).
FACTURX_BASE_URL
Facultative depuis la 0.1.2 : la production (https://api.facturxapi.com) est l’hôte par défaut ; obligatoire en 0.1.1.

3. Les quatre outils exposés

Chaque description dit à l’agent quand appeler l’outil, ce qu’il renvoie et ce qu’il consomme. Le serveur indique aussi l’ordre : contrôle d’abord, conversion seulement quand le contrôle répond ready.

Outil Ce qu’il fait
facturx_dry_run

(invoice, validation_target?, output?)

 Contrôle le JSON de facture complet avant toute génération. Renvoie ready (vrai seulement quand generationReadiness.status vaut « ready »), le détail de ce qui bloque, request_id et idempotency_key.

Ce qu’il consomme : Aucune facture décomptée.

facturx_convert

(invoice, out_dir, validation_target?, output?, idempotency_key?)

 Génère factur-x.pdf (PDF/A-3 avec XML embarqué) et factur-x.xml dans out_dir. Renvoie chemins, tailles, SHA-256, la cible et son statut, et l’idempotency_key.

Ce qu’il consomme : 1 facture du quota. Relancé avec la même idempotency_key après une coupure, l’appel n’est pas facturé deux fois.

facturx_validate

(file_path, validation_target?)

 Valide un Factur-X PDF ou un XML CII présent sur le disque. Renvoie valid, validationStatus, le profil, la cible et les dix premières erreurs.

Ce qu’il consomme : 1 facture du quota par rapport rendu, que le fichier soit valide ou non. Un appel refusé (clé, format, quota atteint) ou interrompu par une erreur technique de notre côté n’est pas décompté.

facturx_explain_error

(code_or_rule)

 Donne, pour une règle EN16931 ou des règles françaises (BR-CO-15…), un terme métier (BT-1…) ou un chemin JSON (totals.gross…), les champs concernés, BT, règle, XPath CII, exigence, lus dans le contrat d’intégration public.

Ce qu’il consomme : Sans clé API.

4. Une session d’agent, du JSON ERP au PDF vérifié

Les réponses des outils ci-dessous sont celles d’une session enregistrée le 6 novembre 2026 sur l’environnement de test (valeurs exactes, sorties abrégées).

  1. Vous (demande d’exemple)

    Voici l’export JSON de la facture X08-DEMO-001 de notre ERP. Produis le Factur-X EN16931 dans ./out et vérifie-le.

  2. Agent → facturx_explain_error

    { "code_or_rule": "BR-CO-15" }

    → 3 champs liés : totals.net (BT-109), totals.tax (BT-110), totals.gross (BT-112), lus dans GET /api/v1/integration-contract.

    BR-CO-15 : total TTC = total HT + total TVA. L’agent contrôle ces trois montants de l’export avant d’appeler l’API.

  3. Agent → facturx_dry_run

    Extrait abrégé, non exécutable

    { "invoice": { …facture X08-DEMO-001… } }

    → ready: true — generationReadiness « ready », 0 donnée bloquante.

  4. Agent → facturx_convert

    Extrait abrégé, non exécutable

    { "invoice": { … }, "out_dir": "out" }

    → Cible en16931 vérifiée. out/factur-x.xml (4 584 octets, SHA-256 f332975e…e03c) et out/factur-x.pdf (20 624 octets).

  5. Agent → facturx_validate

    { "file_path": "out/factur-x.pdf", "validation_target": "en16931" }

    → valid: true — profil EN16931, 0 erreur.

  6. Agent

    Factur-X généré dans out/factur-x.pdf : profil EN16931, cible vérifiée, 0 erreur à la validation.

Quand l’export ERP contient une erreur

  • Quand un appel échoue, l’agent reçoit l’erreur de l’API telle quelle : status, code, api_message, request_id et idempotency_key. Il n’a pas à deviner ce qui s’est passé.
  • Pour une règle (BR-…) ou un terme (BT-…), facturx_explain_error lui donne le champ JSON à corriger, son BT et, quand le contrat le donne, son emplacement dans le XML CII.
  • Il corrige le JSON, relance facturx_dry_run, et ne lance facturx_convert que lorsque ready vaut true.

Pour aller plus loin