Technique

Corriger un XML CII Factur-X invalide : API de réparation

10 min de lecture Par FacturX API

Réparer un XML CII (Factur-X / EN16931) : dates, namespaces, schemeID de TVA, devises, unités ; décimales sur option. Validation avant/après et diff détaillé.

Comment corriger automatiquement un XML CII / Factur-X invalide sans risquer de casser autre chose ? L’endpoint /repair applique 6 règles de correction déterministes (dates, séparateur décimal sur demande, namespaces, schemeID de TVA, casse de la devise, unités) avec diff complet et validation avant/après. Les erreurs de FOND (catégorie TVA mal choisie, montant faux) restent à corriger dans l’ERP.

En bref

  • Endpoint : POST /api/v1/repair — input XML CII, output XML corrigé + diff détaillé + statut de validation avant/après.
  • Erreurs de format corrigées : dates ISO→yyyymmdd, namespaces CII :100, schemeID="VA" pour un numéro de TVA pris en charge, casse d’un code devise existant, unités UN/ECE prises en charge. Virgule→point : sur option seulement (do_not_modify_amounts=false).
  • Erreurs de fond NON corrigées : mauvaise catégorie TVA, montant incorrect, champ métier manquant → retour à l’ERP. L’API ne devine pas votre intention.
  • Sécurité : chaque modification est traçable dans le diff. Si une correction est ambiguë (pas de valeur par défaut applicable), le moteur ne touche pas au champ.
  • Combinaison /validate + /repair : d’abord valider pour diagnostiquer, puis réparer les erreurs de format, puis revalider pour confirmer la conformité.

Vous validez un XML CII et le rapport Schematron remonte 5, 10, 20 erreurs. Vous ouvrez le fichier, vous localisez la première, vous corrigez, vous revalidez. Une erreur de moins, quatre nouvelles — parce que la correction manuelle a cassé un namespace ou introduit un caractère invalide. Le cycle reprend.

Cet article traite de la réparation du XML structuré (le fichier CII embarqué dans un Factur-X). Il ne couvre pas la correction du conteneur PDF/A-3 ni des métadonnées XMP — ces aspects sont traités dans PDF/A-3 pour Factur-X : conformité et pièges.

Une part significative des erreurs rencontrées en pratique ne sont pas des problèmes de fond. Ce sont des problèmes de format : une date en ISO au lieu de AAAAMMJJ, une virgule au lieu d’un point décimal, un namespace oublié, un attribut schemeID absent.

L’API Repair applique les corrections de format déterministes listées ci-dessous, avec un diff complet de chaque modification et une validation avant/après qui indique si la cible demandée est vérifiée une fois la correction appliquée. Chaque règle de réparation est documentée, chaque changement est traçable.

Pour les erreurs BR-* et leurs causes racines, voir Catalogue des erreurs BR-* EN16931.

Quelles erreurs sont réparables automatiquement ?

Le moteur de réparation applique six règles publiques, chacune identifiée par un code R0xx ; la correction est déterministe (même entrée, même sortie). R002 (séparateur décimal) est désactivée par défaut : elle exige do_not_modify_amounts=false. R006 n’écrit schemeID="VA" que pour un numéro de TVA pris en charge ; une valeur ambiguë produit UNDETERMINED_SCHEME_ID sans aucune modification. Aucune valeur par défaut n’est inventée : si la correction est ambiguë, le moteur ne touche pas au champ.

Les règles R003 et R004 existent en interne mais ne sont pas exposées publiquement dans cette version de l’API.

R001 — Format de date (2024-01-15 vers 20240115)

CII exige le format format="102" pour les dates, ce qui correspond à AAAAMMJJ sur 8 chiffres sans séparateur. Les ERP exportent presque toujours en ISO 8601 (2024-01-15), en format européen slash (15/01/2024), ou en format européen point (15.01.2024).

XPath concernés : ram:IssueDateTime, ram:DueDateDateTime, ram:OccurrenceDateTime, ram:BillingSpecifiedPeriod/ram:StartDateTime, ram:BillingSpecifiedPeriod/ram:EndDateTime.

Avant :

<ram:IssueDateTime>
  <udt:DateTimeString format="102">2024-01-15</udt:DateTimeString>
</ram:IssueDateTime>

Après :

<ram:IssueDateTime>
  <udt:DateTimeString format="102">20240115</udt:DateTimeString>
</ram:IssueDateTime>

Le format format="102" déclare explicitement que la valeur est au format AAAAMMJJ. Un validateur Schematron qui trouve 2024-01-15 avec format="102" va rejeter le document : la valeur ne correspond pas au format déclaré. R001 supprime les tirets, les slashs et les points, et réordonne les composants si nécessaire (DD/MM/YYYY vers YYYYMMDD).

