Factur-X EN 16931 (factures et avoirs)
À la finalisation, Teadle produit un PDF Factur-X (profil EN 16931) seulement si le formateur a accepté le mandat de facturation (cas 19a) : le PDF HTML Dompdf existant, plus un XML CII embarqué (factur-x.xml). Sans mandat, le PDF reste classique. Le fichier stocké sur S3 est celui qui est téléchargé. La transmission vers une plateforme agréée n'est pas dans ce chantier.
Mandat (cas 19a)
Le champ trainer_billing_settings.electronic_invoicing_mandate est faux par défaut. L'activation se fait dans Paramètres de facturation, après une modale d'acceptation. La désactivation passe par une modale d'avertissement. Chaque bascule enregistre electronic_invoicing_mandate_last_accepted_at ou electronic_invoicing_mandate_last_cancelled_at. Une date déjà écrite n'est pas effacée par le changement inverse. Le choix est recopié dans le snapshot émetteur (electronicInvoicing = 1 ou 0) au moment de la finalisation.
Quand le mandat est actif, le XML contient une note BT-22 de code DCL (déclaration du créateur de la facture en cas de mandat de facturation, norme XP Z12-012) : « Facture émise par Teadle au nom et pour le compte de [nom] » (avoir : « Avoir émis par… »). La même phrase est imprimée en petit en bas du PDF. Le contrôle des données Factur-X (422) ne s'applique que si le mandat est actif.
Chaîne
- Si le mandat est actif,
FinalizeInvoiceCommand/FinalizeCreditNoteCommandappellentEInvoiceReadinessValidatoravantfinalize(). Données manquantes →EInvoiceDataIncompleteException(HTTP 422,missingFields). - La TVA de chaque catégorie du XML est la somme des TVA de ligne (
LineAmounts::vatCents), donc exactement la TVA du document et du PDF. BR-CO-17 tolère ±1 unité monétaire entre cette somme et l'arrondi de la base de la catégorie (Schematron CEN EN 16931, syntaxe CII, 1.3.16) : aucun refus de finalisation pour un écart d'arrondi. - Les snapshots émetteur et client sont figés. Le XML ne lit que ces snapshots et les lignes.
InvoiceFinalizedEvent/CreditNoteFinalizedEventdéclenchentGenerateInvoiceFacturXCommand/GenerateCreditNoteFacturXCommand.- Le XML n'est embarqué que si le snapshot émetteur a
electronicInvoicing=1. Sinon le PDF reste simple.
La clé documentData.eInvoice (format, profile, version, generatedAt) est écrite après un embarquement réussi. La colonne invoicing_invoice.is_e_invoice — et, pour un avoir, invoicing_credit_note.is_e_invoice (FEAT-451) — est alors passée à vrai, pour lister et filtrer sans ouvrir le PDF ; les trois listes d'avoirs du formateur exposent isEInvoice et le résumé de GET /trainer/invoices compte les documents Factur-X (eInvoiceDocumentsCount). Un brouillon reste à faux.
Bibliothèque
horstoeko/zugferd (ZugferdProfiles::PROFILE_EN16931, ZugferdDocumentPdfBuilder). Les images Docker ont déjà dom, xml, mbstring ; l'image de prod embarque aussi zlib.
Contrôle de conformité (CI, job backend-tests-functional) : TrainerInvoiceFacturXConformanceSamplesTest écrit dans var/facturx-samples/ une facture assujettie, une facture exonérée, un avoir (PDF + factur-x.xml extrait) et un témoin fautif sans note PMD ; tests/Resources/facturx/validate-conformance.sh les soumet au validateur KoSIT 1.6.3 (tests/Resources/facturx/kosit/scenarios.xml : XSD Factur-X EN 16931, Schematron du profil Factur-X EN 16931 et règles françaises BR-FR, artefacts FNFE-MPE France_RFE v1.4.0.04) — les conformes doivent être acceptés, le témoin rejeté (BR-FR-05). validate-pdfa.sh mesure la conformité PDF/A-3B par veraPDF 1.30.2 (profil 3b forcé) en rapport seul : le PDF Dompdf n'est pas encore produit en PDF/A (OutputIntent ICC, polices embarquées) — correction à part, après laquelle cette étape devient bloquante. Les tests unitaires relisent le XML (ZugferdDocumentPdfReader) et le valident en XSD (ZugferdDocumentValidator).
Données
| Zone | Champ | Rôle |
|---|---|---|
| Émetteur | vatRegime |
SUBJECT, FRANCHISE_293B, EXEMPT_261_4_4A. Défaut migration : SUBJECT pour tous (pas d'inférence du régime depuis un n° de TVA vide). Régime déclaré (TrainerCompany::isVatRegimeDeclared()) = franchise, exonération, ou assujetti avec n° de TVA valide ; sa mention obligatoire est VatRegime::legalMention(), lue par le PDF (mentions par défaut et éditeur de facture), par le XML (motif BT-120) et exposée en company.vatLegalMention de la config. Tant que le régime n'est pas déclaré, la mention par défaut reste celle d'avant la facture électronique : 293 B si tout est à 0 %, modifiable. |
| Émetteur | address, postalCode, city, countryCode |
Rue BT-35, CP BT-38, ville BT-37, pays BT-40. Obligatoires à la finalisation. |
| Émetteur | vatNumber |
Nullable. Obligatoire seulement si SUBJECT (format FR + 2 caractères + 9 chiffres). BT-31. |
| Émetteur | vatOnDebit |
BT-8 (UNTDID 2475) : 5 (date de facture) si vrai, sinon 72 (date de paiement). Réglage entreprise, recopié dans le snapshot. Mention obligatoire « Option pour le paiement de la taxe d'après les débits » (CGI, ann. II, art. 242 nonies A, 11° bis) : TrainerCompany::VAT_ON_DEBIT_MENTION, portée par TrainerCompany::vatLegalMention() pour un assujetti qui a exercé l'option — mentions par défaut, éditeur de facture (company.vatLegalMention), note BT-22 ; ignorée en franchise ou en exonération (BUG-453). |
| Émetteur | rcsNumber, electronicAddress |
Optionnels à la saisie (BT-33, BT-34). Le XML émet toujours une adresse de l'annuaire, schéma 0225 : la saisie si elle commence par le SIREN (« SIREN » ou « SIREN_suffixe »), sinon le SIREN seul. Jamais d'adresse e-mail (EM). |
| Émetteur | legalMentionsPenalties |
Figé à la finalisation tel que le PDF l'imprime (LatePaymentPenaltiesMentionProvider : surcharge du modèle résolu pour le PDF, sinon paramètre global, sinon mention par défaut LatePaymentPenaltiesMention::DEFAULT — jamais vide, art. L441-9). Trois notes BT-22 découpées dans ce texte : PMD (pénalités), PMT (indemnité 40 €), AAB (escompte). Le PDF d'un document finalisé relit ce texte figé (billingLegalPenaltiesFrozen) ; les textes par défaut du XML ne servent qu'aux instantanés antérieurs à ce figement. L'avoir reprend le texte dans son XML (BR-FR-05 exige PMT, PMD, AAB pour tout type de document, avoir compris), son PDF n'imprime pas de pénalités (art. L441-10). |
| Émetteur | SIRET | 14 chiffres, BT-29 scheme 0009. SIREN = 9 premiers chiffres, BT-30 scheme 0002. |
| Client | siret, street, postalCode, city, countryCode |
Obligatoires à la finalisation. SIREN BT-47 scheme 0002. Pays BT-55. |
| Client | vatNumber, electronicAddress |
Optionnels, jamais un motif de 422 (BT-48, BT-49). Adresse de l'annuaire, schéma 0225, même règle que l'émetteur. |
| Facture | operationCategory |
SERVICES par défaut → cadre BT-23 S1 (GOODS → B1, MIXED → M1). Pas d'UI. |
| Facture | currency |
EUR. Pas d'UI. |
| Facture | documentData.po |
Optionnel, BT-13. C'est la valeur du champ modèle « Réf. bon de commande » (client.showPo). Recopiée dans le snapshot client (po) à la finalisation. L'avoir reprend celui de la facture créditée. Pas de colonne dédiée. |
La migration reprend code postal et ville par regex sur l'adresse existante (Version20260930160000), puis Version20261002190000 les retire de address quand ils y figurent tels quels et sans ambiguïté (une seule suite de cinq chiffres). Sinon les champs restent vides et le 422 guide la saisie. Sur le PDF, l'adresse de l'émetteur est recomposée « rue, code postal ville » (clé address de BillingTemplatePreviewPartyDataProvider::issuerForTrainer(), sans répétition si la rue porte encore le code postal) ; le XML lit street (BT-35), postalCode (BT-38) et city (BT-37).
Adresse à boîte postale (CS, BP, TSA, numéro de lot avant le code postal) : Version20260930160000 y a pris la première suite de cinq chiffres pour code postal ; Version20261004190000 relit le code postal (BT-38) et la ville (BT-37) dans la dernière suite « code postal ville » de l'adresse, sans toucher la rue (BT-35), chaque valeur seulement si elle n'a pas été saisie à l'écran depuis.
Mapping XML
- Type
EInvoiceTypeCode:380facture,381avoir (facture créditée en BT-25). - Unités UN/ECE :
UNIT→C62,HOUR→HUR,DAY→DAY,PACKAGE→LS(montant forfaitaire, pas un colisXPK). Une ligne horaire calculée à la minute part enMIN(80 pour 1h20) au prix horaire réel, base 60MIN(BT-149 / BT-150). Le prix unitaire (BT-146) est le prix réel net de remise. - Période de prestation : BT-73 / BT-74 = première et dernière date d'intervention des lignes ; aucune date de livraison (BT-72) à la date d'émission. Le bloc
ApplicableHeaderTradeDeliveryest rempli par un Ship-To = adresse acheteur (évite un nœud vide, PEPPOL-EN16931-R008). - Avoir : BT-25 = numéro public de la facture créditée, sans
TypeCode380 surInvoiceReferencedDocument(profil EN 16931). - Lignes : catégorie et taux TVA en ligne ; motif / code d'exemption (BT-120 / BT-121) seulement au niveau
ApplicableTradeTaxdocument. - TVA : catégorie
Ssi taux > 0 et assujetti ;E+VATEX-FR-FRANCHISEen franchise 293 B ;E+ motif article 261-4-4° a pour l'exonération formation. Un régime non assujetti avec une ligne taxée est refusé. Sans n° de TVA, le SIREN est émis en BT-32 (schémaFC) pour couvrir BR-E-02. - BT-20 : libellé du délai de paiement uniquement. Les mentions de pénalités, de recouvrement et d'escompte sont des notes BT-22 (
PMD,PMT,AAB), pas le délai. - IBAN/BIC présents → moyen de paiement virement (
BT-81 = 30).
API et écrans
POST /trainer/invoices/{uuid}/finalizeetPOST /trainer/credit-notes/{uuid}/finalize: 422{ detail, missingFields }viaEInvoiceIncompleteDataExceptionSubscriber.- Refus de finalisation : les éditeurs de facture et d'avoir ouvrent le dialogue « Finalisation impossible » (
FinalizeErrorDialog,role="alertdialog"). Il liste les champs manquants au vocabulaire « organisation » (utils/eInvoiceMissingFields.js) et propose « Compléter Mon entreprise » ou « Compléter la fiche organisation » selon la famille des champs (UX-460). - Entreprise : régime, TVA sur les débits, code postal, ville, pays, RCS et adresse électronique. TVA intracom requise seulement si assujetti ; un régime
nullà l'enregistrement (« à déclarer ») conserve le régime en base sans exiger le numéro, etGET /trainer/companyexposevatRegimeDeclared(FEAT-450). - Facture : réf. bon de commande optionnelle (BT-13), saisie dans le champ « Réf. bon de commande » du bloc client de l'aperçu (indication « Facultatif », « — » en lecture seule — UX-465), marquée comme les champs d'en-tête quand elle diffère du dernier enregistrement (clé
documentData.podu registre de l'état modifié — UX-407) ; pas un champ en plus. - Facture et avoir : la marque « Factur-X » (badge
BaseBadgeinfo, icônefile-check) suit l'état figé du document —isEInvoicedeGET /trainer/invoices/{uuid}et des réponses d'enregistrement et de finalisation,isEInvoicedeCreditNoteResponse(FEAT-451) —, jamais le mandat courant : un document finalisé avant le mandat n'en porte pas (C10, BUG-454). Un brouillon sous mandat affiche l'information « Sera émis(e) en Factur-X à la finalisation » ; la modale de finalisation de la facture le rappelle. Le drapeau du mandat vient deGET /trainer/invoices/config→billing.electronicInvoicingMandate. Le CRA n'embarque pas de Factur-X et n'affiche aucune marque ;EInvoiceMark.vueest supprimé. - Mandat (FEAT-452) :
PUT /trainer/billing/settings/electronic-invoicing-mandateavec{ "electronicInvoicingMandate": true | false }— acceptation ou désactivation horodatée, idempotente, sans réenregistrer les autres paramètres ni exiger de tarif. - Liste des factures et tiroir de détail : la marque « Factur-X » d'une facture ou d'un avoir lit son état figé (
isEInvoice, FEAT-451), jamais le mandat ; un brouillon sous mandat actif porte l'information « Sera émise en Factur-X à la finalisation ». Le filtre « Factur-X » de la liste n'est proposé que si le mandat est actif ou sisummary.eInvoiceDocumentsCountest supérieur à 0 (UX-459). - École : mention SIRET requis pour la facturation électronique, n° de TVA et adresse électronique optionnels.