API REST synchronisation agenda - Rendez-vous Facile

Introduction

L'API s'adresse aux clients professionnels Premium et aux partenaires de Rendezvousfacile.com qui souhaitent synchroniser l'agenda Rendezvousfacile.com avec leur système d'information, que ce soit un logiciel métier, un CRM, un DMS, une base de données ou tout autre système d'information de gestion d'agendas ou de relation client, ci-dessous appelé BDD.

Vous pouvez vous servir de cette API pour utiliser certaines fonctionnalités de Rendezvousfacile.com en dehors de l'interface fournie. Il peut s'agir de synchronisation, d'import et d'export d'agendas ou des fiches clients.

L'API de Rendezvousfacile.com est de type REST et accepte les méthodes GET (Récupérer) et POST (Créer, Modifier ou Supprimer). Il est également possible d'utiliser le paramètre method (valeurs GET ou POST) pour appeler l'API avec la bonne méthode HTTP ce qui peut être utile pour un formulaire web ou certains firewalls.

L'API permet d'échanger les données dans le format JSON. Pour cela elle utilise le paramètre format qui doit avoir pour valeur json. Dans le format JSON une valeur vide est représentée par la constante null.

Authentification

L'utilisation de l'API est restreinte par une clé d'utilisation. Les clés sont fournies sur demande par Rendezvousfacile.com en précisant l'utilisation envisagée de l'API dans votre message. La clé est associée à une application (vous devez demander plusieurs clés si vous créez plusieurs applications).
Les clés API sont différentes entre l'environnement sandbox et l'environnement de production. Rendezvousfacile.com se réserve le droit de refuser l'attribution d'une clé, de la récuser ou de la limiter.

La clé doit être envoyée à chaque requête sur l'API, en utilisant le paramètre apikey.

De plus, vous devez vous authentifier en utilisant l'identifiant uname et le mot de passe pass encodé en MD5 associés au compte Rendezvousfacile.com pour lequel l'accès aux ressources est souhaité. Pour plus de facilité, si la clé est associée à une structure ayant un compte d'administrateur, il est possible d'utiliser le mot de passe de la structure pour tous les professionnels y étant associés.

URLs Sandbox et Production

Pour utiliser l'API en production, l'URL de base est :
https://www.rendezvousfacile.com/api/sync_api_YYYYMMDD.php

L'environnement sandbox (ou bac à sable) vous permet de tester votre application sans modifier vos données de production.
L'URL à utiliser est alors :
https://sandbox.rendezvousfacile.com/api/sync_api_YYYYMMDD.php

Dans le cas d'une application en lecture seule, l'utilisation de la sandbox n'est pas nécessaire.

L'API Rendezvousfacile.com fonctionne exclusivement en HTTPS (port 443). Toutes les données doivent être codées en Unicode (UTF-8).
Les clés en mode Sandbox et Production, nécessaires pour tous les appels de l'API, sont différentes.

Rendezvousfacile.com se réserve le droit de modifier l'API à tout moment pour l'ajout de fonctionnalités ou la résolution de bogues.
La version la plus récente est sync_api_20130210.php

Statuts d'analyse

Chaque requête transmise au serveur, reçoit en retour un statut d'analyse de son contenu. Le code de réponse HTTP est contenu dans l'entête HTTP et dans le contenu de la réponse

200 OK : Requête acceptée
400 Bad Request : Paramètre manquant ou erroné
401 Unauthorized : Couple identifiant/mot de passe erroné
403 Forbidden : Pas la permission requise pour exécuter cette opération
404 Not Found : Ressource demandée n'existe pas
500 Internal Server Error : Erreur inconnue - si cette erreur persiste, merci de nous contacter

En cas d'erreur, le contenu de la réponse contiendra une liste d'une ou plusieurs erreurs sous la forme : {"error":"Message d'erreur"}

Objets accessibles via l'API

Voici la liste des objets disponibles via l'API :

type - Type de prestations
location - Lieux des prestations
calendar - Liste des Rendez-vous
client - Données clients
holiday - Gestion des jours fériés