R002 — Séparateur décimal (100,50 vers 100.50)

CII utilise le point comme séparateur décimal, conformément à la représentation XML standard des nombres. Les ERP français et allemands utilisent la virgule. C’est l’une des erreurs les plus fréquentes dans les exports XML depuis des systèmes localisés.

Avant :

<ram:GrandTotalAmount>1 234,56</ram:GrandTotalAmount>

Après :

<ram:GrandTotalAmount>1234.56</ram:GrandTotalAmount>

R002 traite aussi les séparateurs de milliers européens : 1.234,56 (point pour les milliers, virgule pour les décimales) devient 1234.56.

Cette règle est contrôlée par la contrainte do_not_modify_amounts. Par défaut, cette contrainte est à true — les montants ne sont pas modifiés. C’est une protection délibérée : changer un séparateur décimal change potentiellement la valeur financière du document. Pour activer R002, vous devez explicitement passer do_not_modify_amounts: false dans les contraintes.

R005 — Préfixes et namespaces XML

Un XML CII Factur-X utilise typiquement quatre namespaces déclarés sur l’élément racine :

<rsm:CrossIndustryInvoice
  xmlns:rsm="urn:un:unece:uncefact:data:standard:CrossIndustryInvoice:100"
  xmlns:ram="urn:un:unece:uncefact:data:standard:ReusableAggregateBusinessInformationEntity:100"
  xmlns:qdt="urn:un:unece:uncefact:data:standard:QualifiedDataType:100"
  xmlns:udt="urn:un:unece:uncefact:data:standard:UnqualifiedDataType:100">

Les générateurs XML maison oublient fréquemment qdt: ou udt:, ou déclarent les URN avec une faute de frappe. R005 vérifie chaque namespace attendu et corrige les déclarations manquantes ou erronées.

R006 — Attributs schemeID manquants

Certains éléments CII exigent un attribut schemeID pour identifier le système d’identification utilisé. Sans cet attribut, le validateur Schematron rejette le document.

Avant :

<ram:SpecifiedTaxRegistration>
  <ram:ID>FR12345678901</ram:ID>
</ram:SpecifiedTaxRegistration>

Après :

<ram:SpecifiedTaxRegistration>
  <ram:ID schemeID="VA">FR12345678901</ram:ID>
</ram:SpecifiedTaxRegistration>

R006 pose schemeID="VA" sur un SpecifiedTaxRegistration/ID seulement quand la valeur a la forme d’un numéro de TVA ; il ne corrige jamais la valeur. Il ne devine pas le schéma d’un ram:GlobalID (SIRET, GLN, DUNS…) : la réponse signale UNDETERMINED_SCHEME_ID sans rien modifier, et la correction se fait dans votre système source.

R007 — Casse du code devise (eur vers EUR)

ISO 4217 exige des codes devise en majuscules. Un eur minuscule est techniquement invalide et sera rejeté par les règles BR-CL-* du Schematron.

Avant :

<ram:InvoiceCurrencyCode>eur</ram:InvoiceCurrencyCode>

Après :

<ram:InvoiceCurrencyCode>EUR</ram:InvoiceCurrencyCode>

R007 normalise aussi l’attribut currencyID sur les montants de TVA (ram:TaxTotalAmount).

R009 — Code unité de quantité (For vers C62)

Les quantités déclarent leur unité par un code UN/ECE (unitCode). R009 normalise les codes pris en charge, par exemple For vers C62 (« unité »). Les autres codes ne sont pas devinés : la validation continue de les signaler.

Avant :

<ram:BilledQuantity unitCode="For">2</ram:BilledQuantity>

Après :

<ram:BilledQuantity unitCode="C62">2</ram:BilledQuantity>

Pas de structure vide ajoutée. Le contrat public exclut la création d’un ApplicableHeaderTradeDelivery vide et toute donnée métier manquante. Si le validateur exige un élément absent, ajoutez-le dans votre système source.

Le workflow en 3 phases

Le moteur de réparation ne modifie pas le XML “à l’aveugle”. Il suit un workflow en trois phases qui garantit la traçabilité de chaque modification :

Phase 1 — Validation AVANT. Le XML original est validé (XSD + Schematron). Le rapport capture l’état initial : nombre d’erreurs, codes BR-* déclenchés, sévérités.

Phase 2 — Application des règles. Les règles publiées (R001, R002, R005, R006, R007, R009) sont appliquées dans un ordre déterministe. Chaque modification est enregistrée dans un DiffItem avec le XPath de l’élément modifié, la valeur avant, la valeur après, et le code de la règle appliquée.

