Étape 2 — La facturation

Surprise pour les novices : les factures ne sont pas créées quand l'acheteur paie, mais dès l'assignation. Elles servent justement à demander le paiement.

Les 8 types de documents (docTypes)

Le système ne connaît qu'un seul objet « Invoice », décliné en 8 types :

⭐ Facturation simple vs facturation double

C'est LA distinction à maîtriser. Elle est déterminée par l'invoiceMode du contrat du vendeur.

📄 Facture SALES : Vendeur → Acheteur
   ├── ligne(s) : prix d'adjudication du/des lot(s)
   └── ligne(s) : frais acheteur (intégrés dans la même facture, marqués par un feesType)

📄 Facture SALES : Vendeur → Acheteur
   └── uniquement le prix d'adjudication du/des lot(s)
📄 Facture BUYER_FEES : Shop → Acheteur
   └── uniquement les frais acheteur

📄 Facture SALES : Shop (commissaire-priseur) → Acheteur
   └── prix d'adjudication + frais, tout compris
📄 Bordereau INVOICE_SLIP : Vendeur → Shop
   └── le vendeur « vend » au shop les lots adjugés (document établi par la plateforme)
📄 Facture COMMISSION : Shop → Vendeur (sa rémunération)

L'autofacturation (selfBilling) et le mandat de facturation

En courtage (simple comme double), la facture SALES est juridiquement une facture du vendeur… mais c'est la plateforme qui l'émet à sa place. C'est l'autofacturation (mécanisme légal où un tiers, ici la plateforme, émet la facture au nom et pour le compte du vendeur, sur la base d'un mandat de facturation signé au contrat), autorisée par le paramètre de contrat INVOICING_MANDATE. Le PDF porte la mention correspondante, et la facture reçoit en plus un numéro de facture vendeur dans sa propre séquence (voir numérotation).

Comment les factures sont créées : createInvoicesFromSeance

À l'assignation (circuit V2), le book-keeper reçoit la séance et la liste d'items à facturer, puis :

1. Validation : la séance existe, les items sont facturables ;
2. Groupage : les items sont regroupés par contrat + vendeur + acheteur + bon de commande + code service (groupItemsByContractSellerBuyer). Chaque groupe = une facture. Un acheteur qui remporte 3 lots du même vendeur reçoit donc une seule facture à 3 lignes ;
3. Création selon le mode : intermediationInvoice() (simple/double) ou auctioneerInvoice() ;
4. Lignes & totaux : construction des lignes depuis les items (buildInvoiceLinesFromItem), calcul des totaux et de la TVA (computeTotalPrices) ;
5. Références : numéro de facture + référence de paiement générés ;
6. Enregistrement en base (PostgreSQL), statut initial TO_VALIDATE, puis validation (action INVOICE) → statut INVOICED et envoi à l'acheteur.

La facture de commission et le bordereau

Une fois la vente confirmée vient la rémunération de la plateforme :

• La facture COMMISSION est créée à partir des factures SALES (action COMMISSION du workflow, automatique si COMMISSION_CREATE_AUTO). Elle est découpée par bon de commande / code service : un groupe = une facture de commission, pour que chaque commission reste rattachée à un seul ensemble de ventes ;
• Le INVOICE_SLIP (bordereau) est créé pour les circuits où le shop encaisse pour le compte du vendeur : il matérialise « le vendeur facture le shop » (associations : SELLER = le vendeur, BUYER = l'organisation créatrice du shop).

La numérotation des factures

Trois systèmes de numéros cohabitent — c'est souvent source de confusion :

Le cycle de vie d'une facture

Comme les items, chaque facture suit un workflow d'actions. Voici le parcours d'une facture SALES :

flowchart LR
  a["TO_VALIDATE"] --> b["INVOICED"]
  b --> c["PAID"]
  c --> d["CONFIRMED"]
  d --> e["COMMISSIONED"]
  e --> f["SUBMITTED / EXECUTED"]
  f --> g["SETTLED"]

Sorties possibles : CANCELED (annulée avant paiement), NOT_PAID (impayé constaté), REIMBURSED (remboursée après paiement).

Le PDF et l'envoi

Chaque facture validée génère un PDF à partir de templates Handlebars, choisi selon le contexte : facture classique (invoice-v2-1f / invoice-v2-2f multi-taux), invoice-proforma (avant officialisation), invoice-intra (intracommunautaire), invoice-export, invoice-commission, invoice-receipt (reçu). Le PDF inclut les adresses et horaires d'enlèvement (pickupLines), les coordonnées bancaires du shop et les conditions de paiement. Il est stocké (service documents) et envoyé par email à l'acheteur ou au vendeur.