Envoyer une demande avec l'API REST

Il vous faut un formulaire publié. Ce guide utilise celui construit dans Construire un formulaire avec un agent IA : nom de l’entreprise, e-mail de contact, numéro de TVA, une question oui ou non sur les conditions de paiement, et un téléversement de fichier. Chaque méthode et option utilisée ici est décrite dans Méthodes API.

1. Créez un token API

Dans formbase, ouvrez OAuth et clés API dans la barre latérale de l’espace de travail et créez un token. La valeur n’est affichée qu’une fois. Gardez-la dans une variable d’environnement, pas dans votre code :

export FORMBASE_TOKEN='fb_...'

Un token n’atteint que l’espace de travail dans lequel il a été créé. Chaque appel ci-dessous est un POST vers la même URL avec le token dans l’en-tête Authorization ; le corps nomme la méthode et ses paramètres.

2. Trouvez l’ID du formulaire

Ouvrez le formulaire dans l’éditeur. L’ID du formulaire est la partie de l’adresse après /forms/ :

https://app.formbase.so/<workspace ID>/forms/jx75hdx8vb5hy1x85gm17nqgkn8f674g/edit

Les commandes ci-dessous utilisent l’ID de formulaire de ce guide. Mettez le vôtre à sa place.

3. Listez les clés de champ

Une demande remplit des questions, et les réponses reviennent, par clé de champ. Demandez au formulaire ses clés plutôt que de les deviner à partir des titres :

curl -X POST https://api.formbase.so/api/v1 \
  -H "Authorization: Bearer $FORMBASE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"method": "fields.list", "params": {"formId": "jx75hdx8vb5hy1x85gm17nqgkn8f674g"}}'

La réponse liste chaque question du formulaire publié. Raccourcie :

{
  "ok": true,
  "data": {
    "published": true,
    "items": [
      { "key": "company_name", "type": "text", "title": "Company name", "required": true, "prefillable": true },
      { "key": "contact_email", "type": "email", "title": "Contact email", "required": true, "prefillable": true },
      { "key": "vat_number", "type": "text", "title": "VAT number", "required": false, "prefillable": true },
      {
        "key": "do_you_accept_our_30_day_payment_terms", "type": "radio", "title": "Do you accept our 30-day payment terms?", "required": true, "prefillable": true,
        "options": [{ "key": "yes", "label": "Yes" }, { "key": "no", "label": "No" }]
      },
      { "key": "certificate_of_incorporation", "type": "file", "title": "Certificate of incorporation", "required": true, "prefillable": false }
    ],
    "hasMore": false
  }
}

Pour préremplir une question à choix, envoyez la key de l’option, ici “yes”, pas son libellé. Une question avec prefillable: false, comme le téléversement de fichier, seul le destinataire peut y répondre. Les autres indicateurs sont expliqués sous fields.list.

4. Créez une demande de test

Envoyez la demande à Ada Lovelace, avec le nom de l’entreprise rempli et verrouillé. test: true en fait une demande de test : elle n’envoie jamais d’e-mail à personne et ne compte nulle part, vous pouvez donc répéter cette étape aussi souvent que vous voulez, avec un nouveau idempotencyKey à chaque fois.

curl -X POST https://api.formbase.so/api/v1 \
  -H "Authorization: Bearer $FORMBASE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "requests.create",
    "params": {
      "formId": "jx75hdx8vb5hy1x85gm17nqgkn8f674g",
      "recipient": { "email": "ada@acme.example", "name": "Ada Lovelace" },
      "prefill": { "company_name": "Analytical Engines Ltd" },
      "readonly": ["company_name"],
      "externalId": "supplier-2043",
      "idempotencyKey": "supplier-2043",
      "test": true
    }
  }'

• prefill remplit des réponses que le destinataire peut encore modifier. Une clé dans readonly est aussi verrouillée.

• externalId est votre propre id pour cette tâche, comme un numéro de fournisseur. Il revient sur chaque lecture et chaque callback.

• idempotencyKey rend une nouvelle tentative sûre. Si votre code envoie le même appel deux fois, formbase renvoie la première demande avec deduplicated: true au lieu d’en créer une seconde.

La réponse porte l’ID de la demande et le lien pour le destinataire :

{
  "ok": true,
  "data": {
    "id": "m17ayhcnj9xvzkff3atek49bdd8f6872",
    "status": "pending",
    "url": "https://form.formbase.so/r/rq_...",
    "deliveryStatus": "not_requested",
    "externalId": "supplier-2043",
    "deduplicated": false,
    "createdAt": 1790539225370,
    "expiresAt": 1793131225370
  }
}

deliveryStatus: “not_requested” signifie que formbase n’a envoyé aucun e-mail ; vous livrez le lien vous-même. Pour que formbase envoie l’invitation et les rappels, ajoutez “delivery”: “email”, ce qui nécessite un plan Pro ou Business. Voir Invitations, rappels et expiration. Si le formulaire a Send reminders activé, une vraie demande avec un e-mail de destinataire reçoit quand même les rappels programmés ; ajoutez “reminders”: [] pour n’en envoyer aucun.

5. Complétez-la et lisez les réponses

Ouvrez url dans un navigateur. Le nom de l’entreprise est rempli et verrouillé ; répondez au reste et soumettez. Puis relisez la demande avec son ID :

curl -X POST https://api.formbase.so/api/v1 \
  -H "Authorization: Bearer $FORMBASE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"method": "requests.get", "params": {"requestId": "m17ayhcnj9xvzkff3atek49bdd8f6872"}}'

Une fois que status vaut completed, la réponse porte deux maps indexées par clé de champ. answers est pour le code : une réponse à choix est la clé de l’option, une réponse fichier est une liste de fichiers avec des liens de téléchargement. display est pour les humains : des libellés et des noms de fichiers.

"answers": {
  "company_name": "Analytical Engines Ltd",
  "do_you_accept_our_30_day_payment_terms": "yes",
  "certificate_of_incorporation": [{ "name": "certificate-of-incorporation.pdf", "type": "application/pdf", "size": 635, "url": "https://api.formbase.so/api/storage/..." }]
},
"display": {
  "company_name": "Analytical Engines Ltd",
  "do_you_accept_our_30_day_payment_terms": "Yes",
  "certificate_of_incorporation": "certificate-of-incorporation.pdf"
}

Redemander sans cesse jusqu’à ce que le statut change fonctionne pour un test, mais pas en production. Donnez à la demande une callbackUrl et formbase vous appelle quand elle se termine ; le guide suivant met ça en place.

Suite