Phase 3 — Validation APRES. Le XML réparé est revalidé avec les mêmes artefacts. Le rapport final permet de comparer : combien d’erreurs avant, combien après, lesquelles ont été corrigées.

Le résultat inclut les deux rapports de validation et le diff complet. Vous pouvez vérifier exactement ce qui a changé, pourquoi, et si la conformité a progressé.

Utilisation de l’API

Appel simple

curl -X POST https://api.facturxapi.com/api/v1/repair \
  -H "X-API-Key: votre-cle-api" \
  -F "file=@./facture.xml"

Avec contraintes

curl -X POST https://api.facturxapi.com/api/v1/repair \
  -H "X-API-Key: votre-cle-api" \
  -F "file=@./facture.xml" \
  -F 'constraints={"max_changes_allowed":10,"do_not_modify_amounts":false}'

Réponse type

{
  "durationMs": 142,
  "repaired_xml": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4...",
  "diff_summary": [
    {
      "code": "format_corrected",
      "path": "/rsm:CrossIndustryInvoice/rsm:ExchangedDocument/ram:IssueDateTime/udt:DateTimeString",
      "message": "Format de date corrige de '2024-01-15' vers '20240115'",
      "beforeValue": "2024-01-15",
      "afterValue": "20240115",
      "ruleReference": "R001",
      "changeCategory": "correction"
    },
    {
      "code": "attribute_added",
      "path": "/rsm:CrossIndustryInvoice/.../ram:SpecifiedTaxRegistration/ram:ID/@schemeID",
      "message": "Attribut schemeID='VA' manquant ajoute",
      "afterValue": "VA",
      "ruleReference": "R006",
      "changeCategory": "correction"
    },
    {
      "code": "format_corrected",
      "path": "/rsm:CrossIndustryInvoice/.../ram:InvoiceCurrencyCode",
      "message": "Casse du code devise corrigee de 'eur' vers 'EUR'",
      "beforeValue": "eur",
      "afterValue": "EUR",
      "ruleReference": "R007",
      "changeCategory": "normalization"
    }
  ],
  "validation_before": {
    "valid": false,
    "summary": { "errorCount": 3, "warningCount": 0 }
  },
  "validation_after": {
    "valid": true,
    "summary": { "errorCount": 0, "warningCount": 0 }
  }
}

Le champ repaired_xml contient le XML réparé encodé en base64. Décodez-le seulement quand repairSuccessful est true et que la cible demandée est vérifiée ; vous obtenez alors le XML corrigé à ré-embarquer dans votre pipeline PDF/A-3.

Exemple Python

import base64
import requests

API_URL = "https://api.facturxapi.com/api/v1/repair"
API_KEY = "votre-cle-api"

with open("facture.xml", "rb") as f:
    response = requests.post(
        API_URL,
        headers={"X-API-Key": API_KEY},
        files={"file": ("facture.xml", f, "application/xml")},
        data={"constraints": '{"do_not_modify_amounts": false}'},
    )

result = response.json()

# Afficher les corrections appliquées
for diff in result["diff_summary"]:
    print(f"[{diff['ruleReference']}] {diff['message']}")

def target_verified(target):
    return (
        target
        and target.get("requested") == target.get("executed")
        and target.get("status") == "verified"
    )

# Sauvegarder le XML repare uniquement si la cible demandee est verifiee
if (
    result.get("repairSuccessful") is True
    and target_verified(result.get("target"))
    and target_verified(result.get("validation_after", {}).get("target"))
):
    repaired_xml = base64.b64decode(result["repaired_xml"])
    with open("facture_réparée.xml", "wb") as out:
        out.write(repaired_xml)
    print(f"XML réparé sauvegardé ({len(repaired_xml)} octets)")
else:
    remaining = result["validation_after"]["summary"]["errorCount"]
    print(f"Reparation partielle : {remaining} erreur(s) restante(s)")

Les contraintes de sécurité

L’API Repair accepte un objet JSON constraints qui contrôle le comportement du moteur :

ContrainteDéfautRôle
max_changes_allowed50Nombre maximum de modifications autorisées. Au-delà, l’API retourne une erreur 422.
do_not_modify_amountstrueProtège les montants financiers. Aucun ram:*Amount n’est modifié tant que ce flag est actif.
do_not_invent_missing_partiestrueEmpêche l’ajout de données de parties (noms, adresses, identifiants de vendeur/acheteur).
target_profileauto-détectéProfil Factur-X cible (MINIMUM, BASIC_WL, BASIC, EN16931, EXTENDED).

