Intégrer Factur-X dans votre ERP en 3 jours : retour d'expérience API

En bref

• Retour d’expérience : un éditeur ERP BTP a intégré la conformité Factur-X en 3 jours-homme d’un développeur senior.
• Mode ERP-assisted (invoice_data JSON) : les données sont déjà structurées dans l’ERP, pas d’OCR nécessaire.
• Jour 1 : mapping ERP → JSON invoice_data. Jour 2 : intégration API + gestion d’erreurs. Jour 3 : tests, idempotence, CI/CD.
• Environ cinq cents factures par mois en production.
• Prérequis : ERP avec données exportables, développeur connaissant le modèle de données et les cas métier.

Un éditeur ERP spécialisé dans le BTP devait rendre ses factures conformes Factur-X avant l’échéance de la réforme. Le contexte : un logiciel métier mature, un pipeline PDF existant qu’il ne fallait pas réécrire, aucun expert XML ou PDF/A dans l’équipe, et ~500 factures par mois en production.

Ce retour d’expérience décrit un cas favorable : ERP déjà structuré avec données exportables, développeur senior, usage du mode ERP-assisted (invoice_data). Le temps d’intégration varie selon la maturité de vos données et la complexité de vos cas métier.

L’intégration via API a pris 3 jours-homme d’un développeur senior. Pas 3 jours calendaires pour un junior qui découvre EN16931 — 3 jours pleins d’un développeur qui connaissait le modèle de données de l’ERP et les cas métier BTP. Voici les étapes concrètes.

Jour 1 : le mapping ERP vers JSON

La première journée a été consacrée à un seul objectif : construire l’objet invoice_data attendu par l’API à partir des tables existantes de l’ERP.

Identifier les Business Terms

EN16931 définit des Business Terms (BT) numérotés : BT-1 pour le numéro de facture, BT-2 pour la date d’émission, BT-27 pour le nom du vendeur, etc. Le travail consiste à trouver, dans les tables de l’ERP, quelle colonne correspond à chaque BT obligatoire.

Pour un ERP BTP français, les champs fondamentaux existaient : numéro, date, SIRET, TVA intra, lignes de détail. L’essentiel du mapping s’est fait mécaniquement. Le guide complet est dans Données ERP vers Factur-X CII : mapper JSON vers XML EN16931.

Les points de friction réels

Trois transformations de format ont consommé du temps :

Le format de date. L’ERP stockait déjà les dates en ISO 8601 (2026-04-13). C’est le format attendu par invoice_data (issue_date, payment.due_date). Le moteur se charge ensuite de produire le format CII requis dans le XML.

Les identifiants fiscaux. Le SIRET (14 chiffres) devient seller.siret. Le numéro de TVA intracommunautaire (FR32123456789) devient seller.vat_id. L’ERP stockait les deux dans un même bloc “identifiants entreprise” — il a fallu les séparer explicitement.

Le code devise. L’ERP gérait la devise comme un libellé (“Euro”) plutôt qu’un code ISO 4217. Le remplacement par EUR dans le champ currency était immédiat, mais c’est le genre de détail qui fait échouer silencieusement la validation si on l’oublie.

Le cas spécifique BTP : l’autoliquidation

Lorsque les conditions de l’article 283, 2 nonies du CGI sont réunies pour des travaux immobiliers sous-traités, le sous-traitant facture hors taxe et le preneur autoliquide la TVA. Ce régime ne s’applique pas indistinctement à toutes les prestations BTP. Pour une opération effectivement soumise à l’autoliquidation, le mapping est :

• vat_category passe de S (Standard) à AE (Reverse Charge)
• vat_rate passe à 0
• Un motif textuel (BT-120) ou codé (BT-121), conformément à BR-AE-10. Exemple de texte dans vat_exemption_reason : "Autoliquidation - art. 283, 2 nonies du CGI"

Côté EN16931, le code d’exonération interopérable est VATEX-EU-AE. En complément, la facture française doit porter la mention “Autoliquidation” conformément au CGI. Les deux informations peuvent coexister dans le XML (BT-121 pour le code, BT-120 pour le texte).

L’ERP gérait déjà le flag “autoliquidation” — il a suffi de le traduire en code AE dans le JSON. Le code AE, les taux, les identifiants et la ventilation TVA doivent ensuite être contrôlés ensemble ; le seul flag ne prouve ni le régime fiscal applicable ni la validité du document. Les erreurs spécifiques sont documentées dans Les erreurs Factur-X qui bloquent vos factures BTP.

