invoice_data JSON : données ERP et génération Factur-X

Un éditeur ERP peut déléguer la génération XML CII sans perdre la maîtrise de ses données de facturation. Avec invoice_data JSON complet, /convert utilise le JSON comme source structurée de la facture : le PDF transmis n’est pas analysé pour compléter ces données.

Pour une sortie facturx_pdfa3, l’API rend le PDF lisible à partir de ces mêmes données, puis construit le conteneur et exécute les contrôles demandés. La présentation du PDF ERP existant n’est donc pas conservée par cette voie. Une sortie xml_cii fournit le XML sans porteur PDF. Le résultat atteste ces contrôles uniquement ; il ne vaut ni transmission ni acceptation par une PA ou une solution compatible (SC).

En bref

• Le JSON complet fournit la facture structurée ; il ne complète pas automatiquement un PDF analysé.
• Le XML CII et le rendu PDF proviennent de la même source invoice_data.
• L’ERP n’a pas besoin de générer lui-même tout le XML EN16931.
• Pour un complément ciblé, utilisez les chemins invoice_patch, seller_context ou buyer_context indiqués par le diagnostic, selon le champ concerné.
• Le choix entre source complète et complément ciblé dépend des données fiables déjà disponibles et du résultat demandé.

Ce billet explique le principe. Le flux pas à pas — exemples curl, champs invoice_data acceptés, réponses à gérer, erreurs et FAQ — est documenté dans le guide d’intégration /convert avec JSON ERP.

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 puis expose le résultat des contrôles exécutés.

Architecture de l’appel /convert

ERP
  ├─ fournit un fichier dans la requête
  └─ expose la facture complète en JSON
        ↓
POST /api/v1/convert
  ├─ file=@./facture.pdf
  └─ invoice_data={facture complète}
        ↓
JSON source → rendu PDF + XML CII
        ↓
Assemblage Factur-X PDF/A-3 puis contrôles

Avec invoice_data complet, le moteur saute l’analyse du PDF fourni. Il produit le XML CII et le rendu lisible à partir du JSON, assemble le PDF/A-3 puis expose le résultat de revalidation. Si vous devez conserver une présentation particulière, vérifiez le rendu obtenu sur vos fichiers avant intégration.

Exemple de requête à adapter à votre facture

Les identités ci-dessous sont fictives : elles illustrent les familles de champs et ne constituent pas une facture valide à transmettre. Utilisez les données réelles de votre ERP et vérifiez le contrat des champs dans le guide d’intégration.

curl -X POST https://api.facturxapi.com/api/v1/convert \
  -H "Authorization: Bearer $FACTURX_API_KEY" \
  -F "file=@./facture-erp.pdf" \
  -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

invoice_data doit décrire la facture complète, y compris les lignes, la ventilation TVA et les totaux. Ne lui transmettez pas seulement les champs signalés comme manquants : les compléments ciblés passent par les chemins dédiés que le diagnostic indique.

À 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 à l’opération facturée ;
• 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 ERP et le JSON divergent, vérifiez la facture à la source avant génération ; l’analyse du PDF étant sautée avec invoice_data, cet appel ne prouve pas leur concordance.

Comment utiliser le scanner pour préparer le JSON

Workflow recommandé :

1. Déposer une facture dans /scan.
2. Lire les contrôles exécutés et les actions précises proposées par le diagnostic.
3. Vérifier quelles données fiables sont déjà présentes et lesquelles manquent réellement.
4. Choisir un complément ciblé au chemin indiqué, ou fournir une facture complète via invoice_data si vous reconstruisez le document.
5. Appeler /convert.
6. Revalider le Factur-X produit.
7. Ajouter le cas comme fixture CI.

Un complément ciblé conserve les informations déjà établies par le diagnostic. Une reconstruction avec invoice_data demande, elle, l’ensemble des données de la facture. Testez ces deux chemins séparément dans votre intégration.

Pour explorer la structure du résultat, les exemples Factur-X téléchargeables proposent un PDF de démonstration et son XML CII BASIC. Ils servent à inspecter le conteneur et les champs ; construisez vos fixtures de conversion avec vos propres cas métier et le profil attendu.

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 :

• conserver la maîtrise des données dans l’ERP ;
• extraire les données déjà disponibles ;
• fournir la facture complète en JSON lorsque ce mode de génération convient ;
• laisser le moteur produire et vérifier la couche EN16931.

Cette séparation évite de développer le générateur XML dans chaque ERP. L’intégration doit toujours tester le rendu, les cas métier couverts et le résultat des contrôles après conversion.

Articles liés

• Convertir une facture PDF en Factur-X 1.08 contrôlé
• 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