FacturX API
Technique

Erreurs Factur-X BTP : autoliquidation, situations, retenue de garantie — diagnostic et correction

Mis à jour le 10 min de lecture Par FacturX API

Corriger les erreurs Factur-X spécifiques au BTP : autoliquidation (art. 283, 2 nonies CGI), factures de situation, retenue de garantie, multi-taux TVA. Exemples XML et API.

En bref

  • Cinq points de contrôle sur les factures BTP : autoliquidation (AE), situations, retenue de garantie, ventilation multi-taux et identification des entreprises.
  • Autoliquidation sous-traitance relevant de l’article 283, 2 nonies du CGI : catégorie AE, taux 0 et motif textuel ou codé, par exemple VATEX-EU-AE.
  • Dans l’exemple de situation ci-dessous, les lignes portent le montant de la situation courante, calculé par différence d’avancement.
  • Retenue de garantie : ne pas déclarer une somme non réglée comme un montant déjà payé (BT-113).
  • Valider les contrôles documentaires applicables via /api/v1/validate avant transmission ; ce résultat ne garantit pas la réception ou l’acceptation par une PA ou Chorus Pro.

Autoliquidation sur certains travaux sous-traités, situations successives, retenues contractuelles et taux de TVA différents rendent le mapping BTP délicat. Les données métier doivent conserver leur sens dans le XML CII : une égalité arithmétique correcte ne suffit pas si un champ contient une valeur de nature différente.

Le problème n’est pas technique au sens strict. Les données existent dans l’ERP. Le problème est le mapping : chaque spécificité BTP active des règles Schematron différentes, exige des codes précis et des relations arithmétiques strictes entre champs. Un vat_category incorrect, un montant de situation mal positionné ou une retenue soustraite au mauvais niveau peut faire échouer les contrôles documentaires et entraîner un rejet par la PA ou Chorus Pro.

Cet article documente cinq erreurs de mapping Factur-X sur les factures BTP, avec le diagnostic Schematron, le XML invalide, le XML corrigé et les références légales exactes. Pour le contexte général de la validation (XSD vs Schematron, workflow de debug), voir Valider EN16931/Factur-X : XSD vs Schematron, erreurs BR-*. Pour le mapping complet des données ERP vers CII, voir Données ERP → Factur-X CII : mapper JSON vers XML EN16931.

Erreur #1 : autoliquidation mal déclarée (BR-AE-*)

Pour les travaux immobiliers sous-traités relevant de l’article 283, 2 nonies du CGI, le sous-traitant facture sans collecter la TVA : le preneur assujetti l’autoliquide. Les conditions et exclusions sont précisées par la DGFiP.

Le piège

L’ERP code la ligne avec vat_category="S" et vat_rate=20 puis applique un montant TVA de zéro. Ou bien il utilise le bon code AE mais omet le motif d’exonération ou les identifiants fiscaux. Les règles déclenchées dépendent de la catégorie et des données présentes dans le document.

XML invalide

<ram:ApplicableTradeTax>
  <!-- ERREUR : catégorie "S" au lieu de "AE" -->
  <ram:TypeCode>VAT</ram:TypeCode>
  <ram:CategoryCode>S</ram:CategoryCode>
  <ram:RateApplicablePercent>0</ram:RateApplicablePercent>
</ram:ApplicableTradeTax>

Cet extrait de taxe de ligne illustre BR-S-05 : une ligne de catégorie S doit avoir un taux strictement positif. Si l’opération relève réellement de AE, vérifier aussi les identifiants requis par BR-AE-02 et le motif de la ventilation requis par BR-AE-10. L’absence de ces informations ne peut pas se déduire de ce seul fragment.

Les règles BR-AE activées