Bilan du jour 1 : une fonction d’extraction qui transforme un objet facture ERP en JSON invoice_data conforme.

Jour 2 : l’appel API et la gestion des erreurs

L’intégration HTTP proprement dite : appeler l’API, traiter les réponses, gérer les erreurs.

Premier appel

L’appel /api/v1/convert reçoit le PDF existant et le JSON invoice_data du jour 1. Pour la sortie facturx_pdfa3, il utilise ce PDF comme support visuel et produit le livrable lorsque les conditions du contrat sont remplies. Vérifier target.status, packagingPerformed et la présence effective du PDF dans le résultat. Le pipeline PDF de l’ERP peut être conservé ; le fichier retourné est transformé et n’est pas identique au fichier d’entrée. Les deux modes de conversion sont détaillés dans Convertir une facture PDF en Factur-X 1.08 contrôlé.

Premier appel avec une facture réelle : erreur insufficient_data. Le JSON ne contenait pas tous les champs conditionnellement obligatoires.

Les erreurs rencontrées en production

Deux types d’erreurs ont dominé les premiers tests :

insufficient_data — champs manquants. L’API valide le JSON en amont et signale les absences avant la génération XML. Champs manquants fréquents : buyer.address.country (obligatoire même sans adresse complète), au moins un identifiant vendeur parmi BT-29 (identifiant commercial), BT-30 (identifiant légal) ou BT-31 (identifiant TVA) doit être présent (règle BR-CO-26), si BT-115 est positif, une date d’échéance (payment.due_date, BT-9) ou des conditions de paiement (payment.terms, BT-20), selon BR-CO-25. Ces exigences doivent être contrôlées dans le document généré, même si le JSON a été accepté à l’entrée.

totals_mismatch — incohérence arithmétique. BR-CO-10 vérifie la somme des nets de lignes (BT-106) ; BR-CO-13 en déduit le total HT après remises et charges documentaires ; BR-CO-14 compare le total TVA à la somme des ventilations TVA. Les arrondis doivent être vérifiés selon la règle exécutée : toutes les règles ne partagent pas une tolérance universelle d’un centime.

Correction : vérifier les nets de lignes, les ventilations et les totaux avec les remises, charges, acomptes et arrondis applicables. Reprendre les montants comptables exacts ; ne pas modifier un montant uniquement pour faire disparaître un diagnostic.

Idempotency et retries

Pour reprendre une requête interrompue, réutiliser la même clé d’idempotence et le même payload dans le même périmètre d’authentification. Réutiliser la clé avec un autre payload ou sur l’autre endpoint /repair provoque un conflit 409. Ce mécanisme n’est pas une déduplication comptable permanente par numéro de facture. Exemple d’en-tête et de requête abrégée :

curl -X POST https://api.facturxapi.com/api/v1/convert \
  -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: INV-2026-04-0042" \
  -F "file=@./facture-0042.pdf" \
  -F 'invoice_data={"invoice_number":"INV-2026-04-0042",...}'

Bilan du jour 2 : un appel API fonctionnel, avec gestion des erreurs métier et réseau, testé sur une dizaine de factures représentatives.

Jour 3 : les cas spéciaux et la mise en production

Les variantes métier non testées au jour 2, puis la mise en production.

Avoirs (note de crédit)

Pour un avoir annulant une opération positive, l’exemple invoice_data utilise invoice_type: "381" avec des montants positifs. Le contrat d’entrée impose des totaux net, tax et gross non négatifs ; cette restriction de l’API n’est pas une règle universelle du XML CII. Le seul code 381 ne normalise pas les signes de l’ERP : vérifier le mapping, la référence à la facture d’origine, sa date lorsque requise et le document généré.

Multi-taux TVA

Un chantier de rénovation peut combiner 20% (gros oeuvre) et 10% (travaux d’amélioration, logement > 2 ans). Le JSON doit regrouper les lignes par taux dans le bloc tax_breakdown, avec un sous-total par catégorie. L’ERP calculait déjà ces sous-totaux — conversion directe.

Autoliquidation mixte

Le cas le plus subtil : un chantier où certaines lignes sont en autoliquidation (sous-traitance, AE) et d’autres en TVA standard (S). Chaque ligne porte son propre vat_category, et le tax_breakdown doit contenir une entrée pour chaque combinaison catégorie/taux rencontrée. L’erreur classique est de déclarer un tax_breakdown global unique quand les lignes sont hétérogènes.

