Documentation en ligne

Gestion des fiches

Une application tierce peut créer des fiches, récupérer les données des fiches, et peut également obtenir la liste des modèles de fiche et les schémas de données associés.

Création d'une fiche

La création d'une fiche se fait par une requête POST à l’adresse /api/cards/slug/submit, le contenu de la requête doit être un dictionnaire contenant obligatoirement un attribut data.

L’attribut data est obligatoire et contient un dictionnaire dont les clés sont les noms de variable (remplacé ici par varname) des champs de la fiche 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 « Liste » et « Liste à choix multiples » acceptent différentes valeurs selon leur configuration, ceci est décrit dans Transmission des champs « Liste » et « Liste à choix multiple ».

  • 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’exemple suivant crée une fiche « Parking », dont le modèle de fiche a comme identifiant « parkings », qui demanderait trois champs : adresse (nom de variable adresse), date d'ouverture (nom de variable date_ouverture) et nom (nom de variable nom).

$ curl -H "Content-type: application/json" \
       -H "Accept: application/json" \
       -d@donnees.json \
       https://www.example.net/api/cards/parkings/submit?signature…
{"err": 0, "data": {"id": "5"}}
  

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

{
  "data": {
     "adresse": "rue de l’Opéra",
     "date_ouverture": "2020-11-12",
     "nom": "Parking Opéra-Tolozan"
  }
}
  

Récupération des données d’une fiches

L’exemple suivant récupère les données d’une fiche « Parking », dont le modèle de fiche a comme identifiant « parkings ».

$ curl -H "Accept: application/json" \
       https://www.example.net/api/cards/parkings/5/?signature…

Le contenu ainsi obtenu est le suivant :

{
   "digest" : "Parking Opéra-Tolozan",
   "display_id" : "31-5",
   "display_name" : "Parkings - n°31-5",
   "id" : "5",
   "last_update_time" : "2020-11-24T14:18:16",
   "receipt_time" : "2020-11-06T14:48:07",
   "fields" : { 
      "adresse" : "rue de l’Opéra",
      "date_ouverture" : "2020-11-12",
      "nom" : "Parking Opéra-Tolozan"
   },
   "text" : "Parking Opéra-Tolozan",
   "url" : "https://.../backoffice/data/parkings/5/",
   "workflow" : {
      "status" : {
         "id" : "recorded",
         "name" : "Recorded"
      }
   },
   "evolution" : [...],
   "geolocations": {...},
   "roles": {...}
}

La structure du contenu correspond à celle de l’API de Création d'une fiche.

Liste de fiches

La liste des fiches d’un modèle donné est destinée à être utilisée par un système de synchronisation. Elle ne retourne donc pour chaque fiche que son numéro (id), ses dates de création et de dernière mise à jour.

Un système de synchronisation vérifiera depuis cette liste si de nouvelles demandes existent, ou si certaines ont été mises à jour, sont obsolètes ou effacées, puis effectuera pour chacune les actions nécessaires.

$ curl -H "Accept: application/json" \
       https://www.example.net/api/cards/parkings/list?signature…
{
    "data": [
        {
            "id": 1,
            "text": "Parking de la place",
            "url": "https://www.example.net/backoffice/data/parkings/1/",
            "last_update_time": "2015-03-26T23:08:45",
            "receipt_time": "2015-03-26T23:08:44",
            "display_id": "12-1",
            "display_name": "Parkings - n°12-1"
        },
        {
            "id": 3,
            "text": "Parking de la rivière",
            "url": "https://www.example.net/backoffice/data/parkings/3/",
            "last_update_time": "2015-03-27T12:11:21",
            "receipt_time": "2015-03-27T12:45:19",
            "display_id": "12-3",
            "display_name": "Parkings - n°12-3"
        }
    ]
}

Des paramètres peuvent être envoyés dans la requête pour filtrer la liste des fiches, ils sont similaires à ceux de l’API de récupération d’une liste de formulaires. Les autres paramètres de cette API sont également exploitables, pour inclure l’ensemble des données (full=on) ou anonymiser celles-ci (anonymise).

Schéma de données

Une API existe pour récupérer le schéma de données d’un modèle de fiches.

$ curl -H "Accept: application/json" \
       https://www.example.net/api/cards/parkings/@schema?signature…
{
   "always_advertise" : false,
   "appearance_keywords" : null,
   "confirmation" : false,
   "description" : null,
   "detailed_emails" : true,
   "digest_template" : "{{form_var_nom}}",
   "disabled" : false,
   "disabled_redirection" : null,
   "discussion" : false,
   "drafts_lifespan" : null,
   "enable_tracking_codes" : false,
   "expiration_date" : null,
   "fields" : [
      {
         "anonymise" : true,
         "data_source" : {},
         "label" : "Nom",
         "prefill" : {
            "type" : "none"
         },
         "required" : true,
         "type" : "string",
         "validation" : {},
         "varname" : "nom"
      },
      ...
   ],
   "workflow" : {
      "fields" : [],
      "functions" : {
         "_editor" : "Editor",
         "_viewer" : "Viewer"
      },
      "name" : "Fiche parking",
      "statuses" : [
         {
            "endpoint" : false,
            "forced_endpoint" : false,
            "id" : "recorded",
            "name" : "Recorded",
            "waitpoint" : true
         },
      ...
   }
}

Liste des modèles de fiches

Une API permet de récupérer la liste des modèles de fiches.

$ curl -H "Accept: application/json" \
       https://www.example.net/api/cards/@list?signature…
{
   "data" : [
      {
         "custom_views" : [],
         "description" : "",
         "id" : "parkings",
         "keywords" : [],
         "slug" : "parkings",
         "text" : "Parkings",
         "title" : "Parkings",
         "url" : "https://.../backoffice/data/parkings/"
      },
      ...
   }
}

Dernière mise à jour le 22 octobre 2021 15:41 — Éditer