Générateur UBL — chaque cas métier français, sous forme de document exécutable

La réforme vous donne une liste de situations métier qu'une facture peut encoder — les cas d'usage de la XP Z12-014 — et un tableau de champs. Ce qu'elle ne vous donne pas, c'est une facture conforme pour chacune. Si bien que la première fois que vous construisez une facture d'acompte, une facture affacturée ou une auto-facture, vous découvrez si vous avez eu raison au moment où elle est rejetée.

Cette page comble ce manque. Choisissez une situation métier, lisez ce qui s'y passe réellement et pourquoi la réforme en fait un cas à part entière, puis repartez avec le XML UBL 2.1 conforme à l'EN 16931 et l'appel POST /v1/documents/send exact qui le produit. 59 scénarios, couvrant les 45 cas d'usage numérotés ainsi que les neuf fondamentaux dont toute intégration française a besoin dès le premier jour.

Pourquoi un générateur plutôt qu'une simple liste de champs

Une facture électronique française n'est pas un document unique assorti d'options. Les mêmes 10 000 € de prestation produisent un document matériellement différent selon qu'il s'agit d'un acompte, d'une facture définitive qui déduit cet acompte, d'une auto-facture, d'une facture affacturée ou d'une facture de sous-traitance en autoliquidation — code type différent, cadre de facturation différent, parties différentes, catégorie de TVA différente, cycle de vie différent. Chacun de ces choix a une conséquence juridique, et chacun a une règle qui vous rejette si vous vous trompez.

Trois erreurs reviennent constamment, et toutes trois sont des décisions métier avant d'être techniques :

Mode d'emploi

1. Trouvez votre situation. Filtrez par thème, ou cherchez ce que vous faites réellement — « acompte », « affacturage », « auto-facturation », « autoliquidation », « Réunion ».
2. Lisez la description métier. Ce qui se passe, pourquoi la réforme s'y intéresse, ce qui dérape, et quels champs le portent. Si cette section ne correspond pas à votre situation, vous n'êtes pas sur le bon cas — cherchez encore avant d'écrire du code.
3. Récupérez les artefacts. Le XML UBL à valider, et la requête d'envoi à déclencher. Les deux sont déjà conformes : un diff avec votre propre sortie vous donne exactement la liste de ce qui vous manque.

Le générateur

Le cadre de facturation — le champ le plus « métier » de la facture

Toute facture électronique française déclare de quel type d'opération il s'agit, en un code (BT-23, porté par cbc:ProfileID). La première lettre indique Biens, Services ou Mixte ; le chiffre indique la situation. C'est la réponse de la réforme elle-même à la question « qu'est-ce que je regarde ? », et il détermine les règles applicables — raison pour laquelle le générateur le renseigne par scénario plutôt que de tout mettre à S1.

Source : BR-FR-08. Envoyer une facture sans cadre, ou avec un cadre qui contredit la date d'exigibilité (BT-8), c'est le décalage silencieux qui place la TVA sur la mauvaise CA3, des deux côtés.

Les types de facture — et pourquoi « on envoie 380 » ne marche pas

La France accepte une liste fermée de types de document (BT-3, BR-FR-04). Tout autre code UNTDID 1001 est rejeté. La liste est courte mais structurante : c'est elle qui indique à toute la chaîne aval qu'un document est un acompte, une auto-facture, une facture affacturée ou une rectification — avant même que quiconque ne lise un montant.

Les trois mentions que toute facture française doit porter

La règle BR-FR-05 impose au moins trois notes, chacune qualifiée par un code sujet (BT-21), sur toute facture française. Ce sont des mentions légales issues du Code de commerce, pas de la mise en forme — et c'est la première cause d'échec d'une facture pourtant correcte au sens de l'EN 16931, parce que les ERP conçus pour d'autres marchés n'ont aucun champ pour les porter.

<cbc:Note>#PMT#Indemnité forfaitaire pour frais de recouvrement en cas de retard de paiement : 40 EUR (art. L441-10 du Code de commerce).</cbc:Note>
<cbc:Note>#PMD#Pénalités de retard : trois fois le taux d'intérêt légal, exigibles le jour suivant la date d'échéance.</cbc:Note>
<cbc:Note>#AAB#Escompte pour paiement anticipé : néant.</cbc:Note>
<cbc:Note>#BAR#B2B</cbc:Note>

En UBL, le code sujet et le texte partagent une même balise cbc:Note, le code étant porté par un préfixe #CODE#. La quatrième note ci-dessus n'est pas exigée par BR-FR-05 mais compte tout autant : BAR déclare de quel côté de la réforme le document se situe (BR-FR-20).

TVA — les catégories acceptées en France, et le moment de l'exigibilité

La France restreint la liste des catégories de TVA de l'EN 16931 (BR-FR-15) et fixe les taux acceptés (BR-FR-16). Toute catégorie autre que S et Z exige un motif et un code VATEX — une facture qui ne facture pas de TVA sans dire pourquoi est rejetée, et à juste titre : le motif est ce qui rend l'exonération défendable en contrôle.

