w.c.s. › API »

Complétion et modification d'un formulaire

w.c.s expose une API autorisant les logiciels tiers à transmettre des données structurées permettant la complétion d'un formulaire ou la modification d'un formulaire existant.

Complétion d'un formulaire

La complétion d'un formulaire se fait par une requête POST à l'adresse /api/formdefs/slug/submit, le contenu de la requête doit être un dictionnaire contenant obligatoirement un attribut data et optionnellement un attribut meta et un attribut context.

L'attribut data est obligatoire et contient un dictionnaire dont les clés sont les identifiants des champs du formulaire (ou leur nom de variable) et les valeurs le contenu de ces champs.

  • Les champs de type simple tels que « Texte », « Texte long » ou « Courriel » sont des chaînes de caractères.

  • Les champs de type « Date » sont des chaînes de caractères au format ISO-8601, i.e. YYYY-MM-DD.

  • Les champs de type « Fichier » sont des dictionnaires contenant les clés filename pour le nom de fichier et content pour le contenu de celui-ci, encodé en base64.

  • Les champs de type « Carte » sont des dictionnaires contenant les clés lat pour la latitute en nombre décimal et lon pour la longitude en nombre décimal.

L'attribut meta est optionnel et contient une série de paramètres supplémentaires concernant le formulaire.

Métadonnées

draft

true pour enregistrer le formulaire comme étant un brouillon.

backoffice-submission

true pour enregistrer le formulaire comme étant saisi depuis le backoffice.

L'attribut context est également optionnel et contient une série de renseignements supplémentaires sur le contexte de l'envoi du formulaire. Les attributs reconnus sont channel, thumbnail_url, user_id et comments.

L'exemple suivant complète un formulaire d'inscription à une newsletter, qui demanderait trois champs : prénom (nom de variable prenom), nom (nom de variable nom) et adresse électronique (nom de variable email).

$ curl -H "Content-type: application/json" \
       -H "Accept: application/json" \
       -d@donnees.json \
       https://www.example.net/api/formdefs/newsletter/submit
{"err": 0, "data": {"id": "1"}}
  

Le fichier de données utilisé (donnees.json) contient le dictionnaire JSON suivant :

{
  "data": {
     "prenom": "Marc",
     "nom": "L.",
     "email": "marc@example.net"
  }
}
  

Modification d'un formulaire

Un formulaire qui peut être modifié (par la présence d'une action de workflow de type « Permettre l'édition ») peut également être modifié via un appel à l'API, en faisant un POST sur l'adresse du formulaire.

Les données attendues sont similaires à la création d'un nouveau formulaire, seuls les champs présents seront pris en compte.

Cet appel :

$ curl -H "Content-type: application/json" \
       -H "Accept: application/json" \
       -d@donnees.json \
       https://www.example.net/api/forms/newsletter/1/
{"err": 0}
  

Avec les données suivantes en entrée, modifiera donc uniquement le champ « email ».

{
  "data": {
     "email": "marc@example.org"
  }
}