L'objet à créer ou à modifier doit être contenu dans un objet portant son nom (ex : ‘calendar').

Seul les champs modifiés peuvent être spécifiés à l'exception de rdvfid et/ou de extid qui est nécessaire pour faire une modification.

Exemple : modification du nom et de la durée du type 45615

{"type":{"apptype":"Echographie","duration":"20","rdvfid":"45615","extid":"984"}}

Le serveur renvoie l'ensemble de l'objet créé ou modifié. Ce dernier contient en particulier le rdvfid assigné si il s'agit d'une création. Il est souhaitable de conserver cet identifiant nécessaire pour utilisation ultérieure.

Objet Type

Par défaut, 3 types de rendez-vous de 15 minutes sont créés lors de la création d'un compte de professionnel :
- Consultation
- Visite à domicile
- Représentant Commercial (il ne peut être supprimé)

Il est nécessaire de récupérer leur identifiant pour les modifier en fonction des besoins du professionnel.

Récupérer un objet type

Le paramètre typeid doit contenir l'identifiant rdvfid de l'objet souhaité ou 0 pour obtenir la liste complète.

GET /api/sync_api_YYYYMMDD.php?format=json&apikey=xxx&uname=xxx&pass=xxx&typeid=xxx

Créer ou modifier un objet type

POST /api/sync_api_YYYYMMDD.php?format=json&apikey=xxx&uname=xxx&pass=xxx
[
  { "type": {
      "apptype":"Echographie",
      "duration":"20",
      "color":"#AAFFFF",
      "extid":"a546",
      "rdvfid":"489841"}
  }
]

Supprimer un objet type

Un objet type ne peut pas être supprimé via l'API.

Champs de l'objet type

apptype: string(50) - Titre du type de rdv (unique et obligatoire pour un nouveau type)
duration: integer - Durée du type de rdv (multiple de 5 minutes) (15 par défaut)
description: text - Description du type de rdv apparaissant lors de la recherche de rdv par le client
instructions: text - Instructions pour le type de rdv envoyées par email au client lors du rappel du rdv
visible_web: enum('Yes','No') - Type ouvert aux patients sur internet (Yes par défaut)
visible_first: enum('Yes','No') - Type ouvert aux nouveaux patients sur internet (Yes par défaut)
home_visit: enum('Yes','No') - Indique si le type de rdv est une visite à domicile (No par défaut)
max_dist: integer - Distance en km par rapport au lieu pour lequel les visites à domicile sont acceptées (0 par défaut pour illimité)
color: string(7) - Couleur du type au format hexadécimal #RRGGBB (#C6C6C6 par défaut)
extid: string(10) - Identifiant du type dans BDD a indiquer si l'objet existe déjà. Permet de réconcilier les données
rdvfid: integer - Identifiant du type chez Rendezvousfacile.com a indiquer si l'objet existe déjà. Si pas de valeur un objet est créé, sinon il est modifié (en lecture uniquement)
changed: datetime - Date de dernière modification, ex: "2013-01-10 10:27:50" (en lecture uniquement)

Objet Location

Un objet location peut être utilisé pour des lieux d'exercice (différents cabinets, exercice mixte cabinet-clinique,...) et/ou des ressources (salles, appareils,...).

Par défaut, 2 objets location sont créés lors de la création d'un compte de professionnel :
- Cabinet
- Visite à domicile

Il est nécessaire de récupérer leur identifiant pour les modifier en fonction des besoins de votre exercice.

Récupérer un objet location

Le paramètre locid doit contenir l'identifiant rdvfid de l'objet souhaité ou 0 pour obtenir la liste complète.

GET /api/sync_api_YYYYMMDD.php?format=json&apikey=xxx&uname=xxx&pass=xxx&locid=xxx

Créer ou modifier un objet location

