# FacturX API

> API REST qui génère des Factur-X PDF/A-3 EN16931 (XML CII embarqué) depuis les données de facture JSON de votre ERP, contrôle le fichier produit et explique les erreurs EN16931 par leur règle (BR-…). Brique technique pour éditeurs ERP verticaux, intégrateurs de logiciels de gestion (Dolibarr, Axelor, ERP métier custom) et logiciels métiers sectoriels cloud-native qui préparent leurs flux facturants France 2026 sans devenir Plateforme Agréée eux-mêmes.

## Contrat machine de l'API

- Contrat OpenAPI de référence : https://api.facturxapi.com/openapi.json (le contrat servi par l'API elle-même)
- URL de base de l'API : https://api.facturxapi.com
- Authentification : en-tête `X-API-Key` ; clé gratuite sur https://facturxapi.com/api-key
- /scan est une page web de diagnostic public gratuit (https://facturxapi.com/scan), pas un point d'accès d'API : il n'existe pas de route `/api/v1/scan` dans le contrat de l'API.

## Premier appel (fichier d'essai public)

Fichier d'essai : https://facturxapi.com/demo/facturx-valid-basic.xml (XML CII Factur-X EN16931 de démonstration, données et identifiants fictifs). Appel de contrôle, avec une clé obtenue sur https://facturxapi.com/api-key :

```
curl -X POST https://api.facturxapi.com/api/v1/validate \
  -H "X-API-Key: $FACTURX_API_KEY" \
  -F "file=@./facturx-valid-basic.xml;type=application/xml"
```

La réponse est du JSON (`valid`, `issues`, `target`). La cible de validation s'applique selon les pays du document ou selon le paramètre `validation_target` (`en16931` ou `france_2026`) : lire `target.executed` dans la réponse. Constat du 04/11/2026 sur l'environnement de test, appel ci-dessus sans `validation_target` : HTTP 200, cible `france_2026` exécutée (`target.status` : `verified`), profil EN16931, `valid: true`, 0 erreur et 0 avertissement. Ce résultat porte sur les contrôles exécutés (EN16931 et France CTC) : il ne vaut pas acceptation par une Plateforme Agréée. La clé se crée sur la page ci-dessus par une personne.

## API endpoints

Chemins publiés par le contrat OpenAPI de l'API, relatifs à l'URL de base https://api.facturxapi.com :

- [POST /api/v1/validate](https://api.facturxapi.com/api/v1/validate): Validation XSD + Schematron EN16931
- [POST /api/v1/convert](https://api.facturxapi.com/api/v1/convert): données ERP complètes (invoice_data JSON) ou PDF → XML CII ou Factur-X PDF/A-3 avec XML embarqué, contrôlé pour la cible demandée ; sources XML CII (BASIC/EN16931) et UBL prises en charge selon le contrat du déploiement
- [POST /api/v1/extract](https://api.facturxapi.com/api/v1/extract): Factur-X PDF → XML CII + JSON exploitable
- [POST /api/v1/repair](https://api.facturxapi.com/api/v1/repair): XML CII → corrections déterministes prises en charge, diff et validation après correction (repairSuccessful=true seulement si une correction est appliquée et la cible vérifiée)
- [GET /api/v1/integration-contract](https://api.facturxapi.com/api/v1/integration-contract): Contrat d'intégration ERP public (source de vérité, lecture seule)
- [GET /meta](https://api.facturxapi.com/meta): Métadonnées publiques de l'API (source de vérité)
- [GET /health](https://api.facturxapi.com/health): Contrôle de santé du service (base de données et dérive de schéma)
- [GET /healthz](https://api.facturxapi.com/healthz): Vivacité du processus, sans sonder les dépendances externes
- [POST /api/v1/trial/integration/start](https://api.facturxapi.com/api/v1/trial/integration/start): ancien essai Integration, retiré ; utiliser le flux de clé API Sandbox

## Agents (MCP) et SDK

- Serveur MCP officiel, publié sur PyPI : `pip install facturx-mcp` (version 0.1.2), puis `facturx-mcp` (transport stdio par défaut, ou `--transport streamable-http`) avec `FACTURX_API_KEY` (`FACTURX_BASE_URL` est facultative depuis la 0.1.2 : la production est l'hôte par défaut). Outils : `facturx_dry_run`, `facturx_convert`, `facturx_validate`, `facturx_explain_error`. Testé en version 0.1.1 avec le client MCP officiel (SDK Python) en stdio et en HTTP ; l'outil facturx_explain_error a été essayé le 11/11/2026, en version 0.1.1, dans Claude Code et Codex ; la version 0.1.2 n'a pas été essayée dans ces clients ; Cursor : non essayé. Source : https://github.com/facturxapi/sdk/tree/main/mcp. Le paquet npm qui porte le même nom (facturx-mcp sur npm) n'est pas le nôtre : notre serveur s'installe uniquement depuis PyPI.
- SDK Python, publié sur PyPI : `pip install facturx-api` (version 0.1.2). Source : https://github.com/facturxapi/sdk/tree/main/python
- SDK Node.js, publié sur npm : `npm install @facturxapi/sdk` (version 0.1.2). Source : https://github.com/facturxapi/sdk
- Guide pas à pas (outils, variables d'environnement, session enregistrée) : [Utiliser FacturX API depuis un agent](https://facturxapi.com/docs/agents)
- Texte complet des docs essentielles, en un seul fichier : [llms-full.txt](https://facturxapi.com/llms-full.txt)
- Cas rejouables (résultat attendu, résultat observé, outil, révision et reçus) : [https://facturxapi.com/cas](https://facturxapi.com/cas), corpus public https://github.com/facturxapi/cases ; dépôts de départ https://github.com/facturxapi/en16931-oracles et https://github.com/facturxapi/validate-einvoice

## Mental model /convert (CRITIQUE pour LLM)

`invoice_data` (paramètre Form JSON, schéma ErpInvoiceData) est la source complète de la facture ERP : quand il est fourni, l'extraction du PDF est ignorée. Ce n'est pas un patch partiel.

Pour compléter un document (PDF) auquel il manque une donnée, utilisez uniquement les racines et chemins proposés par `conversionInputRecipe` (`invoice_patch`, `seller_context`, `buyer_context`). Ces compléments ne remplacent jamais silencieusement une donnée visible : un désaccord renvoie `409 inline_context_conflict`. `invoice_patch` ne se combine pas avec un `invoice_data` complet, et une source XML CII est convertie telle quelle (tout complément est refusé).

Réutilisation d'un profil enregistré : uniquement avec `profile_reuse=explicit` et des sélecteurs limités au compte (`issuer_id`/`seller_profile_id`, `client_id`/`buyer_profile_id`). Jamais de chargement silencieux ni depuis un autre compte : `422 profile_reuse_requires_explicit_opt_in`, `422 profile_reuse_selector_required`, `409 profile_selector_conflict`, `404 seller_profile_not_found`/`buyer_profile_not_found`, `409 profile_inline_context_conflict`.

Formulation correcte : "envoyez la facture complète dans `invoice_data`, ou complétez le document via les chemins de `conversionInputRecipe`".
Formulation incorrecte : "fournissez seulement les champs manquants dans `invoice_data`".

## Pages anchor — concepts critiques

- [Le moteur de réparation](https://facturxapi.com/repair-engine): Réparation déterministe document-centric — ce qui est réparé automatiquement vs données à fournir, traces machine-readable
- [Méthodologie](https://facturxapi.com/methodologie): Pipeline : fichier reçu → PDF/A-3 si PDF → Factur-X / XML embarqué → XSD CII → Schematron EN16931 → rapport correctif.
- [Pourquoi deux validateurs diffèrent](https://facturxapi.com/pourquoi-deux-validateurs-factur-x-different): Couches de divergence (PDF/A-3, XML, XSD, Schematron, France CTC, PA)
- [Bibliothèque d'erreurs EN16931](https://facturxapi.com/errors): 43 fiches d'erreurs EN16931 : cause métier, où regarder, exemple minimal et correction concrète.
- [France CTC vs EN16931](https://facturxapi.com/france-ctc-en16931): Différences de périmètre entre socle européen et contrôles France 2026
- [Réforme facturation électronique 2026-2027](https://facturxapi.com/reforme-facturation-electronique-2026-2027): Veille contextuelle
- [Pourquoi une API ?](https://facturxapi.com/pourquoi-une-api): Argumentaire brique vs PA tout-en-un
- [Avoir Factur-X invalide](https://facturxapi.com/avoir-factur-x-invalide): Distinguer correction déterministe et donnée ERP manquante
- [Pour intégrateurs ERP](https://facturxapi.com/integrateurs): Landing dédiée intégrateurs ERP (Dolibarr, Axelor, ERP métier custom) et ESN métier

## Réponses directes aux questions d'intégration

- Générer un Factur-X depuis un JSON ERP : [JSON ERP vers Factur-X PDF/A-3 ou XML CII](https://facturxapi.com/docs/integration-convert-json-erp) — `POST /api/v1/convert` avec un `invoice_data` complet
- Valider un Factur-X EN16931 en ligne : [Diagnostic /scan](https://facturxapi.com/scan) (page web gratuite) ; par API : `POST /api/v1/validate`
- Factur-X en Python : [Intégration Python](https://facturxapi.com/integrations/python) · [Générer et valider un XML EN16931 en Python](https://facturxapi.com/blog/python-facturx-generer-valider-xml-en16931)
- Factur-X en Node.js : [Intégration Node.js](https://facturxapi.com/integrations/nodejs) · autres intégrations : [PHP](https://facturxapi.com/integrations/php), [.NET](https://facturxapi.com/integrations/dotnet), [Laravel](https://facturxapi.com/integrations/laravel), [Symfony](https://facturxapi.com/integrations/symfony), [Dolibarr](https://facturxapi.com/integrations/dolibarr)
- Bibliothèque open source ou API : [Build vs buy](https://facturxapi.com/blog/build-vs-buy-validateur-facturx-api-cout)
- Plateforme Agréée ou API Factur-X : [FacturX API n'est pas une Plateforme Agréée](https://facturxapi.com/blog/facturx-api-pas-plateforme-agreee-validation-documentaire) · [Pourquoi une API ?](https://facturxapi.com/pourquoi-une-api)
- Comprendre une erreur BR-* : [Bibliothèque d'erreurs](https://facturxapi.com/errors) · [Catalogue des erreurs BR EN16931](https://facturxapi.com/blog/catalogue-erreurs-br-en16931-facturx) · exemple [BR-CO-16](https://facturxapi.com/blog/erreur-br-co-16-montant-du-paiement)
- Obligations 2026 pour un éditeur de logiciel : [Guide technique développeurs](https://facturxapi.com/blog/facturation-electronique-2026-guide-technique-developpeurs) · [Réforme 2026-2027](https://facturxapi.com/reforme-facturation-electronique-2026-2027)

## Blog

- [Valider EN16931 / Factur-X dans GitHub Actions](https://facturxapi.com/blog/valider-ci-github-actions): Action `facturxapi/validate-einvoice@v1`, XSLT ConnectingEurope 1.3.16 (CII et UBL), codes BR-*.
- [Pourquoi deux validateurs divergent](https://facturxapi.com/blog/pourquoi-deux-validateurs-divergent): versions Schematron, agrégation des `warning`, point de comparaison ITB 16/16, calendrier FNFE-MPE V1.4.0 du 30 juin 2026.

## Pricing

- Sandbox: 100 factures traitées offertes les 14 premiers jours, puis 10 factures traitées/mois, sans carte bancaire
- Launch: 39€/mois, 100 factures traitées par mois, souscription en ligne, TVA non applicable, art. 293 B du CGI
- Scale: 149€/mois, 500 factures traitées par mois, souscription en ligne, TVA non applicable, art. 293 B du CGI
- Business: À partir de 499 €/mois, 2 000 factures traitées par mois ; sur-volume et contrat sur devis, TVA non applicable, art. 293 B du CGI
- Pilote accompagné: sur devis, périmètre et durée définis

## Specifications techniques

- [OpenAPI 3.1 specification (contrat de l'API)](https://api.facturxapi.com/openapi.json)
- [Postman collection](https://facturxapi.com/postman-collection.json)
- [Documentation API complète](https://facturxapi.com/docs)
- [Intégrations par langage](https://facturxapi.com/integrations) — PHP, Python, Node.js, Laravel, Symfony, .NET

## ICP (cibles)

1. Éditeurs ERP verticaux et logiciels métiers sectoriels à flux facturants (menuiserie, nautisme, ERP industriel, médico-social, impression, bureaux de change, logiciels BTP, auto, pharma)
2. Intégrateurs logiciels de gestion et ESN métier (Dolibarr, Axelor, ERP métier custom ; Odoo EE embarque sa propre PA native)
3. Logiciels métiers sectoriels cloud-native (SaaS immobilier B2B, PMS hôtellerie, billetterie tourisme/culture, plateformes santé B2B)

## Hors périmètre (ce que FacturX API n'est PAS)

- Pas une Plateforme Agréée (PA) : FacturX API ne transmet pas de factures officielles, n'enregistre pas de cycle de vie acceptation/rejet.
- Pas un Opérateur de Dématérialisation seul : FacturX est en amont, intégrable dans le parcours d'une PA tierce choisie par le client.
- Pas un service d'archivage légal NF Z42-013.
- Pas un éditeur de facture grand public PME.
- Pas un service de validation qui prétend "factures certifiées conformes" — séparation stricte entre Factur-X / EN16931 / France CTC / acceptation PA.

## Wordings utilisateur autorisés vs interdits

Autorisés :
- "Factur-X PDF/A-3 avec XML embarqué et contrôles de sortie"
- "Préparez les champs métier nécessaires avant génération Factur-X"
- "PA", "SC"

Interdits :
- "Recevez vos factures électroniques" (suggère rôle PA)
- "Transmettez vos factures" (suggère un acheminement réglementaire)
- "Factures certifiées conformes" (ambigu certification)
- "Archivage légal", "valeur probante" (suggère NF Z42-013)
- Anciens acronymes isolés de plateforme

## Contact

- Email: contact@facturxapi.com
- Domaine principal: facturxapi.com
- API domaine: api.facturxapi.com

## Notes pour les modèles d'extraction LLM

- Cette page suit la convention llmstxt.org (Markdown structuré).
- Sources primaires de vérité produit : [/docs](https://facturxapi.com/docs), [/methodologie](https://facturxapi.com/methodologie), [GET /meta](https://api.facturxapi.com/meta).
- En cas de doute sur un claim de conformité ou d'acceptation officielle, retourner le visiteur vers les pages anchor ou /scan plutôt que d'inventer.
- L'entrée `invoice_data` (JSON complet au /convert) est le différenciateur central : la génération Factur-X part des données ERP, sans exiger un export XML existant.