Les défauts sont conservateurs par conception. En production, gardez do_not_modify_amounts: true sauf si vous avez vérifié que votre ERP exporte bien les montants corrects avec un séparateur incorrect. Modifier un montant financier dans un XML de facturation est une opération sensible — la contrainte existe pour forcer cette décision consciente.

Ce que Repair ne corrige PAS

Le moteur de réparation corrige les erreurs de format, pas les erreurs de fond. La distinction est nette :

Erreurs de format (réparables) : la donnée est correcte, sa représentation XML est incorrecte. Une date 2024-01-15 contient la bonne information, mais le format ne correspond pas à ce que CII attend.

Erreurs de fond (non réparables) : la donnée elle-même est incorrecte ou absente. Le total TTC ne correspond pas à la somme HT + TVA. Le numéro de TVA est invalide. Le vendeur est absent du document.

Exemples concrets d’erreurs que Repair ne peut pas corriger :

  • BR-CO-10, BR-CO-15 — incohérences arithmétiques entre les totaux. Si GrandTotalAmount ne correspond pas à TaxBasisTotalAmount + TaxTotalAmount, c’est un bug dans le calcul de l’ERP, pas un problème de format.
  • BR-S-08, BR-S-09 — taux de TVA incohérent avec le montant. Le moteur ne recalcule pas la TVA.
  • BR-02, BR-05, BR-06 — champs obligatoires manquants (numéro de facture, nom du vendeur, nom de l’acheteur). Ce sont des données métier que seul le système source peut fournir.

Pour ces erreurs, la correction doit se faire dans le système source (ERP, logiciel de facturation, générateur XML). Le moteur Repair ne remplace pas la qualité des données en entrée — il corrige les artefacts de formatage qui polluent le rapport de validation.

Pour le détail des deux niveaux de validation (XSD vs Schematron), voir Valider EN16931/Factur-X : XSD vs Schematron, erreurs BR-*.

Intégration dans un pipeline

Le pattern recommandé pour intégrer Repair dans un pipeline de traitement automatisé :

XML source → Validate → erreurs réparables ? → Repair → Validate → suite du pipeline

Étape 1 : Validation initiale. Appelez /api/v1/validate pour obtenir le rapport complet. Si le XML est valide, passez directement à la suite.

Étape 2 : Réparation conditionnelle. Si des erreurs sont détectées, appelez /api/v1/repair. L’API inclut la validation avant et après dans sa réponse — pas besoin d’un appel validate séparé.

Étape 3 : Vérification. Consommez repairSuccessful comme indicateur primaire, puis vérifiez que target.status et validation_after.target.status sont verified pour la cible demandée. validation_after.valid reste un détail technique du rapport de validation ; seul, il ne suffit pas à dire que le XML corrigé couvre la cible demandée. Si la cible n’est pas vérifiée, les erreurs restantes nécessitent une intervention humaine ou une correction dans le système source.

1 livrable final = 1 facture traitée

Règle de décompte

Idempotence : le header Idempotency-Key empêche de réutiliser une clé pour un autre fichier : un même Idempotency-Key avec un payload différent retourne une erreur 409 Conflict. Sur /repair, le rejeu du même appel n’est pas encore garanti sans nouveau traitement : un appel relancé peut être traité et facturé une seconde fois. Avant de relancer après une erreur réseau, vérifiez si le premier appel a abouti.

curl -X POST https://api.facturxapi.com/api/v1/repair \
  -H "X-API-Key: votre-cle-api" \
  -H "Idempotency-Key: repair-facture-2024-00142" \
  -F "file=@./facture.xml"

Erreurs réparables : fiches détaillées

Chaque type d’erreur réparé automatiquement a sa fiche dédiée avec exemple XML avant/après :

Les erreurs NON réparables (catégorie TVA incorrecte, montant faux, IBAN, champ métier absent) restent de la responsabilité de l’ERP. Voir Confusion catégorie TVA S/Z/E/AE, BT-131 montant net de ligne et IBAN format ISO 13616 pour le diagnostic.

Et maintenant ?

Réparer mon XML Factur-X →

curl -X POST https://api.facturxapi.com/api/v1/repair \
  -H "X-API-Key: VOTRE_CLE" \
  -F "file=@./facture.xml"

Clé Sandbox : 100 factures traitées offertes les 14 premiers jours, puis 10 factures traitées/mois. Launch prend le relais pour utiliser /repair, /convert et /extract sur un flux récurrent. Obtenir une clé API.

Aller plus loin

#factur-x #repair #correction #EN16931 #XML #CII #schematron #API