RègleObjet
BR-AE-01Si une ligne, remise ou charge porte AE, la facture doit contenir exactement une ventilation AE dans BG-23
BR-AE-02Pour une ligne AE, présence d’un identifiant fiscal vendeur (BT-31, BT-32 ou BT-63) et d’un identifiant acheteur (BT-48 ou BT-47)
BR-AE-05Les lignes de facture rattachées à la catégorie AE doivent avoir un taux de 0
BR-AE-10Une raison d’exonération (BT-120) ou un code (BT-121) doit être présent pour la catégorie AE

La description complète de chaque règle BR-AE est disponible dans les artefacts EN16931 officiels. Le contenu exact peut varier selon la version des artefacts.

Attention aux identifiants requis : le vendeur doit fournir au moins un identifiant fiscal parmi BT-31 (TVA intra), BT-32 (identifiant fiscal national) ou BT-63 (identifiant TVA du représentant fiscal du vendeur). L’acheteur doit fournir BT-48 (identifiant TVA acheteur) ou BT-47 (identifiant légal acheteur). Ce n’est pas “les deux parties doivent avoir un numéro de TVA” — l’acheteur peut fournir l’identifiant légal adapté au contexte, par exemple son SIREN dans le cadre France CTC.

Fragments XML corrigés

Extraits pédagogiques à placer sous les éléments CII appropriés : les identifiants TVA appartiennent respectivement au vendeur et à l’acheteur, la ventilation au règlement de niveau document. Les valeurs d’identité sont fictives ; ces fragments ne constituent pas une facture complète validée.

<!-- Vendeur : identifiant fiscal (BT-31) -->
<ram:SpecifiedTaxRegistration>
  <ram:ID schemeID="VA">FR32123456789</ram:ID>
</ram:SpecifiedTaxRegistration>

<!-- Acheteur : identifiant TVA (BT-48) -->
<ram:SpecifiedTaxRegistration>
  <ram:ID schemeID="VA">FR87987654321</ram:ID>
</ram:SpecifiedTaxRegistration>

<!-- Ventilation TVA corrigée -->
<ram:ApplicableTradeTax>
  <ram:CalculatedAmount>0.00</ram:CalculatedAmount>
  <ram:TypeCode>VAT</ram:TypeCode>
  <ram:ExemptionReason>Autoliquidation - Sous-traitance BTP,
    article 283, 2 nonies du CGI</ram:ExemptionReason>
  <ram:BasisAmount>15000.00</ram:BasisAmount>
  <ram:CategoryCode>AE</ram:CategoryCode>
  <ram:RateApplicablePercent>0</ram:RateApplicablePercent>
</ram:ApplicableTradeTax>

Pour les travaux immobiliers sous-traités concernés, la facture porte la mention « Autoliquidation ». La référence à l’article 283, 2 nonies peut préciser le motif. BR-AE-10 accepte un motif textuel indiquant l’autoliquidation ou un code correspondant ; elle n’impose pas une citation juridique française avec une graphie particulière.

Le code VATEX-EU-AE (BT-121) et un motif textuel (BT-120) peuvent coexister. Distinguez cette règle sémantique EN16931 des mentions fiscales françaises et des exigences supplémentaires du profil destinataire. Sources : BR-AE-01, BR-AE-02 et BR-AE-10.

Pour un exemple complet JSON → XML incluant l’autoliquidation, voir Données ERP → Factur-X CII.

Erreur #2 : facture de situation avec des montants incohérents (BR-CO-10)

Les marchés de travaux peuvent être facturés par situations successives. Dans l’exemple ci-dessous, la situation courante est calculée par différence entre l’avancement cumulé et ce qui a déjà été facturé. Les lignes et totaux XML doivent correspondre au périmètre choisi ; cela ne constitue pas une interdiction générale des présentations cumulatives en CII.

Le piège

Pour un marché de 100 000 EUR HT, un avancement passant de 45 % à 70 % représente ici une situation de 25 000 EUR. Si BT-106 vaut 25 000 EUR alors que les montants nets de ligne BT-131 totalisent 70 000 EUR, BR-CO-10 échoue : elle compare BT-106 à la somme des BT-131, pas directement au total HT BT-109.

