# Référence de l’API

URL de base :

```txt
https://api.formerie.com
```

Cette référence couvre les routes `/v1` de l’API. Les formulaires publics
hébergés, les intégrations et les noms d’hôte clients de l’environnement
d’exécution utilisent des routes épurées sur `https://forms.formerie.com` ou sur
des noms d’hôte clients vérifiés :

```txt
GET  /{workspaceHandle}/{formHandle}/schema
POST /{workspaceHandle}/{formHandle}/validate
POST /{workspaceHandle}/{formHandle}/submit
```

Les noms d’hôte clients liés à un espace de travail utilisent `/{formHandle}/schema`,
`/{formHandle}/validate` et `/{formHandle}/submit`. Les noms d’hôte liés à un
formulaire utilisent `/schema`, `/validate` et `/submit`.

## État du service

```http
GET /health
```

```json
{
  "ok": true,
  "service": "formerie-api",
  "version": "0.1.0"
}
```

## Soumettre un formulaire

Route canonique :

```http
POST /v1/{workspaceHandle}/{formHandle}
```

Route de l’API sur un nom d’hôte à votre marque :

```http
POST /v1/{formHandle}
```

Charge utile :

```json
{
  "fields": {
    "name": "Jane Example",
    "email": "jane@example.com",
    "message": "Hello"
  },
  "verificationToken": "token-from-client",
  "metadata": {
    "pageUrl": "https://example.com/contact",
    "idempotencyKey": "frontend-generated-random-uuid"
  }
}
```

Réponse lorsque la soumission est acceptée :

```json
{
  "ok": true,
  "submissionId": "uuid",
  "status": "accepted"
}
```

## Valider les champs

La validation vérifie les valeurs fournies sans enregistrer de soumission,
réserver de quota, vérifier de jetons CAPTCHA ni envoyer de courriel.

```http
POST /v1/{workspaceHandle}/{formHandle}/validate
POST /v1/{formHandle}/validate
```

## Schéma public

```http
GET /v1/{workspaceHandle}/{formHandle}/schema
GET /v1/{formHandle}/schema
```

Le point de terminaison du schéma public est volontairement sans danger pour les
navigateurs. Il expose les libellés des champs, les types, les indications de
validation, les exigences de vérification et les métadonnées publiques. Il
n’expose pas les destinataires, la configuration des fournisseurs, les règles de
livraison, les gabarits, les origines autorisées, les règles de limite de débit
ni les secrets.

La soumission finale demeure celle qui fait foi et valide le formulaire au
complet.

## Format des erreurs

```json
{
  "ok": false,
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "The submitted form contains invalid fields.",
    "fields": {
      "contact.email": [
        {
          "path": "contact.email",
          "code": "FIELD_EMAIL_INVALID",
          "message": "Invalid email address.",
          "rule": "email",
          "params": {}
        }
      ]
    },
    "issues": [
      {
        "path": "contact.email",
        "code": "FIELD_EMAIL_INVALID",
        "message": "Invalid email address.",
        "rule": "email",
        "params": {}
      }
    ]
  }
}
```

Les requêtes soumises à la limite de débit reçoivent une réponse HTTP `429` avec
le code d’erreur public `RATE_LIMITED`. Lorsqu’un en-tête `Retry-After` est
présent, les clients devraient attendre au moins ce nombre de secondes avant une
nouvelle tentative. Ne relancez pas les soumissions en boucle serrée; affichez
plutôt au visiteur un état de nouvelle tentative rassurant.