wcs/help/fr/api-fill.page

<page xmlns="http://projectmallard.org/1.0/"
      type="topic" id="api-fill" xml:lang="fr">

<info>
  <link type="guide" xref="index#api" />
  <revision docversion="0.1" date="2013-01-04" status="draft"/>
  <credit type="author">
    <name>Frédéric Péters</name>
    <email>fpeters@entrouvert.com</email>
  </credit>
  <desc>Transmission de données</desc>

</info>

<title>Complétion et modification d'un formulaire</title>

<p>
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.
</p>

<section id="create">
  <title>Complétion d'un formulaire</title>

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

  <p>
   L'attribut <code>data</code> 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.
  </p>

  <list>
  <item>
  <p>
   Les champs de type simple tels que « Texte », « Texte long » ou
   « Courriel » sont des chaînes de caractères.
  </p>
  </item>

  <item>
  <p>
   Les champs de type « Date » sont des chaînes de caractères au format
   ISO-8601, i.e. <code>YYYY-MM-DD</code>.
  </p>
  </item>

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

  <item>
  <p>
   Les champs de type « Carte » sont des dictionnaires contenant les clés
   <code>lat</code> pour la latitute en nombre décimal et <code>lon</code>
   pour la longitude en nombre décimal.
  </p>
  </item>
  </list>

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

  <table shade="rows">
    <title>Métadonnées</title>
    <tr>
      <td><p><code>draft</code></p></td>
      <td><p><code>true</code> pour enregistrer le formulaire comme étant un
      brouillon.</p></td>
    </tr>
    <tr>
      <td><p><code>backoffice-submission</code></p></td>
      <td><p><code>true</code> pour enregistrer le formulaire comme étant
      saisi depuis le backoffice.</p></td>
    </tr>
   </table>

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

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

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

  <p>
   Le fichier de données utilisé (<file>donnees.json</file>) contient le
   dictionnaire JSON suivant :
  </p>

  <code mime="application/json">
{
  "data": {
     "prenom": "Marc",
     "nom": "L.",
     "email": "marc@example.net"
  }
}
  </code>

</section>

<section id="edit">
  <title>Modification d'un formulaire</title>

  <p>
   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 <code>POST</code> sur l'adresse du formulaire.
  </p>

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

  <p>
   Cet appel :
  </p>

<screen>
<output style="prompt">$ </output><input>curl -H "Content-type: application/json" \
       -H "Accept: application/json" \
       -d@donnees.json \
       https://www.example.net/api/forms/newsletter/1/</input>
<output>{"err": 0}</output>
  </screen>

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

  <code mime="application/json">
{
  "data": {
     "email": "marc@example.org"
  }
}
  </code>

</section>

</page>