# Démarrer avec Heartwood en moins de 10 minutes

> Périmètre actuel (21/07/2026) : génération Factur-X, validation, rule
> packs (Epic 1), documentation (Epic 2), validateur public (Epic 3),
> comptes/facturation self-service (Epic 4).

## 1. Créer un compte et obtenir une clé Découverte (2 min)

Inscription self-service, sans contact humain (FR-9) :

```bash
curl -X POST "https://api.example/signup" \
  -H "Content-Type: application/json" \
  -d '{"email": "vous@exemple.fr", "password": "un-mot-de-passe-suffisamment-long"}'
# {"accountId": "...", "apiKey": "fxk_...", "message": "compte créé — vérifiez votre e-mail pour activer la clé (FR-9)"}
```

La clé est créée mais **inactive** tant que l'e-mail n'est pas confirmé.
Cliquez le lien reçu par e-mail (`GET /verify?token=...`) pour l'activer.
Le palier Découverte inclut `[ASSUMPTION]` 20 documents/mois, sans carte
bancaire — voir la page [comptes et facturation](./comptes-facturation.md)
pour le détail des paliers.

Vous gérez ensuite vos clés et votre consommation dans l'espace client
server-rendered : `https://api.example/account/` (connexion par
e-mail/mot de passe).

## 2. Premier appel : valider un document (2 min)

```bash
curl -X POST "https://api.example/v1/validate" \
  -H "Authorization: Bearer $FACTURX_API_KEY" \
  --data-binary @ma-facture.xml
```

Réponse : un verdict `conforme: true|false`, **toujours accompagné du rule
pack appliqué** — jamais une promesse de conformité réglementaire absolue.
Depuis Story 3.7, `schematronChecked: true` pour les profils Factur-X
`EN16931` et `EXTENDED-CTC-FR` (référentiel officiel FNFE-MPE, règles BR-*
réelles) — voir la page réglementation pour le détail de ce que cela
couvre aujourd'hui.

## 3. Générer une facture Factur-X (5 min)

```bash
curl -X POST "https://api.example/v1/generate/facturx?profile=EN16931" \
  -H "Authorization: Bearer $FACTURX_API_KEY" \
  -H "Content-Type: application/json" \
  -d @ma-facture.json \
  -o facture.pdf
```

Voir [`web/docs/examples/`](./examples/) pour des exemples complets par
langage (curl, PHP, Python, JS, Go).

## Erreurs courantes

| Code | Signification | Action |
|---|---|---|
| 401 | Clé absente ou invalide | Vérifier l'en-tête `Authorization: Bearer ...` |
| 422 | Facture incomplète | Le corps `missing[]` liste les champs manquants par leur code BT-* |
| 400 | Profil ou rule pack inconnu | `profile` doit être `EN16931` ou `EXTENDED-CTC-FR` |
| 413 | Document > 20 Mo | Rejeté avant tout traitement |
| 429 | Quota Découverte dépassé (20 documents/mois `[ASSUMPTION]`) | Attendre la réinitialisation (date fournie dans `detail`) ou souscrire un palier payant sur `/account/` |
| 409 | `Idempotency-Key` réutilisée avec un corps différent | Utiliser une nouvelle `Idempotency-Key` pour un nouveau corps (voir [comptes et facturation](./comptes-facturation.md#idempotence)) |

## Spécification complète

`GET /v1/openapi.json` — spécification OpenAPI 3.0.3 à jour, synchronisée
avec l'implémentation par des tests de contrat en CI.