Validation systématique avant envoi à la PA

Avant d’envoyer une facture à la Plateforme Agréée (PA, ex-PDP), le pipeline valide systématiquement le Factur-X généré via l’endpoint /validate. Cette étape détecte les écarts couverts par les contrôles effectivement exécutés avant transmission. Elle ne garantit pas l’acceptation par la PA ; les réserves du rapport et le retour réel de la plateforme restent à traiter. Pour les détails de la validation XSD et Schematron, voir Valider EN16931/Factur-X : XSD vs Schematron, erreurs BR-*.

Monitoring des premières semaines

L’éditeur a suivi les taux d’erreur sur les 4 premières semaines : factures traitées, succès première passe, erreurs par type. Ce monitoring a permis de détecter les cas de données ERP incomplètes (opérateur qui omet le code postal acheteur, par exemple) et de les corriger rapidement.

Résultat en production

Après 3 mois d’exploitation sur le parc client :

Les 5% d’échecs ne sont pas des bugs d’intégration mais des erreurs de saisie dans l’ERP : code postal manquant, numéro de TVA mal formaté, montant de ligne à zéro. L’API renvoie un message explicite, l’opérateur corrige et relance. Ces erreurs se concentrent sur les premières semaines d’utilisation par un nouvel opérateur, puis disparaissent.

Les prérequis pour reproduire ce résultat

Toute intégration ERP suit le même schéma si les prérequis sont remplis.

Votre ERP doit exposer les données comptables. Pas nécessairement via une API REST — une requête SQL sur les tables de facturation suffit. L’important : accéder aux données structurées (numéro, date, montants, lignes, identifiants fiscaux).

Vous devez connaître vos cas de TVA. Chaque combinaison correspond à un code vat_category : S (Standard), AE (autoliquidation), E (Exempt), Z (Zero rated). Cet inventaire est un prérequis au mapping.

Vous devez disposer d’un identifiant vendeur valide. Au moins un identifiant vendeur parmi BT-29 (identifiant commercial), BT-30 (identifiant légal) ou BT-31 (identifiant TVA) doit être présent (règle BR-CO-26). Pour une entreprise française, le couple SIRET + TVA intra est le plus robuste.

L’API prend en charge la génération et les contrôles techniques prévus par le contrat supporté. Vérifier la cible demandée et les contrôles réellement exécutés. Les données métier, les conditions fiscales, les réserves du rapport et l’acceptation PA ne sont pas déléguées par le seul appel API ; la durée d’intégration dépend de ces éléments.

Erreurs fréquentes et fiches de diagnostic

• BT-131 — Montant net de ligne — base quantity oubliée sur les prix au m²/lot
• BR-AE-05 — Autoliquidation — sous-traitance BTP
• BR-05 — Code devise — premier champ oublié en migration ERP
• Format date 102 — conversion ISO → yyyymmdd en sortie d’ERP
• Mapping ERP → JSON complet — guide de référence pour invoice_data

Les 22 fiches unitaires : catalogue complet des erreurs BR-*.

Et maintenant ?

curl -X POST https://api.facturxapi.com/api/v1/convert \
  -H "Authorization: Bearer VOTRE_CLE" \
  -F "file=@./facture.pdf"

Clé Sandbox : 100 factures traitées offertes les 14 premiers jours, puis 10 factures traitées/mois. Le scanner public reste gratuit et séparé du quota API. Obtenir une clé API.

Aller plus loin

• Données ERP vers Factur-X CII : mapper JSON vers XML EN16931 — le guide complet du mapping JSON, avec tous les champs, les cardinalités et les cas spéciaux
• Convertir une facture PDF en Factur-X 1.08 contrôlé — les deux modes de conversion (extraction PDF et données ERP), avec exemples curl, Python et Node.js
• Les erreurs Factur-X qui bloquent vos factures BTP — diagnostic et correction des erreurs spécifiques au BTP (autoliquidation, factures de situation, retenue de garantie)
• Valider EN16931/Factur-X : XSD vs Schematron, erreurs BR-* — comprendre les deux niveaux de validation et déboguer les erreurs
• Automatiser la validation Factur-X dans votre pipeline CI/CD — intégrer la validation dans un workflow automatisé pour les volumes importants
• Checklist développeur : préparer la réception obligatoire du 1er septembre 2026 — tout ce qu’il faut livrer avant l’échéance réglementaire