POST /api/sync_api_YYYYMMDD.php?format=json&apikey=xxx&uname=xxx&pass=xxx
[
  { "location": {
      "lname":"Clinique du Bien-Etre",
      "laddress":"130 Avenue des Champs-Elysées",
      "lcity":"Paris"
      "rdvfid":"9154"}
  }
]

Supprimer un objet location

Un objet location ne peut pas être supprimé via l'API.

Champs de l'objet location

lname: string(50) - Titre du lieu ou de la ressource (obligatoire pour un nouveau lieu)
laddress: string(100) - Adresse du lieu (obligatoire pour un nouveau lieu)
lzipcode: string(20) - Code Postal
lcity: string(50) - Ville (obligatoire pour un nouveau lieu)
lcountry: string(2) - Code du pays, ex. CH pour la Suisse (FR par défaut)
latitude: double(50,6) - Latitude (46.000000 par défaut)
longitude: double(50,6) - Longitude (2.000000 par défaut)
lphone: string(20) - Numéro de téléphone du lieu au format international ( ex. +33123456789 en France) (obligatoire pour un nouveau lieu)
description: text - Informations complémentaires sur le lieu
visible_web: enum('Yes','No') - Lieu ouvert aux patients sur internet (Yes par défaut)
visible_first: enum('Yes','No') - Lieu ouvert aux nouveaux patients sur internet (Yes par défaut)
cash: enum('Yes','No') - Accepte les règlements par argent liquide dans ce lieu (No par défaut)
cheque: enum('Yes','No') - Accepte les règlements par chèque dans ce lieu (No par défaut)
visa: enum('Yes','No') - Accepte les règlements par carte Visa dans ce lieu (No par défaut)
mastercard: enum('Yes','No') - Accepte les règlements par carte Mastercard dans ce lieu (No par défaut)
amex: enum('Yes','No') - Accepte les règlements par carte American Express dans ce lieu (No par défaut)
diners: enum('Yes','No') - Accepte les règlements par carte Diners Club dans ce lieu (No par défaut)
vitale: enum('Yes','No') - Télétransmission par carte Vitale dans ce lieu (No par défaut)
acc_handi: enum('Yes','No') - Accès handicapé dans ce lieu (No par défaut)
aircon: enum('Yes','No') - Climatisation dans ce lieu (No par défaut)
wifi: enum('Yes','No') - WIFI disponible dans ce lieu (No par défaut)
car_park: enum('Yes','No') - Parking disponible à proximité de ce lieu (No par défaut)
color: string(7) - Couleur du type au format hexadécimal #RRGGBB (#A5A5A5 par défaut)
extid: string(10) - Identifiant du lieu dans BDD a indiquer si l'objet existe déjà. Permet de réconcilier les données
rdvfid: integer - Identifiant du lieu/ressource chez Rendezvousfacile.com a indiquer si l'objet existe déjà. Si pas de valeur un objet est créé, sinon il est modifié (en lecture uniquement)
changed: datetime - Date de dernière modification, ex: "2013-01-10 10:27:50" (en lecture uniquement)

Objet Client

Récupérer un objet client

Le paramètre clientid doit contenir l'identifiant rdvfid de l'objet souhaité ou les premières lettres du nom de famille pour obtenir la liste des objets client correspondants.

GET /api/sync_api_YYYYMMDD.php?format=json&apikey=xxx&uname=xxx
    &pass=xxx&clientid=xxx

Créer ou modifier un objet client

POST /api/sync_api_YYYYMMDD.php?format=json&apikey=xxx&uname=xxx&pass=xxx
[
  { "client": {
      "fname":"Grégory",
      "lname":"Dupont",
      "birthdate":"1940-03-11",
      "homephone":"+33123456789",
      "invite":"No"}
  }
]

Supprimer un objet client

Un objet client ne peut pas être supprimé via l'API.

Champs de l'objet client

