Champs de la facture¶
L'objet invoice accepté par POST /v1/invoices/generate et par l'outil MCP generate_invoice. Chaque champ correspond à un terme métier (BT) ou groupe (BG) EN 16931 ; le JSON Schema est servi sur /v1/schema/invoice.
Conventions : montants et quantités sont des chaînes décimales ("19.90"), les pourcentages aussi ("20", "5.5"), les dates au format AAAA-MM-JJ, les codes pays ISO 3166-1 alpha-2. Les champs inconnus sont rejetés (422), ce qui attrape les fautes de frappe tôt.
En-tête¶
| Champ | Obligatoire | BT | Notes |
|---|---|---|---|
number |
oui | BT-1 | 35 caractères max, lettres, chiffres, . _ / - (BR-FR-01/02) |
issue_date |
oui | BT-2 | |
type_code |
non | BT-3 | 380 facture (défaut), 381 avoir, 384 facture rectificative, 386 acompte, 389 autofacturation, 261, 751 |
currency |
non | BT-5 | Défaut EUR |
vat_accounting_currency |
non | BT-6 | |
due_date |
non | BT-9 | |
tax_point_date |
non | BT-7 | |
buyer_reference |
non | BT-10 | Souvent le code service / référence de routage de l'acheteur |
project_reference, contract_reference, purchase_order_reference, sales_order_reference, receiving_advice_reference, despatch_advice_reference, tender_reference |
non | BT-11..17 | |
buyer_accounting_reference |
non | BT-19 | |
payment_terms |
non | BT-20 | Raccourci pour payment.terms |
operation_type |
non | BT-23 | goods (biens), services (défaut), mixed : déduit le code de processus français B1/S1/M1 |
already_paid |
non | BT-23 | true donne B2/S2/M2 (facture déjà payée à l'émission) |
business_process |
non | BT-23 | Code explicite, prime sur les deux champs précédents |
french_mentions |
non | BG-1 | Voir ci-dessous |
notes[] |
non | BG-1 | {"text": "...", "subject_code": "AAI"} ; notes libres sur le document |
preceding_invoices[] |
non | BG-3 | {"number": "F-2026-0001", "issue_date": "2026-08-01"}, obligatoire pour les avoirs et rectificatives (BR-FR-06) |
additional_documents[] |
non | BG-24 | {"id": "PO-7781", "description": "...", "url": "https://..."} |
tax_exemption_reason, tax_exemption_reason_code |
non | BT-120 / BT-121 | Texte et code VATEX par défaut appliqués à chaque ligne exonérée / autoliquidée ; des défauts français sont fournis par catégorie |
prepaid_amount, rounding_amount |
non | BT-113 / BT-114 | Appliqués quand les totaux sont calculés |
totals |
non | BG-22 | À envoyer seulement pour forcer les totaux (vous portez alors la cohérence BR-CO-*) |
Mentions françaises (french_mentions)¶
Trois notes sont obligatoires sur les factures B2B françaises (BR-FR-05) : pénalités de retard (PMD), indemnité forfaitaire de 40 € (PMT) et politique d'escompte (AAB). Elles sont ajoutées automatiquement avec une formulation standard ; personnalisez chaque texte ou désactivez avec {"enabled": false} pour un vendeur non français :
"french_mentions": {
"enabled": true,
"late_payment_penalties": "Pénalités de retard : 3 fois le taux d'intérêt légal.",
"recovery_fee": "Indemnité forfaitaire pour frais de recouvrement : 40 €.",
"early_payment_discount": "Pas d'escompte pour paiement anticipé."
}
Parties (seller, buyer)¶
| Champ | Obligatoire | BT (vendeur / acheteur) | Notes |
|---|---|---|---|
name |
oui | BT-27 / BT-44 | Dénomination légale |
trading_name |
non | BT-28 / BT-45 | Nom commercial |
siren |
FR | BT-30 / BT-47, schéma 0002 |
9 chiffres. Obligatoire pour les parties françaises dans la réforme (BR-FR-03/04) |
siret |
non | BT-29 / BT-46, schéma 0009 |
14 chiffres, doit commencer par le SIREN (BR-FR-08) |
legal_registration_id, legal_registration_scheme |
non | BT-30 / BT-47 | Pour les sociétés non françaises (ex. 0208 numéro d'entreprise belge) |
vat_id |
recommandé | BT-31 / BT-48 | FR40732829320. Obligatoire sauf vendeur exonéré (BR-CO-26) |
tax_registration_id |
non | BT-32 | Vendeur seulement, identifiant fiscal local sans numéro de TVA |
legal_info |
non | BT-33 | Vendeur seulement : forme juridique, capital, ville du RCS ; imprimé sur le PDF |
electronic_address, electronic_address_scheme |
non | BT-34 / BT-49 | Par défaut le SIRET (0225) ou le schéma du numéro de TVA |
global_ids |
non | BT-29 / BT-46 | {"0088": "3012345678901"} GLN et autres identifiants ISO 6523 |
address |
oui | BG-5 / BG-8 | line1, line2, line3, postal_code, city, country_subdivision, country (obligatoire) |
contact |
non | BG-6 / BG-9 | name, department, phone, email |
Livraison (delivery)¶
name (BT-70), location_id + location_id_scheme (BT-71), address (BG-15), actual_date (BT-72), period_start / period_end (BT-73/74). Les règles françaises exigent l'adresse de livraison quand elle diffère de celle de l'acheteur (BR-FR-10).
Paiement (payment)¶
| Champ | BT | Notes |
|---|---|---|
means_code |
BT-81 | UNTDID 4461 : 30 virement, 58 virement SEPA, 59 prélèvement SEPA, 48 carte, 10 espèces, 20 chèque, ZZZ autre |
means_text |
BT-82 | |
remittance_information |
BT-83 | Par défaut le numéro de facture |
iban, account_name, bic |
BT-84/85/86 | Compte à créditer pour les virements |
mandate_reference, creditor_reference_id, debited_iban |
BT-89/90/91 | Prélèvement |
terms |
BT-20 | Conditions de paiement |
Lignes (lines[])¶
| Champ | Obligatoire | BT | Notes |
|---|---|---|---|
id |
non | BT-126 | Numérotées 1..n automatiquement si omis |
item_name |
oui | BT-153 | |
item_description |
non | BT-154 | Imprimé sous le nom de l'article |
note |
non | BT-127 | |
quantity |
oui | BT-129 | Chaîne décimale |
unit_code |
non | BT-130 | UN/ECE Rec 20 : C62 unité (défaut), HUR heure, DAY jour, MON mois, KGM, MTR, LTR, E48 unité de service |
unit_price |
oui | BT-146 | Prix unitaire net HT |
gross_unit_price, price_discount |
non | BT-148 / BT-147 | Prix brut et remise article |
price_base_quantity, price_base_unit_code |
non | BT-149 / BT-150 | Prix pour N unités |
vat_category |
non | BT-151 | S standard (défaut), Z taux zéro, E exonéré, AE autoliquidation, K intracommunautaire, G export, O hors champ, L, M |
vat_rate |
pour S |
BT-152 | "20", "10", "5.5", "2.1" |
seller_item_id, buyer_item_id |
non | BT-155 / BT-156 | |
standard_item_id, standard_item_id_scheme |
non | BT-157 | ex. GTIN avec schéma 0160 |
origin_country |
non | BT-159 | |
attributes |
non | BG-32 | {"Couleur": "bleu"} |
allowances[], charges[] |
non | BG-27 / BG-28 | {"amount": "10.00", "reason": "Remise fidélité", "percentage": "5", "base_amount": "200.00"} |
period_start, period_end |
non | BT-134 / BT-135 | Période de service, imprimée sur le PDF |
order_line_reference, buyer_accounting_reference |
non | BT-132 / BT-133 | |
net_amount |
non | BT-131 | Calculé comme quantity x unit_price / price_base_quantity - remises + charges si omis |
Remises et charges de pied de facture (allowances[], charges[])¶
amount (obligatoire, HT), base_amount, percentage, reason, reason_code (UNTDID 5189 pour les remises, 7161 pour les charges), vat_category (défaut S), vat_rate. Elles alimentent BT-107/BT-108 et la ventilation de TVA.
Totaux et ventilation de TVA¶
Calculés côté serveur et renvoyés dans l'enveloppe JSON, l'en-tête X-Facturx-Amount-Due et le résumé MCP :
- Total des lignes BT-106 = somme des nets de ligne ; BT-109 = BT-106 - BT-107 + BT-108.
- Une ligne de ventilation par (catégorie, taux) ; montant de TVA arrondi par ligne à 2 décimales (BR-CO-17).
- BT-112 = BT-109 + BT-110 ; BT-115 = BT-112 - acompte + arrondi.
- Les catégories exonérées portent le motif et le code VATEX (BT-120/121). Défauts français :
VATEX-FR-FRANCHISEpour la franchise en base (art. 293 B CGI), formulations d'autoliquidation et de livraison intracommunautaire avec les articles du CGI.
Cas fréquents¶
{
"seller": {"name": "Marie Leblanc", "siren": "851234567", "address": {...}},
"tax_exemption_reason": "TVA non applicable, art. 293 B du CGI",
"tax_exemption_reason_code": "VATEX-FR-FRANCHISE",
"lines": [{"item_name": "Création logo", "quantity": "1", "unit_price": "650.00", "vat_category": "E"}]
}
Pas de vat_id sur le vendeur ; l'API renseigne BT-32 pour que BR-CO-26 passe.
{
"seller": {"name": "Atelier Numérique SAS", "siren": "732829320", "vat_id": "FR40732829320", "address": {...}},
"buyer": {"name": "Muster GmbH", "vat_id": "DE811907980", "address": {"line1": "...", "city": "Berlin", "postal_code": "10115", "country": "DE"}},
"lines": [{"item_name": "Conseil", "quantity": "10", "unit_code": "HUR", "unit_price": "120.00", "vat_category": "AE"}]
}
Les deux numéros de TVA sont obligatoires pour AE (BR-AE-02). La mention « Autoliquidation de la TVA par le preneur » est ajoutée par défaut.
{
"type_code": "381",
"preceding_invoices": [{"number": "F-2026-0042", "issue_date": "2026-09-01"}],
"lines": [{"item_name": "Avoir remise commerciale", "quantity": "1", "unit_price": "100.00", "vat_rate": "20"}]
}
Les montants restent positifs sur un avoir (le code type porte le signe), comme l'exigent EN 16931 et les règles françaises.