ClicRDV REST API v1

Vous pouvez vous servir de cette API pour utiliser les fonctionnalités de ClicRDV en dehors des interfaces fournies par ClicRDV.

Les utilisations les plus fréquentes de l’API concernent :

A propos de l'API ClicRDV

ClicRDV met à disposition une API HTTP RESTful, ce qui signifie que le traitement d'une requête sera dépendant de l'ensemble des éléments suivants :

  • l'URL de la requête,
  • la méthode HTTP (GET, POST, PUT, DELETE) utilisée lors de la requête,
  • les paramètres passés lors de la requête :
    • via le body de la requête pour les requêtes POST et PUT,
    • et via l'URL de la requête dans tous les cas.

Les API HTTP RESTful donnent un sens très précis à chaque méthode HTTP, comme expliqué sur cette page wikipedia.

Documentation des appels API

Dans la suite de cette documentation, les appels à l'API seront toujours présentés de la façon suivante :

1 
POST /api/v1/ressource.format?x=y&w=z
2 
{
    "clé": "valeur"
    ...
}


1 La première ligne indique la méthode HTTP utilisée (dans l'exemple POST), suivie d'un espace, puis de l'URL appelée sur l'API (dans l'exemple /api/v1/ressource.format?x=y&w=z).


Pour la clarté de la présentation, l'URL est volontairement raccourcie. Elle contient :

  • le "path", dans l'exemple /api/v1/ressource.format,
  • et, optionnellement, des paramètres, dans l'exemple ?x=y&w=z.

Lors de votre utilisation de l'API vous devrez compléter cette URL, selon le cas, avec l'URL de base de production ou bien de test/recette (voir rubriques ci-dessous).

Ex: /api/v1/groups/:group_id/calendars.json deviendra https://www.clicrdv.com/api/v1/groups/:group_id/calendars.json en production.

Vous devrez également veiller à passer en paramètre toutes les informations utiles concernant l'authentification (clé API), la pagination, les formats, etc.

Ex: /api/v1/groups/:group_id/calendars pourra devenir en production : https://www.clicrdv.com/api/v1/groups/:group_id/calendars.json?apikey=xxxxxx&results=all


Note Lorsque l'URL contient des mots clés précédés d'un caractère :, ils sont à remplacer par des valeurs correspondant à votre cas d'utilisation. Par exemple l'URL /api/v1/groups/:group_id/fiches/:id contient deux mots clés :group_id et :id, que vous devrez remplacer par des valeurs numériques, par exemple /api/v1/groups/1/fiches/4.


2 La deuxième ligne et les lignes suivantes, lorsqu'elles sont présentes dans l'exemple, correspondent au contenu du "body" de la requête (requêtes de type POST ou PUT).

URL de production

Pour utiliser l’API en production, l’URL de base est :

https://www.clicrdv.com/

Important L’API fonctionne exclusivement en HTTPS (port 443). Si vous essayez d'utiliser l'API en HTTP, vous obtiendrez un message d'erreur.

URL de test/recette

Si votre utilisation de l'API nécessite l'accès en écriture, il est préférable de développer l'application sur notre plateforme de test.

L'URL de base devient alors :

https://sandbox.clicrdv.com/

Important La clé API, nécessaire pour tous les appels API, n'est pas la même que la clé API de production.

Format de réception de données

L’API ClicRDV permet de récupérer les données dans divers formats : json, xml ou csv.

Le format peut être transmis via le paramètre "format" ou en précisant directement l'extension dans le path. Exemples :

GET /api/v1/groups/:group_id/fiches.json

ou, de façon équivalente :

GET /api/v1/groups/:group_id/fiches?format=json

Important Le format CSV est accessible uniquement en lecture, et :

  • La première ligne de l’export indique les noms des champs.
  • Les champs sont séparés par des virgules
  • Les informations de pagination de sont pas présentes dans la réponse.
  • Les requêtes devront comporter le paramètre results=all, sinon, la réponse ne contiendra que les 25 premiers éléments.

Format d'envoi des données / Content-Type

Important Les requêtes d'écritures à l'API (requêtes HTTP utilisant la méthode POST), doivent contenir le header Content-Type correspondant au format des données envoyées dans le corps de la requête (body).

  • application/json
  • application/x-www-form-urlencoded
  • application/xml