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)
Champs additionnels de l'objet client : (sans impact dans cette version de l'API)
Ces champs ne sont disponibles que lorsque l'usage de l'API nécessite en plus de valider automatiquement la création de comptes sans intervention. Leur utilisation est soumise à l'approbation de Rendezvousfacile.com quand à la conformité de l'usage et la robustesse des données de la BDD.
L'ensemble des champs doit être renseigné pour un nouveau user si le usertype est Provider ou Secretary
- usertype (remplace définition ci-dessus)
- string(20) - Type de user parmi les valeurs User pour client, Commercial pour représentant commercial, Provider pour professionnel et Secretary pour Secrétaire/Administrateur de Structure. Les deux derniers usertype sont soumis à approbation de Rendezvousfacile.com (User par défaut)
- username
- string(25) - Identifiant du user pour connexion sur Rendezvousfacile.com. Il doit contenir plus de 5 caractères (lettres et chiffres uniquement)
- password
- string(25) - MD5 du Mot de passe du user pour connexion sur Rendezvousfacile.com. Nous vous conseillons de choisir un mot de passe ayant au moins 8 caractères et différent du username (généré automatiquement par défaut)
- newsletter
- enum('HTML','No') - Adhésion aux lettres d'informations
- partners_mail rec_mail
- enum('HTML','No') - Adhésion aux mailings de nos partenaires commerciaux
- acc_terms
- enum('Yes','No') - Le user accepte les Conditions Générales d'Utilisation du site Rendez-vous Facile
- recive_msg_from
- enum('Known','No') - Messagerie interne activée (Known par défaut)
- utzoffset
- Integer - fuseau horaire - Nous consulter pour d'autres zones (30 par défaut pour l'heure normale d'Europe centrale)
- dstoffset
- Integer - Ajustement automatique d'heure d'été (1 par défaut)
- online_agenda
- enum('ON','OFF') - Disponibilité de l'agenda si usertype Provider (OFF par défaut)
- busi_reg
- string(25) - Numéro de Société comme le SIREN
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