# Comptes, paliers et facturation

> Statut au 21/07/2026 : self-service livré (Epic 4) — inscription,
> vérification e-mail, espace client, souscription/résiliation Stripe.
> Non livré : alertes de quota à 80%/100%, réconciliation comptable
> automatisée avec Stripe (voir Dev Notes de la Story 4.4).

## Parcours complet : créer un compte → clé Découverte → premier appel

1. **Inscrire un compte** — `POST /signup` avec email + mot de passe (8
   caractères minimum). Une clé Découverte est créée, mais **inactive**.
   Les domaines d'e-mails jetables courants sont refusés ; les créations de
   compte sont plafonnées par IP et par période (anti-abus, FR-9).
2. **Vérifier l'e-mail** — cliquez le lien reçu (`GET /verify?token=...`).
   La clé devient active immédiatement.
3. **Premier appel** — utilisez la clé reçue à l'étape 1 comme
   `Authorization: Bearer fxk_...` sur n'importe quel endpoint `/v1/*`.

Aucune action manuelle côté exploitant à aucune étape. Voir le [guide de
démarrage](./getting-started.md) pour les commandes complètes.

## Paliers

| Palier | Quota inclus | Prix `[ASSUMPTION]` | Dépassement |
|---|---|---|---|
| Découverte | 20 documents/mois `[ASSUMPTION]` | Gratuit | **Bloqué** (HTTP 429) — jamais d'overage sur le gratuit |
| Starter | 200 documents/mois `[ASSUMPTION]` | 29 €/mois `[ASSUMPTION]` | Overage +20 % du prix unitaire `[ASSUMPTION]` |
| Pro | 1 000 documents/mois `[ASSUMPTION]` | 79 €/mois `[ASSUMPTION]` | Overage +20 % `[ASSUMPTION]` |
| Éditeur | 5 000 documents/mois `[ASSUMPTION]` | 199 €/mois `[ASSUMPTION]` | Overage +20 % `[ASSUMPTION]` |

Les montants et quotas marqués `[ASSUMPTION]` sont repris du PRD comme
hypothèses de lancement, **pas des décisions commerciales figées** — à
confronter au marché avant le jalon J3 (voir PRD, §4.6/FR-10). Sur un
palier payant, un dépassement de quota **n'est jamais bloquant** : les
documents au-delà du quota inclus sont facturés en overage, jamais
interrompus.

## Souscrire, changer de palier, résilier

Depuis l'espace client (`/account/`, connexion par e-mail/mot de passe) :

- **Souscrire ou changer de palier** : redirection vers **Stripe
  Checkout**, hébergé par Stripe — votre carte ne transite jamais par
  l'infrastructure Heartwood.
- **Gérer carte, factures, résiliation** : redirection vers le **Stripe
  Customer Portal**, exclusivement.
- Un changement de palier (upgrade, downgrade, résiliation) est répercuté
  sur le quota en **moins d'une minute** (traité par webhook Stripe vérifié
  par signature).
- Une résiliation ramène le compte au palier Découverte (pas de coupure
  brutale) : le quota de 20 documents/mois s'applique de nouveau.

## Idempotence

Les endpoints facturés (`POST /v1/generate/facturx`, `POST /v1/validate`)
acceptent un en-tête `Idempotency-Key` optionnel, lié au hash du corps de
la requête, sur une fenêtre de 24h :

- **Même clé API + même `Idempotency-Key` + même corps** rejoué : le
  document d'origine est renvoyé tel quel (en-tête
  `Idempotency-Replayed: true`), compté **une seule fois**.
- **Même clé API + même `Idempotency-Key` + corps différent** : HTTP
  **409**, rien n'est produit ni compté.

```json
{
  "type": "idempotency-key-conflict",
  "title": "Idempotency-Key déjà utilisée avec un corps différent",
  "status": 409,
  "detail": "réutilisez une nouvelle Idempotency-Key pour un corps différent (Annexe B PRD)",
  "instance": "01H..."
}
```

## Quota Découverte dépassé

```json
{
  "type": "quota-exceeded",
  "title": "Quota mensuel Découverte dépassé",
  "status": 429,
  "detail": "réinitialisation le 2026-08-01 — upgradez sur /account/ pour un palier sans quota fixe",
  "instance": "01H..."
}
```

Toutes les erreurs de cette page suivent le format
[RFC 7807](https://www.rfc-editor.org/rfc/rfc7807) (`application/problem+json`).