gender: string(10) - Sexe (Male, Female) (Male par défaut)
title: string(10) - Titre si médecin (Dr, Pr ou null)
fname: string(50) - Prénom (obligatoire pour un nouveau client)
mname: string(50) - Second prénom
lname: string(50) - Nom de famille (obligatoire pour un nouveau client)
company: string(50) - Société (obligatoire pour un nouveau client de usertype Commercial)
birthdate: date - Date de naissance au format AAAA-MM-DD (ex, 1976-10-24) (0000-00-00 par défaut)
email: string(50) - Adresse e-mail - nécessaire pour l'envoi de confirmations/rappels de rdv au client - non retourné car non optin
address: string(100) - Adresse du lieu (obligatoire pour pouvoir prendre des rdv de type visite à domicile)
zipcode: string(20) - Code Postal
city: string(50) - Ville
country: string(2) - Code du pays, ex. CH pour la Suisse (FR par défaut)
latitude: double(50,6) - Latitude (46.000000 par défaut)
longitude: double(50,6) - Longitude (2.000000 par défaut)
homephone: string(20) - Numéro de téléphone du domicile au format international (ex. +33123456789 en France)
officephone: string(20) - Numéro de téléphone professionnel au format international (ex. +33123456789 en France)
cellphone: string(20) - Numéro de téléphone portable au format international - nécessaire pour l'envoi de SMS au client (ex. +33123456789 en France)
fax: string(20) - Numéro de fax au format international ( ex. +33123456789 en France)
website: string(25) - url du site internet du client sous la forme http://www.domaine.com
language: Integer - Langue utilisée sur l'interface 1 pour le français et 2 pour l'anglais (1 par défaut)
usertype: string(20) - Type de client parmi les valeurs User pour client classique et Commercial pour représentant commercial (User par défaut)
invite: enum('Yes','No') - Envoi d'un e-mail d'invitation au client pour finaliser son compte (Yes par défaut)
extid: string(10) - Identifiant du client dans BDD a indiquer si l'objet existe déjà. Permet de réconcilier les données
rdvfid: integer - Identifiant du client chez Rendezvousfacile.com a indiquer si l'objet existe déjà. Si pas de valeur un objet est créé, sinon il est modifié (en lecture uniquement)
changed: datetime - Date de dernière modification, ex: "2013-01-10 10:27:50" (en lecture uniquement)

Objet Calendar

Les objets calendar peuvent être de 3 types :

Appointment - RDV classiques à contraintes. Ils sont obligatoirement associés à des objets client, type et location. Ils permettent les rappels de rdv par email et sms le cas échéant. Les emails de confirmations et d'annulation de rdv ne sont par contre pas envoyés. Cette version de l'API ne gère pas les capacités multiples.
Activity - Simples évènements (ex: rendez-vous non contraint, absence, congrès,...) qui peuvent également durer sur plusieurs journées pleines (ex: vacances) . Les objets client, type et location doivent être à la valeur null.
Note - Note ayant lieu à une date et une heure donnée (0,15,30,45 minutes de chaque heure) mais ne bloquant pas de temps sur les calendriers. Plusieurs notes peuvent être crées à la même heure. Ils peuvent être utilisés par exemple pour le surbooking. Les attributs start et end doivent avoir la même valeur (la durée de la note est considérée comme nulle).

Les heures sont automatiquement arrondies aux multiples de 5 ou de 15 en dessous selon le type de calendar si ce n'est pas le cas.

Récupérer un objet calendar

Plusieurs méthodes de récupération d'un objet calendar sont disponibles.

Le paramètre calid doit contenir l'identifiant rdvfid de l'objet souhaité.

GET /api/sync_api_YYYYMMDD.php?format=json&apikey=xxx&uname=xxx&pass=xxx&calid=xxx

Le paramètre delta doit contenir la datetime de du champ changed à partir de laquelle l'objet doit être récupéré :

GET /api/sync_api_YYYYMMDD.php?format=json&apikey=xxx&uname=xxx
    &pass=xxx&delta=2012-09-27%2017:40:00

Le paramètre dt_frm et dt_end doivent contenir les dates limites considérées pour la récupération :

GET /api/sync_api_YYYYMMDD.php?format=json&apikey=xxx&uname=xxx
    &pass=xxx&dt_frm=2012-09-27&dt_end=2012-10-05