La bonne approche

Dans cet exemple, les montants des lignes représentent uniquement la situation courante. BT-25 permet de référencer une facture antérieure lorsqu’une telle référence est pertinente ; ce n’est pas une obligation universelle de chaînage des situations.

<!-- Référence à la situation précédente (BT-25) -->
<ram:InvoiceReferencedDocument>
  <ram:IssuerAssignedID>SIT-2026-042</ram:IssuerAssignedID>
</ram:InvoiceReferencedDocument>

<!-- Ligne : montant de la situation courante uniquement -->
<ram:IncludedSupplyChainTradeLineItem>
  <ram:AssociatedDocumentLineDocument>
    <ram:LineID>1</ram:LineID>
  </ram:AssociatedDocumentLineDocument>
  <ram:SpecifiedTradeProduct>
    <ram:Name>Gros oeuvre — avancement situation 3 (45% à 70%)</ram:Name>
  </ram:SpecifiedTradeProduct>
  <ram:SpecifiedLineTradeAgreement>
    <ram:NetPriceProductTradePrice>
      <ram:ChargeAmount>25000.00</ram:ChargeAmount>
    </ram:NetPriceProductTradePrice>
  </ram:SpecifiedLineTradeAgreement>
  <ram:SpecifiedLineTradeDelivery>
    <ram:BilledQuantity unitCode="C62">1</ram:BilledQuantity>
  </ram:SpecifiedLineTradeDelivery>
  <ram:SpecifiedLineTradeSettlement>
    <ram:ApplicableTradeTax>
  <ram:TypeCode>VAT</ram:TypeCode>
  <ram:CategoryCode>S</ram:CategoryCode>
  <ram:RateApplicablePercent>10</ram:RateApplicablePercent>
</ram:ApplicableTradeTax>
    <ram:SpecifiedTradeSettlementLineMonetarySummation>
      <ram:LineTotalAmount>25000.00</ram:LineTotalAmount>
    </ram:SpecifiedTradeSettlementLineMonetarySummation>
  </ram:SpecifiedLineTradeSettlement>
</ram:IncludedSupplyChainTradeLineItem>

Les totaux doivent correspondre au périmètre des lignes et aux remises/charges documentaires : BR-CO-10 vérifie BT-106 = somme des BT-131 ; BR-CO-13 vérifie BT-109 = BT-106 − BT-107 + BT-108 ; BR-CO-15 vérifie BT-112 = BT-109 + BT-110. Un écart avec l’égalité attendue peut entraîner l’échec de la règle. Sources : BR-CO-10, BR-CO-13 et BR-CO-15.

Le nom de la ligne (BT-153) peut mentionner la tranche d’avancement pour la traçabilité. Mais la cohérence arithmétique se joue sur les montants, pas sur le libellé.

Erreur #3 : retenue de garantie mal modélisée

Dans les marchés privés couverts par la loi n°71-584 du 16 juillet 1971, la retenue prévue contractuellement est plafonnée à 5 % des acomptes. L’article 2 prévoit sa libération après un an à compter de la réception, sauf opposition motivée dans les conditions qu’il fixe. Les marchés publics relèvent d’un régime distinct. Ne supposez donc pas un taux ou une date de libération universels.

Le piège

BT-113 représente les montants déjà payés. Une retenue encore non réglée ne devient pas un prépaiement pour satisfaire une formule. La règle BR-CO-16 vérifie BT-115 = BT-112 − BT-113 + BT-114 ; sa réussite arithmétique ne justifie pas le sens métier des valeurs.

Avec 39 600 EUR TTC et une retenue contractuelle de 1 980 EUR, saisir artificiellement 1 980 EUR comme paiement reçu peut produire une égalité correcte tout en décrivant un paiement qui n’a pas eu lieu. Ce mapping est à éviter. BT-115 exprime le montant dû, pas le montant déjà réglé.

