Aller au contenu

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

  1. Si le mandat est actif, FinalizeInvoiceCommand / FinalizeCreditNoteCommand appellent EInvoiceReadinessValidator avant finalize(). Données manquantes → EInvoiceDataIncompleteException (HTTP 422, missingFields).
  2. 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.
  3. Les snapshots émetteur et client sont figés. Le XML ne lit que ces snapshots et les lignes.
  4. InvoiceFinalizedEvent / CreditNoteFinalizedEvent déclenchent GenerateInvoiceFacturXCommand / GenerateCreditNoteFacturXCommand.
  5. 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 : 380 facture, 381 avoir (facture créditée en BT-25).
  • Unités UN/ECE : UNIT → C62, HOUR → HUR, DAY → DAY, PACKAGE → LS (montant forfaitaire, pas un colis XPK). Une ligne horaire calculée à la minute part en MIN (80 pour 1h20) au prix horaire réel, base 60 MIN (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 ApplicableHeaderTradeDelivery est 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 TypeCode 380 sur InvoiceReferencedDocument (profil EN 16931).
  • Lignes : catégorie et taux TVA en ligne ; motif / code d'exemption (BT-120 / BT-121) seulement au niveau ApplicableTradeTax document.
  • TVA : catégorie S si taux > 0 et assujetti ; E + VATEX-FR-FRANCHISE en 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éma FC) 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}/finalize et POST /trainer/credit-notes/{uuid}/finalize : 422 { detail, missingFields } via EInvoiceIncompleteDataExceptionSubscriber.
  • 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, et GET /trainer/company expose vatRegimeDeclared (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.po du registre de l'état modifié — UX-407) ; pas un champ en plus.
  • Facture et avoir : la marque « Factur-X » (badge BaseBadge info, icône file-check) suit l'état figé du document — isEInvoice de GET /trainer/invoices/{uuid} et des réponses d'enregistrement et de finalisation, isEInvoice de CreditNoteResponse (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 de GET /trainer/invoices/config → billing.electronicInvoicingMandate. Le CRA n'embarque pas de Factur-X et n'affiche aucune marque ; EInvoiceMark.vue est supprimé.
  • Mandat (FEAT-452) : PUT /trainer/billing/settings/electronic-invoicing-mandate avec { "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 si summary.eInvoiceDocumentsCount est supérieur à 0 (UX-459).
  • École : mention SIRET requis pour la facturation électronique, n° de TVA et adresse électronique optionnels.