invoice_data JSON : convertir un PDF ERP en Factur-X sans réécrire l'export

Un éditeur ERP n’a pas toujours besoin de réécrire son export facture pour produire un Factur-X conforme. Dans FacturX API, le /convert peut recevoir deux choses : le PDF déjà produit par l’ERP et un objet invoice_data JSON avec les champs métier que l’ERP connaît.

L’API combine les deux pour produire un document Factur-X conforme EN16931 : PDF/A-3, XML CII embarqué, profil cohérent, validation avant/après.

En bref

• Le PDF existant reste la base lisible de la facture.
• invoice_data JSON transporte les données métier nécessaires au XML CII.
• L’ERP n’a pas besoin de générer lui-même tout le XML EN16931.
• Les champs manquants détectés par le scanner peuvent souvent être fournis dans invoice_data.
• C’est le chemin le plus court pour intégrer FacturX API dans un ERP sectoriel ou un logiciel métier à flux facturants.

Le problème : l’ERP sait facturer, mais pas forcément produire EN16931

Un ERP métier sait déjà produire une facture lisible :

• numéro ;
• client ;
• lignes ;
• prix ;
• TVA ;
• échéance ;
• PDF imprimable ;
• avoirs ou situations selon le métier.

Mais produire un Factur-X conforme ajoute une couche technique :

• XML CII D22B ;
• Business Terms EN16931 ;
• profils Factur-X ;
• PDF/A-3 ;
• XMP ;
• AFRelationship ;
• règles XSD et Schematron ;
• codelists.

Construire cette couche dans chaque ERP prend du temps et crée une dette de maintenance. invoice_data JSON sert à séparer les responsabilités : l’ERP fournit les données qu’il maîtrise, FacturX API construit le document conforme.

Architecture de l’appel /convert

ERP
  ├─ produit le PDF existant
  └─ expose les données métier en JSON
        ↓
POST /api/v1/convert
  ├─ [email protected]
  └─ invoice_data={...}
        ↓
Factur-X PDF/A-3 + XML CII EN16931

Le PDF fournit la présentation humaine. Le JSON fournit les champs structurés. L’API produit le XML CII, l’embarque, applique les métadonnées attendues et revalide.

Exemple minimal

curl -X POST https://api.facturxapi.com/api/v1/convert \
  -H "Authorization: Bearer $FACTURX_API_KEY" \
  -F "[email protected]" \
  -F 'invoice_data={
    "invoice_number": "FAC-2026-0042",
    "issue_date": "2026-04-28",
    "invoice_type": "380",
    "currency": "EUR",
    "seller": {
      "name": "ERP Métier SAS",
      "siret": "12345678900012",
      "vat_id": "FR12345678901",
      "address": {
        "street": "12 rue des Éditeurs",
        "postal_code": "75002",
        "city": "Paris",
        "country": "FR"
      }
    },
    "buyer": {
      "name": "Client B2B",
      "siret": "98765432100019",
      "address": {
        "street": "8 avenue du Commerce",
        "postal_code": "69002",
        "city": "Lyon",
        "country": "FR"
      }
    },
    "totals": {
      "net": "1000.00",
      "tax": "200.00",
      "gross": "1200.00",
      "due": "1200.00"
    },
    "tax_breakdown": [
      {
        "rate": "20.00",
        "category": "S",
        "base": "1000.00",
        "amount": "200.00"
      }
    ],
    "line_items": [
      {
        "number": "1",
        "description": "Prestation mensuelle",
        "quantity": "1",
        "unit": "C62",
        "unit_price": "1000.00",
        "net_amount": "1000.00",
        "vat_category": "S",
        "vat_rate": "20.00"
      }
    ],
    "payment": {
      "due_date": "2026-05-28",
      "terms": "Paiement à 30 jours",
      "iban": "FR7630006000011234567890189"
    }
  }'

Le modèle mental reste stable : le PDF n’est pas le seul input. Les données ERP peuvent arriver séparément, avec les totaux, la ventilation TVA et les lignes déjà structurés côté logiciel métier.

Quels champs mettre dans invoice_data

Priorisez les champs que le scanner ou la validation signalent comme manquants.

À lire ensuite : Champs obligatoires EN16931 / Factur-X : mapping ERP → XML.

Ce que invoice_data ne doit pas devenir

invoice_data n’est pas une zone pour deviner des informations absentes.

Ne mettez pas :

• des montants recalculés à la main sans lien avec l’ERP ;
• un SIRET supposé ;
• une catégorie TVA choisie depuis un libellé ambigu ;
• des lignes qui ne correspondent pas au PDF ;
• un IBAN générique ;
• une date inventée pour passer une règle.

Le but est de transmettre les données métier fiables. Si le PDF et le JSON divergent, la facture doit être corrigée à la source ou traitée comme un cas rare.

Comment utiliser le scanner pour préparer le JSON

Workflow recommandé :

1. Déposer une facture dans /scan.
2. Lire les erreurs classées “ERP complète”.
3. Mapper chaque champ vers une donnée disponible dans l’ERP.
4. Construire invoice_data.
5. Appeler /convert.
6. Revalider le Factur-X produit.
7. Ajouter le cas comme fixture CI.

Ce workflow évite de partir d’un schéma théorique de 160+ Business Terms. Vous complétez d’abord ce qui manque réellement dans vos fichiers.

Pourquoi c’est important pour les ERP sectoriels

Un ERP BTP, auto, nautisme, médico-social ou industrie peut avoir une logique de facture très spécifique : situations, retenues, autoliquidation, acomptes, articles composites, frais annexes.

L’erreur serait de forcer chaque ERP à adopter d’un coup un générateur Factur-X complet. Une approche plus réaliste :

• garder le PDF métier existant ;
• extraire les données déjà disponibles ;
• fournir ces données en JSON ;
• laisser le moteur produire et vérifier la couche EN16931.

Le résultat est plus rapide à intégrer et plus facile à maintenir quand les artefacts EN16931 ou Factur-X évoluent.

Articles liés

• Convertir une facture PDF en Factur-X 1.08 conforme
• Données ERP → Factur-X CII : mapper JSON vers XML EN16931
• Intégrer la conformité Factur-X dans votre ERP en 3 jours
• Moteur de réparation EN16931 vs validateur Factur-X