Définir le traitement avant le mapping

Le traitement de la retenue doit être défini selon le contrat, le profil et les spécifications du destinataire. Ne modifiez ni le TTC ni les paiements réellement reçus pour forcer la validation. Une note peut expliquer les conditions contractuelles, mais ne remplace pas la modélisation requise. Aucun mapping universel de remplacement n’est proposé ici.

Sources : définition de BT-113 / montant déjà payé et BR-CO-16.

Erreur #4 : multi-taux TVA incohérents sur un même chantier (BR-S-08, BR-CO-14)

Selon la nature des travaux et les conditions fiscales applicables au logement, une facture peut comporter des opérations à 10 %, 5,5 % ou au taux normal de 20 %. L’exemple suppose l’éligibilité de chaque opération au taux indiqué : consultez les conditions précisées par la DGFiP. Chaque combinaison catégorie/taux concernée doit avoir sa ventilation BG-23.

Le piège

Si l’ERP regroupe les bases sans distinguer les taux, BR-S-08 peut échouer : elle contrôle les bases par catégorie/taux à partir des lignes et des remises/charges documentaires correspondantes. BR-CO-14 contrôle séparément que BT-110 est la somme des montants de TVA BT-117 ; un mauvais regroupement ne signifie pas que les deux règles échouent systématiquement.

XML corrigé : trois ventilations séparées

<!-- Ventilation 1 : travaux à 10% -->
<ram:ApplicableTradeTax>
  <ram:CalculatedAmount>1800.00</ram:CalculatedAmount>
  <ram:TypeCode>VAT</ram:TypeCode>
  <ram:BasisAmount>18000.00</ram:BasisAmount>
  <ram:CategoryCode>S</ram:CategoryCode>
  <ram:RateApplicablePercent>10</ram:RateApplicablePercent>
</ram:ApplicableTradeTax>

<!-- Ventilation 2 : amélioration énergétique à 5.5% -->
<ram:ApplicableTradeTax>
  <ram:CalculatedAmount>467.50</ram:CalculatedAmount>
  <ram:TypeCode>VAT</ram:TypeCode>
  <ram:BasisAmount>8500.00</ram:BasisAmount>
  <ram:CategoryCode>S</ram:CategoryCode>
  <ram:RateApplicablePercent>5.5</ram:RateApplicablePercent>
</ram:ApplicableTradeTax>

<!-- Ventilation 3 : fournitures à 20% -->
<ram:ApplicableTradeTax>
  <ram:CalculatedAmount>640.00</ram:CalculatedAmount>
  <ram:TypeCode>VAT</ram:TypeCode>
  <ram:BasisAmount>3200.00</ram:BasisAmount>
  <ram:CategoryCode>S</ram:CategoryCode>
  <ram:RateApplicablePercent>20</ram:RateApplicablePercent>
</ram:ApplicableTradeTax>

Le total TVA (BT-110) doit être la somme exacte : 1 800.00 + 467.50 + 640.00 = 2 907.50 EUR. Le total HT (BT-109) : 18 000.00 + 8 500.00 + 3 200.00 = 29 700.00 EUR. Chaque ligne de facture doit porter le RateApplicablePercent correspondant à la ventilation dont elle relève. Un taux erroné sur une ligne peut déséquilibrer les bases des ventilations concernées.

Pour le détail complet des règles BR-S-* et BR-CO-*, voir le Catalogue des erreurs BR-* EN16931.

Erreur #5 : SIRET manquant ou mal formaté

SIREN et SIRET désignent deux niveaux différents : l’entreprise (9 chiffres) et l’établissement (14 chiffres). Ne remplacez pas automatiquement un SIREN par un SIRET.

Le piège

