Ventes & Facturation

Périmètre : clients, devis, commandes, factures, avoirs, règlements, fournisseurs (devis/commandes/factures/règlements miroir), entités de facturation, modes de paiement, comptabilité opérationnelle et e-invoicing (réforme FR 2026/2027 — provider : Agicap).

Vocabulaire & entités

Le modèle complet est dans docs/04-data-model.md §8. La comptabilité analytique (plan comptable, nature de prestation, clôture FNP/CCA/CAP) fait l'objet d'un domaine dédié : docs/23-domain-accounting.md.

Écrans

Modèle de données (points clés)

• Invoice.number : alloué sous verrou consultatif Postgres (pg_advisory_xact_lock) à la transition DRAFT → ISSUED. Jamais avant. Test de concurrence validé : 12 émissions parallèles → FAC-1…FAC-12, sans trou ni doublon.
• Format numéro : {prefix}{sequence} — concaténation brute du préfixe (BillingEntity.invoiceNumberPrefix, défaut FAC-) et du compteur entier (BillingEntity.invoiceSequence), sans année ni zéro de remplissage — ex. FAC-1, FAC-42. Pas de reset annuel : le compteur est monotone sur toute la vie de l'entité.
• Invoice.facturXProfile : stocké à l'émission (audit). PDF/A-3 + XML CII embarqué généré via xmlbuilder2 ; validation XSD via libxmljs2.
• EInvoiceSubmission : relation 1-N avec Invoice (plusieurs tentatives, champ attemptNumber). Contrainte @@unique([invoiceId, attemptNumber]).
• SupplierInvoice.accountingCodeId + fiscalYear : contrôle bloquant pour la clôture — une facture fournisseur validée doit impérativement porter ces deux champs.
• SupplierInvoiceAllocation : ventilation multi-contrats d'une charge réseau — la somme des lignes doit égaler totalHt de la facture.
• EReportingSubmission : contrainte d'unicité (organizationId, yearMonth, type) ; statuts DRAFT → SUBMITTED → ACCEPTED / REJECTED.
• Quote.publicToken : clé signée pour la page d'acceptation publique /q/[token] ; hors authentification.
• SupplierEInvoiceReceipt : idempotence à la réception inbound — dédup par (provider, externalInvoiceId).

API

Ventes

Achats (miroir)

Facturation électronique (Agicap)

Exemple de référence d'endpoint :

curl -s -X POST "$API/api/workspace/invoices/$ID/issue" \
  -H "Cookie: $SESSION"

{
  "id": "inv_…",
  "number": "FAC-42",
  "status": "ISSUED",
  "facturXProfile": "EN16931",
  "issueDate": "2026-06-16T10:00:00Z"
}

Comptabilité opérationnelle

Workflows

Cycle vente standard

Opportunity (CRM)
   │
   └─→ Quote (DRAFT) → SENT → ACCEPTED → CONVERTED
                                              │
                                         Order (CONFIRMED)
                                              │
                                         SHIPPED → RECEIVED
                                              │
                                         Invoice (DRAFT) → ISSUED → PARTIALLY_PAID → PAID
                                                                  ↘ OVERDUE   ↘ CANCELED

Statuts de facture (InvoiceStatus) : DRAFT, ISSUED, PARTIALLY_PAID, OVERDUE, PAID, CANCELED. PARTIALLY_PAID/PAID sont posés par les encaissements (Payment) ; OVERDUE par le job d'échéance ; CANCELED par un avoir total.

À l'émission (DRAFT → ISSUED) : contrôle des mentions FR 2026 (422 si incomplet), puis advisory lock, numérotation légale irréversible et génération Factur-X — le tout atomique. La soumission Agicap n'est pas déclenchée par l'émission : elle se fait via POST …/invoices/[id]/submit-einvoice.

Numérotation légale (garde-fou)

Séquence par BillingEntity (compteur invoiceSequence, monotone, sans segmentation par année ni par type et sans reset annuel). Le numéro est consommé une seule fois, à la transition vers ISSUED. Toute tentative d'émission concurrente attend la libération du verrou (pg_advisory_xact_lock). La suppression d'une facture ISSUED est interdite — seule une annulation avec création d'avoir total est possible.

