Factures — Lecture + écriture (pas de suppression)

Gestion des factures émises. Pas de DELETE (rétention légale obligatoire en France : 10 ans Article L123-22 Code de Commerce).

Source : server/publicApi/routes/billing.ts:64-184. Schéma : insertInvoiceSchema dans shared/schema.ts.

Vue d'ensemble

Méthode	Path	Scope
GET	/invoices	invoices:read
GET	/invoices/:id	invoices:read
POST	/invoices	invoices:write
PATCH	/invoices/:id	invoices:write
DELETE	—	(non disponible)

Webhooks émis : invoice.created, invoice.updated, invoice.paid (status change → paid), invoice.sent (status change → sent).

Statuts canoniques

status	Description
draft	Brouillon, modifiable librement
sent	Envoyée au client (déclenche invoice.sent)
paid	Réglée (déclenche invoice.paid)
overdue	En retard de paiement
cancelled	Annulée (avoir séparé requis légalement)

Les statuts exacts dépendent du schéma — consultez GET /invoices/:id sur un existant.

Multi-tenant

Scoping via invoices.clientId → clients.agencyId.

---

GET /invoices

Liste paginée triée par createdAt DESC.

Query params

Param	Type	Description
limit	int	Défaut 50, max 100
offset	int	Offset

Réponse 200

{
  "data": [
    {
      "id": 1,
      "clientId": 42,
      "agencyId": 7,
      "invoiceNumber": "F-2026-0042",
      "status": "sent",
      "totalHt": "1000.00",
      "totalTtc": "1200.00",
      "issueDate": "2026-04-01T00:00:00.000Z",
      "dueDate": "2026-05-01T00:00:00.000Z"
    }
  ],
  "total": 142,
  "limit": 50,
  "offset": 0
}

---

POST /invoices

Création d'une facture. Le clientId doit appartenir à l'agence.

Body

Validé via insertInvoiceSchema.strict(). Dates acceptées en ISO 8601 (string) — converties serveur.

{
  "clientId": 42,
  "invoiceNumber": "F-2026-0042",
  "status": "draft",
  "totalHt": "1000.00",
  "totalTtc": "1200.00",
  "issueDate": "2026-04-27",
  "dueDate": "2026-05-27",
  "lines": [
    { "description": "Hébergement annuel", "quantity": 1, "unitPrice": "1000.00", "vatRate": "20" }
  ]
}

agencyId est résolu serveur. Si issueDate est omis, le serveur utilise new Date().

Webhook émis

invoice.created.

---

PATCH /invoices/:id

Mise à jour partielle. Le passage de status vers paid ou sent déclenche les webhooks dédiés.

Webhooks émis

• invoice.updated (toujours)
• invoice.paid (si status passe à paid)
• invoice.sent (si status passe à sent)

Exemple — marquer une facture comme payée

curl -X PATCH \
  -H "x-api-key: spk_..." \
  -H "Content-Type: application/json" \
  -d '{"status":"paid","paidAt":"2026-04-27T15:00:00.000Z"}' \
  https://beta.stormeo.io/api/public/v1/invoices/42

Pour rectifier une facture émise (statut sent ou paid), passez par un avoir (à émettre séparément). La modification post-envoi peut être contestable légalement.