Passer au contenu
English formerie.com
formerie.com English

Référence de l’API

URL de base :

Text
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 :

Text
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.

Voir en Markdown