# Documentation et référence de l’API

> Où trouver quoi : l’aide de l’application, la référence de l’API et les guides pour brancher vos tests. Les trois existent en français et en anglais.
> https://facteur.eu/documentation

## Trois documentations, et laquelle ouvrir

L’aide de l’application, la référence de l’API et les guides d’intégration répondent chacune à une question différente. L’aide est sur ce site, la référence et les guides sur developers.facteur.eu.

## Ce que contient chacune

Vous en ouvrez une selon ce que vous faites : cliquer dans l’application, écrire le code qui appelle l’API, brancher ce code sur votre suite de tests.

#### Aide de l’application

Créer une inbox, l’adresse qui reçoit les emails déclenchés par vos tests. Puis lire un message, comprendre un quota atteint, inviter un collègue, brancher le SSO, récupérer un second facteur perdu. Écran par écran.

#### Référence de l’API

Chaque route de /v1 : ses champs, ses codes d’erreur, ce qu’une clé doit avoir le droit de faire pour l’appeler, et ce que l’API refuse quelle que soit la clé. Elle est produite à partir du document OpenAPI de l’API, et ne peut donc pas décrire une route que le service ne sert pas.

#### Guides d’intégration

Le chemin du premier appel : une clé, une inbox, un message reçu, une assertion qui passe. Puis l’authentification, la forme des erreurs, l’attente côté serveur qui remplace vos boucles de relance, et la reprise d’une suite écrite pour Mailosaur.

## Je veux…

Si vous savez ce que vous voulez faire mais pas où c’est écrit, partez d’ici. Et si votre besoin manque à la liste, écrivez-nous : c’est une page qu’il nous reste à écrire.

- Je veux…
- C’est écrit

- voir un test lire un vrai email, avant d’écrire le mien
- recevoir un message dans mes tests et lire le code qu’il contient
- installer un paquet dans Playwright ou Cypress plutôt qu’appeler l’API
- connaître les champs exacts d’une réponse, ou le sens d’un code d’erreur
- créer une clé d’API et savoir ce qu’elle peut atteindre
- comprendre un quota atteint, ou changer la rétention d’une inbox
- inviter un collègue, cloisonner un espace de travail, brancher le SSO
- reprendre une suite de tests écrite pour un autre fournisseur
- savoir ce que ça coûte, et à partir de quel volume
- savoir où sont mes données et ce que le DPA engage
- savoir si le service répond en ce moment

## Ce qui est traduit, et ce qui ne l’est pas

- Les trois existent en français et en anglais. Choisissez la vôtre en haut de page : le portail des développeurs retient votre choix et vous sert les pages suivantes dans cette langue.
- Ce que vous lisez est traduit, ce que vous tapez ne l’est jamais. Un nom de champ, un chemin comme /v1/inboxes, un code d’erreur comme quota_exceeded s’écrivent en anglais dans les deux versions : c’est ce que l’API attend, et ce qu’elle renvoie.
- Les messages d’erreur de l’API arrivent en anglais, quelle que soit la langue dans laquelle vous lisez. Branchez vos tests sur le champ error.code, jamais sur la phrase qui l’accompagne : le code ne change pas, la phrase peut être réécrite.