Remarque : Les objets supprimés ne sont pas listés.

Créer ou modifier un objet calendar

POST /api/sync_api_YYYYMMDD.php?format=json&apikey=xxx&uname=xxx&pass=xxx
[
  { "calendar": {
      "start":"2013-02-07 14:40:00",
      "end":"2013-02-07 15:00:00",
      "client":{"rdvfid":"16292"},
      "location":{"lname":"Cabinet 2","rdvfid":"34"},
      "type":{"rdvfid":"58"},
      "extid":"9184",
      "rdvfid":"S5742573"}
  }
]

Supprimer un objet calendar

Il peut être supprimé via l'API en envoyant l'objet avec status à Cancel et son rdvfid. L'objet est alors retourné complet et le status mis à jour si la suppression s'est bien effectuée ou avec un message d'erreur.

POST /api/sync_api_YYYYMMDD.php?format=json&apikey=xxx&uname=xxx&pass=xxx
[
  { "calendar": {
      "status":"Cancel",
      "rdvfid":"S5742573"}
  }
]

Champs de l'objet calendar

start: datetime - Date et heure locale de début du calendar (ex, 2013-03-23 14:30:00) (obligatoire pour un nouveau rdv)
end: datetime - Date et heure locale de fin du calendar (ex, 2013-03-23 14:45:00) (obligatoire pour un nouveau rdv)
client: object - Client (obligatoire pour un appointment, null pour activity/note)
location: object - Lieu d'exercice (obligatoire pour un appointment, null pour activity/note)
type: object - Type de RDV (obligatoire pour un appointment, null pour activity/note)
title: string(50) - Titre de l'activity (obligatoire pour un nouveau activity)
comment: string(200) - Commentaire non visible par le client ou contenu de la note
color: string(7) - Couleur de l'activity au format hexadécimal #RRGGBB (#BDEEC0 par défaut)
status: enum('Confirm','Cancel') - Indique si le calendar est ou doit être supprimé (Confirm par défaut)
extid: string(10) - Identifiant du client dans BDD a indiquer si l'objet existe déjà. Permet de réconcilier les données
rdvfid: integer - Identifiant du client chez Rendezvousfacile.com a indiquer si l'objet existe déjà. Si pas de valeur un objet est créé, sinon il est modifié (en lecture uniquement)
changed: datetime - Date de dernière modification, ex: "2013-01-10 10:27:50" (en lecture uniquement)

Objet Holiday

Par défaut les fériés légaux présents dans nos bases sont chômés mais il est possible d'indiquer les exceptions ou ils sont travaillés.
Si nos bases de données ne contiennent pas les jours fériés pour votre pays, n'hésitez pas à nous en communiquer la liste en incluant l'année, le libellé et la date.

Modifier l'objet holiday

Le statut d'un objet holiday peut être modifié.

POST /api/sync_api_YYYYMMDD.php?format=json&apikey=xxx&uname=xxx&pass=xxx
[
  { "holiday": {
      "date":"2013-01-01",
      "active":"Yes"}
  }
]

Champs de l'objet holiday

date: date - Date du jour férié à modifier au format AAAA-MM-DD
active: enum('Yes','No') - Indique si le jour férié est chômé ou travaillé (Yes par défaut)

Autres requêtes

Il est essentiel de synchroniser les heures serveurs. Cela est possible avec le paramètre status qui doit contenir la valeur date.

GET /api/sync_api_YYYYMMDD.php?format=json&apikey=xxx&uname=xxx&pass=xxx&status=date

En cas de changement de la BDD il peut être utile de remettre à zéro tous les extid. Cette action n'est pas réversible. Pour cela :

GET /api/sync_api_YYYYMMDD.php?format=json&apikey=xxx&uname=xxx&pass=xxx&reset=extid

Dernière modification : 28/02/2013

Prenez votre Rendez-vous

Dernières nouvelles

API REST de Rendezvousfacile.com