Facturation électronique B2B — réforme FR

Pulse ERP vise la conformité complète (émission + réception + e-reporting) au 1ᵉʳ septembre 2026, indépendamment du seuil par BillingEntity.

Workflow émission (Agicap, Phase 7 — livré) :

1. Facture ISSUED → génération Factur-X (XML CII + PDF/A-3).
2. Contrôle bloquant des mentions obligatoires FR 2026 (SIREN client, adresse livraison, nature opération, option TVA sur débits).
3. Résolution du destinataire (SIREN/SIRET → identifiant Agicap/Peppol).
4. Soumission API Agicap → EInvoiceSubmission.providerInvoiceId.
5. Suivi cycle de vie via webhook HMAC POST /api/webhooks/einvoicing/agicap — statuts : SUBMITTED → RECEIVED_BY_PDP → DEPOSITED → RECEIVED_BY_RECIPIENT → APPROVED / REFUSED / IN_DISPUTE / PAID / REJECTED_BY_PDP.
6. En cas de rejet/refus : re-soumission via POST …/invoices/[id]/resubmit-einvoice (incrémente attemptNumber).

Workflow réception inbound : webhook POST /api/webhooks/einvoicing/agicap-inbound → parser CII (cii-parser.ts) → matching fournisseur par SIREN → création SupplierInvoice status RECEIVED. Idempotence via SupplierEInvoiceReceipt.

Relances impayés (module recouvrement)

Le recouvrement n'est pas porté par la facture (pas de champ lastReminderSentAt/reminderCount, pas de …/invoices/[id]/reminder) mais par le module dunning dédié (Dunning, /api/workspace/dunnings).

• Job detect-overdue-invoices : itère sur les organisations actives et crée un Dunning par facture échue impayée (idempotent — un seul dossier par Invoice, RG-01-01).
• Workflow d'étapes (DunningStep, RG-01-02) : NONE → RELANCE_1 → RELANCE_2 → MED → LEGAL, avancé via POST …/dunnings/[id]/advance. Les délais entre étapes sont configurables par organisation (dunningStep2DelayDays, dunningMedDelayDays, dunningTransferDelayDays).
• Horodatage par étape : relance1SentAt, relance2SentAt, medSentAt ; accusés via …/dunnings/[id]/track-ack.
• Transition MED → LEGAL (transmission au juridique) séparée et irréversible (sauf LEGAL_RETURNED, RG-01-06). Résolution/annulation via …/dunnings/[id]/resolve et …/dunnings/[id]/cancel.

E-reporting périodique

POST /api/workspace/einvoicing/ereporting/generate — body { yearMonth, type } (types : TRANSACTIONS, PAYMENTS, B2C). Soumission via …/[id]/submit. Contrainte d'unicité (organizationId, yearMonth, type) évite les doubles envois.

Règles métier

• Numérotation sans trou, immuable, par BillingEntity — obligation légale FR. Advisory lock Postgres à chaque émission.
• Date facture = date d'émission = date où la facture passe ISSUED. Non modifiable après.
• TVA multi-taux dans une facture (5,5 %, 10 %, 20 %). Auto-liquidation pour clients intra-UE (mention obligatoire + vérification VIES).
• Facture > 5 € HT : mentions légales obligatoires (SIRET, N° TVA, conditions règlement, taux pénalité, indemnité 40 €).
• Avoir partiel : total avoirs ne peut pas dépasser le total facture. Avoir total → facture passe CANCELED.
• Paiement : ne peut pas dépasser le montant dû.
• Suppression facture ISSUED interdite ; soft delete sur DRAFT uniquement.
• 3-way match fournisseur : refus de paiement si écart > seuil (5 % ou montant absolu configurable).
• SupplierInvoice validée sans accountingCodeId ou fiscalYear : bloquant pour la clôture comptable.
• Ventilation SupplierInvoiceAllocation : somme des lignes doit égaler totalHt de la facture.

KPIs

CA HT MTD, YTD, comparatif N-1 · panier moyen · DSO global et par client · % factures payées dans les délais · encours > 30/60/90 jours · taux d'acceptation devis · cycle moyen Quote → Order → Invoice → Paid · TVA collectée / déductible / nette · marge brute par produit.

Notifications