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"
  }
}
  

Il n’y a aucune vérification du format des données reçues, elles sont enregistrée telles quelles. Les contraintes de validation ou les conditions d’affichage ne sont pas prises en compte.

Création d’un ensemble de fiches par import CSV

Il est possible de créer un ensemble de fiches par import d’un fichier CSV. Cela s’effectue par une requête PUT à l’adresse /api/cards/slug/import-csv. Le contenu de la requête doit être un fichier CSV (text/csv).

Chaque ligne du fichier va provoquer la création d’une nouvelle fiche et lancer le workflow correspondant.

$ curl -X PUT -H "Content-Type: text/csv" \
       -H "Accept: application/json" \
       https://www.example.net/api/cards/slug/import-csv?signature…
       --data-binary @fichier.csv
{"err": 0}

Le fichier CSV doit suivre le même format que celui utilisé lors d’un import CSV dans l’interface de gestion.

Import CSV asynchrone (recommandé)

En plus de la création des fiches, le workflow va être exécuté pour chacune : sur un fichier CSV important le temps d’exécution de l’import peut dépasser la limite acceptée par le serveur HTTP (souvent 20 ou 30 secondes). Il est donc recommandé d’utiliser l’option asynchrone de l’import CSV.

Pour faire un import asynchrone, ajouter async=on dans les paramètres de l’URL :

$ curl -X PUT -H "Content-Type: text/csv" \
       -H "Accept: application/json" \
       https://www.example.net/api/cards/slug/import-csv?async=on
       --data-binary @fichier.csv
{
    "err": 0,
    "data": {
        "job": {
            "id": "1234",
            "url": "https://www.example.net/api/jobs/1234/"
        }
    }
}

Cet appel envoie le fichier CSV, mais il n’est pas aussitôt importé. Une tâche (job) est lancée qui va effectivement faire l’import, et on peut en suivre la progression en appellant son URL indiquée en retour de l’appel PUT.

$ curl -H "Accept: application/json" \
       https://www.example.net/api/jobs/1234/
{
    "err": 0,
    "data": {
        "status": "en cours",
        "label": "Importation des données dans des fiches",
        "creation_time": 1634910701,
        "completion_time": null,
        "completion_status": "23/46 (50%)"
}
}

Pour suivre la bonne exécution de l’import, il faut appeler cette URL jusqu’à ce que la valeur completion_time soit renseignée. La valeur status permet de savoir alors si l’import s'est correctement déroulé.

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

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": 2,
            "text": "Parking des nénuphars",
            "url": "https://www.example.net/backoffice/data/parkings/2/",
            "last_update_time": "2015-03-27T09:03:12",
            "receipt_time": "2015-03-27T09:03:12",
            "display_id": "12-2",
            "display_name": "Parkings - n°12-2"
        },
        {
            "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).

Il est également possible de récupérer une liste filtrée correspondant à une vue personnalisée, en ajoutant l’identifiant de celle-ci à l’adresse, ex :

$ curl -H "Accept: application/json" \
       https://www.example.net/api/cards/parkings/list/vue-personnalisee?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"
        }
    ]
}

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 4 mai 2022 09:45 — Éditer