Confondre l’identifiant légal, l’identifiant d’établissement et l’adresse de routage. Dans le cadre France CTC, distinguez notamment le SIREN vendeur en BT-30 (0002) et le SIRET en BT-29 (0009). Le routage BT-34/BT-49 utilise un autre champ et un schéma d’adressage, notamment 0225 dans le contexte France CTC.

Fragments CII pour le contexte France CTC

<!-- Sous SellerTradeParty : BT-29, établissement (valeur fictive) -->
<ram:GlobalID schemeID="0009">12345678901234</ram:GlobalID>
<!-- Sous SellerTradeParty : BT-30, identifiant légal (valeur fictive) -->
<ram:SpecifiedLegalOrganization>
  <ram:ID schemeID="0002">123456789</ram:ID>
</ram:SpecifiedLegalOrganization>

Ces valeurs illustrent les emplacements, pas des identifiants de registre valides. Les exigences de format et de schéma dépendent du référentiel exécuté. BR-CO-26 demande au moins un identifiant vendeur parmi BT-29, BT-30 ou BT-31 ; elle n’impose pas universellement un SIRET. Les conventions historiques Chorus Pro doivent être lues séparément de celles du nouveau circuit France CTC.

Sources : artefacts France RFE du FNFE-MPE et BR-CO-26. La version publiée d’un référentiel ne prouve pas son exécution par votre outil ; consultez le résultat de contrôle.

Pipeline de diagnostic pour le BTP

Face à une facture BTP rejetée, le diagnostic suit un arbre de décision basé sur le type d’erreur :

1. Identifier la famille d’erreur

  • Erreur BR-AE-* → problème d’autoliquidation
  • Erreur BR-CO-10, BR-CO-13, BR-CO-15 → problème de cohérence des montants (situation, retenue)
  • Erreur BR-S-08, BR-CO-14 → problème de ventilation multi-taux
  • Erreur BR-CO-26 → identifiant vendeur manquant parmi BT-29, BT-30 ou BT-31

2. Vérifier par type

Type de facture BTPPoints de contrôle
Sous-traitance relevant de l’autoliquidationvat_category=AE + vat_rate=0 + motif exonération + identifiants vendeur/acheteur
SituationLignes et totaux cohérents avec le périmètre facturé ; référence BT-25 si pertinente
Avec retenueTraitement contractuel défini ; BT-113 réservé aux paiements réellement effectués
Multi-taux rénovationUne ventilation BG-23 par combinaison catégorie + taux
IdentificationSIREN, SIRET et routage dans les champs et schémas du circuit concerné

3. Valider et itérer

L’API Validate rapporte les contrôles exécutés et leurs erreurs. Repair peut appliquer certaines corrections déterministes à un XML CII et retourne du XML. Les catégories TVA, identifiants et montants métier doivent provenir de la source ERP. Revalidez le document final ; un contrôle local ne garantit pas l’acceptation PA ou Chorus Pro.

Testez une facture BTP directement dans le scanner en ligne pour obtenir un diagnostic structuré.

Erreurs fréquentes et fiches de diagnostic

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

Et maintenant ?

Tester ma facture maintenant →

 
curl -X POST https://api.facturxapi.com/api/v1/validate \
  -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

#BTP #factur-x #autoliquidation #EN16931 #erreurs #facture de situation #retenue de garantie

Et maintenant ?

Prochaines étapes

Choisissez l'étape suivante pour activer FacturX API sur votre stack. Tous les liens sont internes pour garder le suivi clair.

→

Vérifier une facture

Déposez un PDF ou XML pour obtenir un diagnostic EN16931 clair, sans compte.

→

Obtenir une clé API

Demandez une clé Sandbox par email : 100 factures traitées offertes les 14 premiers jours, puis 10 factures traitées/mois.

→

Voir les tarifs

Plans adaptés du prototype à la production : Sandbox, Launch, Scale, Business et accompagnement.

→

Documentation

Référence complète de l'API : endpoints, paramètres, exemples.