Quand la TVA devient exigible (BT-8)

Ce seul code détermine sur quelle période de déclaration la facture atterrit, pour les deux parties. Les biens sont taxables à la livraison ; les services à l'encaissement, sauf option du vendeur pour la TVA sur les débits. Se tromper ne fait pas échouer la validation — cela place simplement la TVA sur le mauvais mois.

Utiliser l'API

Le même référentiel est servi par l'API, de sorte que vous pouvez le brancher sur votre propre suite de tests plutôt que de copier du XML depuis un navigateur. Le référentiel et le générateur ne demandent aucune clé d'API — ce sont des fonctions pures, sans accès aux données de qui que ce soit.

Lister tous les cas métier

curl https://back.flowie.ink/exchange/v1/tools/fr/ubl/scenarios

Filtrez avec ?theme=, ?family=, ?channel=e-reporting, ?case=20, ou cherchez dans les descriptions métier avec ?q=factoring.

Générer un cas avec vos propres parties

curl -X POST https://back.flowie.ink/exchange/v1/tools/fr/ubl/generate \
  -H "Content-Type: application/json" \
  -d '{
    "scenarioId": "uc-21-final-after-deposit",
    "number": "FA-2027-0042",
    "issueDate": "2027-03-01",
    "seller": { "name": "Ma Société SAS", "siret": "55210055400013" },
    "buyer":  { "name": "Mon Client SA",  "siret": "39158000400021" }
  }'

La réponse contient la description métier, le modèle de facture, le XML UBL, les totaux calculés et le corps POST /v1/documents/send qui l'envoie. Les schémas d'identifiants restent fixes : une surcharge ne peut jamais produire une partie dont le SIRET et le SIREN se contredisent (BR-FR-09).

Générer et valider en un seul appel

curl -X POST https://back.flowie.ink/exchange/v1/tools/fr/ubl/generate-and-validate \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{ "scenarioId": "uc-10-factoring" }'

Celui-ci demande une clé, parce qu'il appelle le service de schématrons pour votre compte. Utilisez-le comme réponse de référence quand votre propre sortie pour le même cas est rejetée : générez le scénario, validez les deux, comparez. Pour valider une facture que vous avez construite vous-même, utilisez POST /v1/documents/validate.

Ce que « valide » veut dire ici

Chaque document généré passe les quatre mêmes portes qu'une vraie facture :

1. XSD — est-ce structurellement une facture UBL 2.1 ? UBL est typé par séquence : un élément dans le mauvais ordre échoue ici, avant qu'une seule règle métier ne s'exécute.
2. Schématron du profil EN 16931 — les totaux s'additionnent-ils (BR-CO-*), chaque ligne exonérée donne-t-elle un motif, chaque ventilation de TVA est-elle cohérente ?
3. Règles BR-FR — la couche française : les mentions légales, les listes fermées de codes types et de cadres, la cohérence SIRET/SIREN, les taux de TVA acceptés.
4. Contrôles de champs CIUS-FR — les champs que la France rend légalement obligatoires alors que l'EN 16931 les laisse facultatifs : le code d'exigibilité, la date d'échéance, la forme juridique et le capital social du vendeur, le SIREN et l'identifiant d'adressage de l'acheteur.

Ce que le générateur ne fait pas

• Il ne vérifie pas vos données dans l'annuaire. Les règles BR-FR-10 et BR-FR-11 exigent que les SIREN du vendeur et de l'acheteur soient présents et actifs dans l'annuaire du PPF. C'est une consultation en temps réel — voir routage & annuaire.
• Il n'émet pas de statuts de cycle de vie. Chaque scénario indique les statuts 200–213 qu'il déclenche, mais les émettre reste le travail de votre intégration — voir l'explorateur de cycle de vie et le playbook d'intégration.
• Il ne produit pas de Factur-X. Les exemples sont en UBL. Flowie génère du Factur-X à partir des mêmes données à l'envoi ; s'il vous faut la syntaxe CII, envoyez avec format: "cii-xml".
• Les cas multi-vendeurs sont une forme de départ, pas une réponse finie. Les cadres S8/B8/M8 activent toute une famille de règles supplémentaires (BR-FR-MV-01 à BR-FR-MV-12) avec identifiants vendeur à la ligne et lignes de regroupement. Validez avant de construire dessus.

Références

• Les 45 cas d'usage, en détail — le référentiel que ce générateur implémente, avec les approfondissements par thème.
• France · PPF & PA, vue d'ensemble — échéances, champs obligatoires, routage, e-reporting.
• Explorateur de cycle de vie — statuts 200–213, qui doit émettre quoi.
• Playbook d'intégration — raccordement, envoi, e-reporting, mise en production.
• Types de document — chaque type que Flowie envoie, auto-facturation comprise.
• FNFE-MPE — l'association qui publie le CIUS français et les schématrons.
• impots.gouv.fr · facturation électronique — les pages de référence de la DGFiP et les Spécifications externes B2B.