The productLogique métier(in French)10 min read
Facturation
Les pièces et leurs liens, des numéros sans trou, quand une facture est émise selon le canal, l’acompte et le solde, les factures rectificatives, les avoirs, des pièces qu’on ne retouche plus, puis la déclaration et l’export.
Not translated yet
Une facture, c’est une pièce comptable. On ne la modifie pas. Pour la corriger, on émet une autre pièce qui la cite. Toutes les pièces sont dans une seule table (Invoice, InvoiceLine). On les distingue par leur type (InvoiceType : facture, acompte, avoir), et elles sont chaînées par la pièce qu’elles citent (invoiceId).
Les chemins sans préfixe partent de apps/erp/shared/invoicing/.
Une pièce vient d’un encaissement, d’une vente soldée, d’un remboursement ou d’une correction (Acomptes et paiements, Service après-vente). Elle recopie la commande au moment de son archivage, et ensuite elle ne la relit plus. La déclaration de TVA et l’export de l’exercice la lisent. Et à leur tour, ils figent ce qu’elle peut encore corriger.
Les pièces
| Pièce | Type | Série (site / magasin) | Émise quand | Cite |
|---|---|---|---|---|
| Facture de vente | INVOICE | FA / FC | le client paie en ligne, ou on la demande sur une vente soldée du magasin | — |
| Facture d’acompte | DEPOSIT | FA / FC | on la demande, pour un encaissement du magasin | son encaissement |
| Facture rectificative | INVOICE | FA / FC | on corrige une identité, une adresse de livraison, une variante ou un prix | la facture qu’elle remplace |
| Avoir | CREDIT_NOTE | AV / AC | il y a un remboursement, ou un geste sans remboursement | la facture qu’il corrige |
| Facture qui annule un avoir | INVOICE | FA / FC | un remboursement est retombé | l’avoir |
Les liens, c’est la base qui les garantit, avec des index uniques et un trigger :
- Une seule facture de vente d’origine par commande (
Invoice_orderId_sale_key, index unique partiel). - Une facture n’est remplacée qu’une fois (
Invoice_rectification_key). - Un encaissement n’a qu’une facture d’acompte, et un remboursement n’a qu’un avoir (
paymentId,refundIduniques). - Un avoir cite toujours une pièce (
Invoice_credit_note_reference_check). - Les enchaînements admis sont écrits en SQL (
Invoice_chain_guard_insert). Une facture de vente ne remplace pas une facture d’acompte. Et une facture n’annule qu’un avoir dont le remboursement est retombé.
Les numéros
Chaque série a son compteur, sans trou (DocumentCounter). Une pièce prend son numéro par un UPDATE … RETURNING dans la transaction qui l’insère (invoice.ts#withReservedNumber). Si l’émission est annulée, le numéro est rendu. Une séquence Postgres ne ferait pas ça (Données).
Le compteur ne repart pas à zéro chaque année. L’année imprimée dans le numéro vient de la date d’émission, lue à l’heure de Paris (packages/domain/src/invoice-number.ts#formatInvoiceLabel). Une facture émise le 31 décembre à 23 h 30 appartient à l’exercice qui se termine, quel que soit le fuseau du serveur.
Les dates suivent les numéros. La date d’émission ne peut pas reculer sous la précédente de la série (GREATEST(clock_timestamp(), "lastIssuedAt")). Si un compteur est en retard sur les pièces existantes, l’émission s’arrête (StaleInvoiceCounterError). Le recaler, c’est une décision comptable, et le code ne la prend pas. La veille signale tout trou dans une série.
Le PDF, les e-mails, l’ERP et le site formatent les numéros de facture et de devis avec les mêmes fonctions (invoice-number.ts, quote-number.ts). Le numéro de commande n’a pas de format : c’est un entier, borné par order-number.ts#ORDER_NUMBER_MAX.
Quand une facture est émise
Sur le site, la facture se crée toute seule. Le webhook fait passer la commande à « payée », émet la facture (invoice.ts#ensureSaleInvoice), l’archive, puis envoie la confirmation avec la facture jointe (modules/payments/services/webhook-session.service.ts#handleSessionPaid). Si un événement est rejoué, il refait les mêmes étapes, et chacune reconnaît ce qui est déjà fait. Une commande dont le montant diverge est fermée sans facture. Une commande payée après son annulation par l’atelier reçoit sa facture, parce que l’argent est arrivé. C’est son remboursement qui émettra l’avoir.
Au magasin, une facture ne se crée pas toute seule. On l’émet depuis la fiche, ou par « Encaisser et facturer » au moment de la vente (modules/payments/services/off-site-sale-invoice.service.ts#invoiceOffSiteSale). Une vente soldée reçoit sa facture de vente. Sinon, chaque encaissement reçoit sa facture d’acompte. Si la facture échoue, la vente reste enregistrée.
store-invoice.ts#issueStoreInvoice refuse une commande qui n’est pas du magasin, qui est anonymisée ou annulée, ou qui n’est pas soldée. Il émet d’abord les avoirs des corrections d’encaissement (invoice.ts#ensureCorrectionCreditNotes). L’ERP ne signale une facture due au magasin que pour une clientèle professionnelle, et jamais pour une vente annulée (shared/lib/invoice-owed.ts#isInvoiceOwed).
Quand un incident a laissé des documents en route, modules/payments/services/missing-documents.service.ts#issueMissingDocuments les reprend. Il le fait dans l’ordre, et il ne refait pas ce qui est déjà fait :
- Les avoirs à reprendre.
- Les avoirs de remboursements retombés à annuler.
- Les avoirs des corrections.
- La facture de vente, si elle est due.
- Les avoirs des remboursements qui n’en ont pas encore.
- L’archivage, puis l’envoi.
L’acompte et le solde
Une facture d’acompte correspond à un encaissement du magasin (invoice.ts#ensureDepositInvoice). Elle est refusée une fois la facture de vente émise. Elle est refusée aussi pour l’encaissement qui solde la vente, parce que celui-là reçoit la facture de vente. La base exige qu’une facture d’acompte cite son encaissement et qu’elle ne remplace aucune pièce (Invoice_deposit_check).
Pour sa TVA, on prend la part de la ventilation de la vente qui correspond au cumul encaissé. On en retire celle du cumul précédent, et on répartit au plus fort reste (payment-vat.ts#paymentVatBreakdown). La même fonction calcule la TVA des encaissements pour la comptabilité. Une fois que tout est encaissé, la somme des parts retombe exactement sur la TVA de la vente.
La facture de vente reprend toutes les lignes, puis elle déduit chaque acompte facturé, net de ses avoirs (« FA-…, net de l’avoir AV-… », invoice-document-data.ts#depositLabelOf).
Les factures rectificatives
Il y a quatre corrections qui remplacent une facture par une autre, sans avoir.
- La correction de l’identité facturée (nom, société, SIREN, adresse) passe par
modules/payments/services/billing-correction.service.ts#correctBilling. Elle n’est admise que sur une commande soldée, non anonymisée, dont les documents sont archivés. Elle exige le SIREN d’une société française. Elle est refusée dès que la vente a des factures d’acompte : elles garderaient l’ancienne identité, et la facture de la vente les reprendrait sous la nouvelle. S’il n’y a pas encore de facture, il n’y a que la commande qui change. Sinon, une facture rectificative est émise sous le verrou de la commande (invoice.ts#rectifyInvoicedOrder), et la commande garde la date de correction (billingCorrectedAt). - La correction du prix ou de la TVA d’une vente du magasin passe par
modules/payments/services/price-correction.service.ts. Elle est refusée si la vente est annulée ou pas encore facturée. Elle est refusée si la vente a déjà un remboursement, un avoir ou un litige. Et elle est refusée si la période de TVA est déclarée ou l’exercice exporté (modules/payments/services/price-correction.service.ts#assertOpenPeriods). La base fige les montants d’une commande facturée. La correction n’a le droit de les changer que dans sa propre transaction. Et à la validation, un trigger différé vérifie que la rectificative a bien été émise dans cette transaction (invoice.ts#openPriceCorrection,Order_price_correction_check). La copie de la rectificative s’écrit dans la même transaction, et elle refuse tout résidu d’arrondi. - La correction du nom ou de l’adresse de livraison d’une commande déjà facturée passe par
modules/payments/services/shipping-address.service.ts#correctShippingAddress. La facture imprime l’adresse de livraison, donc elle est remplacée par une rectificative aux mêmes montants (modules/payments/services/order-rectification.ts#correctPrintedFields). Un retrait au magasin n’imprime pas d’adresse de livraison, et ne passe pas par là. - Le changement de variante d’une ligne déjà facturée passe par
modules/orders/services/order-item-variant.service.ts#changeOrderItemVariant. La rectificative porte la nouvelle variante, aux mêmes montants (invoice.ts#rectifyInvoicedOrder).
Les avoirs
L’avoir d’un remboursement (invoice.ts#ensureCreditNote) cite la facture de vente en vigueur. S’il n’y en a pas, il cite une facture d’acompte dont le reste couvre le montant, de préférence celle du même encaissement. Pour un remboursement Stripe, l’avoir n’est émis qu’une fois le remboursement abouti. Ensuite il s’archive et il part au client (credit-note-delivery.ts#sendCreditNote). Au magasin, quand on rembourse ce qui n’a jamais été facturé, il n’y a pas besoin d’avoir. S’il n’y a aucune pièce à citer, l’avoir est retenu et l’équipe est alertée.
L’avoir sans remboursement, c’est un geste commercial (standalone-documents.ts#issueCreditOnlyNote), et il ne se fait qu’au magasin. Il est plafonné ligne par ligne, ou taux par taux sur une facture d’acompte. Son total ne dépasse pas ce que le client doit encore (ABOVE_DUE), et il réduit ce dû (packages/domain/src/store-collection.ts#creditedCentsOf). La base exige qu’un avoir sans remboursement ait un total négatif (Invoice_type_refund_check).
Quand un remboursement retombe (abouti, puis échoué ou annulé chez Stripe), une facture annule son avoir pour le montant exact (standalone-documents.ts#rebillFallenCreditNote). Si cette facture ne peut pas s’émettre, le prochain remboursement doit reprendre exactement le même montant ou les mêmes pièces. Dans ce cas, il reprend à son compte l’avoir resté en vigueur, et il n’en émet pas un second (shared/lib/refund-guards.ts#creditNoteAdoption).
Pour la TVA d’un avoir partiel (credit-note-pieces.ts#refundedVatEntries), ça dépend du remboursement. Un remboursement total reprend la ventilation de la facture. Un remboursement par pièces prend le taux de chaque ligne, et le port prend le sien. Un remboursement en montant se répartit au prorata de ce qui reste par taux, au plus fort reste. Sur un acompte, l’avoir suit la ventilation de cet acompte.
Pour les arrondis, la TVA comprise dans un montant se calcule sur sa valeur absolue. Comme ça, un avoir reprend au centime la TVA de la facture qu’il annule (packages/domain/src/vat.ts#vatPartOfTtcCents). Le reste d’une ventilation se répartit au plus fort reste (invoice-vat-breakdown.ts#buildVatBreakdown).
Une pièce qui ne se retouche pas
La facture porte l’identité du vendeur, les adresses de l’acheteur et de livraison, ses lignes et ses totaux. Du coup, on peut la relire sans la commande ni le catalogue. Le numéro, la date et le vendeur s’écrivent à l’émission. L’acheteur, les lignes et les totaux s’écrivent une fois, avec le PDF, à l’archivage. Ensuite, la base refuse de changer ce qui fait sa valeur et refuse toute suppression (Invoice_guard_update, Invoice_guard_delete). Seuls la date d’envoi et le remboursement repris par un avoir se complètent après.
Le PDF est scellé. On le range dans un stockage privé avec l’empreinte SHA-256 de ses octets. Avant de le rendre, l’ERP recalcule l’empreinte et refuse une archive altérée (invoice-integrity.ts). La facture porte aussi ses données structurées, au format CII (cii-invoice.ts).
Les encaissements sont chaînés. Chaque encaissement et chaque remboursement reçoit un numéro d’ordre et une empreinte chaînée à la précédente. Des clôtures quotidiennes, mensuelles et annuelles reprennent la dernière empreinte, et la veille alerte si un maillon est rompu (modules/payments/services/cash-closure.service.ts). L’étude de cas Des encaissements qui ne se retouchent pas explique pourquoi.
Déclarer et exporter
La TVA se déclare par période, une déclaration à la fois (modules/payments/services/accounting-declaration.service.ts). Une période ne se fige qu’après quelques jours. Stripe peut relivrer un événement manqué après coup, et l’encaissement qu’il porte garde la date de l’événement. Une fois déclarée, la période ferme les gestes qui la changeraient : une vente datée dans cette période, une correction de prix, l’annulation d’un remboursement consigné.
L’exercice s’exporte pour le comptable (fiscal-year-export.service.ts, accounting-export.service.ts). Les écritures (journaux des ventes et des encaissements, fichier des écritures comptables) ne sont pas stockées. Elles se calculent à l’export, à partir des pièces (modules/payments/lib/ledger-entries.ts#ledgerOf, #fecFileOf). Un exercice exporté se ferme comme une période déclarée.
Les limites
- Les émissions d’une même série passent l’une après l’autre, sous le verrou du compteur. Au volume d’un magasin, ça ne se voit pas.
- Beaucoup de gestes attendent que les documents de la commande soient archivés (
UNARCHIVED), parce que la copie de la facture s’écrit avec son PDF. - Il n’y a pas d’écriture d’opération diverse. Toute correction passe par une nouvelle pièce, et le comptable reçoit des écritures calculées.
- Une commande anonymisée ne reçoit plus ni facture ni avoir, et la correction revient au comptable.