Cette page s'adresse aux toiletteurs et à leurs informaticiens


les clients synchro des
rendez-vous
le toiletteur
et son logiciel

Comment faire communiquer le logiciel du toiletteur avec cette plateforme ?


API - documentation

URL API https://www.planningtoiletteur.com/api/

Cette documentation intéressera les informaticiens.

L'objectif est de permettre au logiciel du toiletteur de "discuter" avec cette plateforme pour récupérer les rendez-vous.

Tout logiciel peut communiquer avec notre plateforme en utilisant les fonctions décrites dans cette API. Chaque fonction peut être testée depuis cette page.

Vous devez utiliser un "accès toiletteur" pour faire vos tests.

Syntaxe https://www.planningtoiletteur.com/api/<nom_de_la_methode>
Méthode POST
Retour format JSON

Synchronisation des rendez-vous avec un logiciel métier

Seulement 2 fonctions de l'API sont nécessaires
méthode objectif
token-get récupération par le logiciel métier d'un token d'identification Les 2 fonctions
pour la synchronisation
des rendez-vous
give-me-news synchronisation des rendez-vous et des présences/absences des toiletteurs entre la plateforme et le logiciel métier
token-test tester si un token est toujours vivant Les 3 fonctions
complémentaires
mais pas indispensables
user-load récupérer la fiche d'un utilisateur
user-list-load récupérer la liste des fiches utilisateurs
token-get récupération par le logiciel métier d'un token d'identification
give-me-news synchronisation des rendez-vous et des présences/absences des toiletteurs entre la plateforme et le logiciel métier
token-test tester si un token est toujours vivant
user-load récupérer la fiche d'un utilisateur
user-list-load récupérer la liste des fiches utilisateurs

Les fonctions de l'API

3 paramètres obligatoires pour toutes les fonctions
Paramètre Valeur Type

api_version

1 int
obligatoire

pms_name

str30
obligatoire
nom du logiciel "métier" du toiletteur

pms_version

str30
obligatoire
version du logiciel "métier" du toiletteur

token-get

Cette fonction renvoie un token d'identification.
Toutes les autres fonctions auront besoin de ce token. C'est la première fonction à appeler.

Un token a une durée de vie. Les autres fonctions retourneront une erreur lorsqu'il faudra le renouveller.
Paramètre Valeur Type

login

str70
obligatoire
Nom d'utilisateur d'un "robot"
Seul un "robot" a le droit de communiquer avec la plateforme de prise de rendez-vous.
Commencer par créer un utilisateur de type "robot" dans le paramétrage de l'"Accès toiletteur".

password

str70
obligatoire
Mot de passe du robot
retour OK: JSON: { "success": true, "token": "A100", "id_etablissement": "A36"}
retour KO: JSON: { "success": false, "error_code": "CODE", "error_message": "MESSAGE" }
"error_code" possibles :
_ERROR_YOU_ARE_NOT_A_ROBOT
_ERROR_GENERATOR_TOKEN
_ERROR_PARAMETER_UNKNOWN
_ERROR_PARAMETER_INCOHERENT
_ERROR_CONNEXION_DATABASE
_ERROR_MAINTENANCE_EN_COURS
_ERROR_CALLING_API
_ERROR_EXCEPTION
_ERROR_UNKNOWN

la signification des codes erreurs se trouve dans le paramètre "error_message"

give-me-news

"Quoi de neuf docteur ?"

Cette fonction est la plus importante de l’API.

Elle permet d’échanger les objets à synchroniser entre la plateforme et le logiciel métier.
Ces objets sont sous formes de listes de rendez-vous, de définitions de présences/absences et d’accusés de réception des précédentes demandes.

Le logiciel métier (PMS) est toujours à l’initiative.

Un système d’accusés de réception permet au PMS d’avoir un retour sur les demandes qu’il a envoyé à la plateforme (WEB).
Réciproquement, le PMS enverra des accusés de réception à la plateforme. C’est pourquoi il est délicat de tester entièrement cette fonction ici. Il faudra le faire au sein du PMS.

Fonctionnement :

A intervalle régulier, le PMS appelle cette fonction « give-me-news » en envoyant 3 listes :

  • "resa_changed_from_pms" : liste des rendez-vous qui ont été créés/modifiés/supprimés dans le PMS
  • "presences_changed_from_pms" : liste des présences/absences qui ont été créées/modifiées/supprimées dans le PMS
  • "ack_from_pms" : liste des accusés de réception des demandes précédentes de la plateforme (WEB)

En retour, la plateforme WEB répond en renvoyant deux listes au PMS :

  • "ack_from_web" : liste des accusés de réception des demandes du PMS
  • "resa_changed_from_web" : liste des rendez-vous qui ont été créés/modifiés/supprimés au niveau de la plateforme.

Au préalable, à la mise en place de ce service dans le PMS, il faudra établir les correspondances entre les identifiants des utilisateurs du PMS et ceux de la plateforme. Pour cela, la fonction "user-list" de l’API est parfaite. Elle n'est pas indispensable puisque les correspondances peuvent être réalisées à la main dans le PMS avec les identifiants (id_user) indiqués en haut de cette page.

Fréquence d'appels et volume de données :

Afin de ne pas surcharger la plateforme, la fréquence d'appels des fonctions de l'API est limitée à 30 secondes minimum. La plateforme rejettera vos appels si vous essayez d'augmenter la fréquence : le code erreur obtenue en retour sera _ERROR_FREQUENCE_FAIR_PLAY.

De la même manière, le volume de données envoyé dans chacune des listes de la fonction "give-me-news" est volontairement limitée à 30 objets maximum par liste. Il est peu probable que 30 rendez-vous aient été modifiés dans le PMS ou sur la plateforme en l'espace de 30 secondes... Si vous essayez de dépasser 30 objets, votre appel à cette fonction sera rejetté et vous obtiendrez en retour le code erreur _ERROR_TOO_MUCH_RECORDS_IN_JSON_LIST

Paramètre Valeur Type

token

str200
obligatoire

resa_changed_from_pms

text
optionnel
Si demande de création ou de modification d'un rendez-vous :

{
    "methode": "create/update",
    "id_resa_pms": "A60",
    "id_resa_web": "A36",
    "id_user_web": "A36",
    "id_synchro_pms": INT,
    "dt_utc_change": "A23", //format yyyy-mm-dd hh:nn:ss.zzz, en UTC0 (heure Greenwich)
    "id_day": INT, //format yyyymmdd
    "debut_minutes": INT, //valeurs possibles [0..1440]
    "duree_minutes": INT, //valeurs possibles [1..1440] et (debut_minutes+duree_minutes<=1440)
    "motif": "A60",
    "notes": "TEXT",
    "client_nom": "A60",
    "client_tel_fixe": "A20",
    "client_tel_mobile": "A20",
    "field01_value": "A30",
    "field02_value": "A30",
    "field03_value": "A30",
    "field04_value": "A30"
}, ...

Si demande de suppression d'un rendez-vous :

{
    "methode": "delete",
    "id_resa_pms": "A60",
    "id_resa_web": "A36",
    "dt_utc_change": "A23" //format yyyy-mm-dd hh:nn:ss.zzz, en UTC0 (heure Greenwich)
}, ...

Limitations :

La liste "resa_changed_from_pms" ne doit pas comporter plus de 30 demandes de synchro. Si c'est le cas, votre appel à la fonction "give-me-news" sera rejetée, et vous obiendrez en retour le code erreur _ERROR_TOO_MUCH_RECORDS_IN_JSON_LIST.

Explications complémentaires :

"id_synchro_pms" est une valeur initialement à zéro dans le PMS, puis incrémentée automatiquement par le PMS à chaque fois que le rendez-vous est modifié.

Lorsque le PMS récupérera l'accusé de réception de sa demande de synchro, ce même "id_synchro_pms" lui sera renvoyé par la plateforme.

Cela permet au PMS de comparer ce "id_synchro_pms" avec celui qui se trouve dans sa base, et ainsi de savoir si le rendez-vous a changé chez lui depuis la demande de synchro, auquel cas il devra renvoyer à nouveau ce rendez-vous à la plateforme lors du prochain cycle de synchro.

Si rien n'avait changé, alors il fixera "id_synchro_pms" à zéro dans sa base.

presences_changed_from_pms

text
optionnel
{
    "id_day": INT, //format yyyymmdd, ou 0 (voir explications)
    "id_user_web": "A36",
    "presence": 0/1,
    "id_synchro_pms": INT
}, ...

Exemples :

Pour indiquer que l’utilisateur XXX est présent le 16 février 2018 :
{ "id_day": 20180216, "id_user_web": "XXX", "presence": 1, "id_synchro_pms": 123}

Pour indiquer que l’utilisateur XXX est absent le 16 février 2018 :
{ "id_day": 20180216, "id_user_web": "XXX", "presence": 0, "id_synchro_pms": 123}

Pour indiquer que l’utilisateur XXX est toujours présent, tous les jours :
{ "id_day": 0, "id_user_web": "XXX", "presence": 1, "id_synchro_pms": 123}

Pour indiquer que l’utilisateur XXX est toujours absent, tous les jours :
{ "id_day": 0, "id_user_web": "XXX", "presence": 0, "id_synchro_pms": 123}

Explications complémentaires :

"id_synchro_pms" est une valeur initialement à zéro dans le PMS, puis incrémentée automatiquement par le PMS à chaque fois qu'une présence/absence est modifiée.

Lorsque le PMS récupérera l'accusé de réception de sa demande de synchro, ce même "id_synchro_pms" lui sera renvoyé par la plateforme.

Cela permet au PMS de comparer ce "id_synchro_pms" avec celui qui se trouve dans sa base, et ainsi de savoir si la présence/absence a changé chez lui depuis la demande de synchro, auquel cas il devra renvoyer à nouveau cette présence/absence à la plateforme lors du prochain cycle de synchro.

Si rien n'avait changé, alors il fixera "id_synchro_pms" à zéro dans sa base.

ack_from_pms

text
optionnel
{
    "type_ack_from_pms": "ack_pms_resa_created/ack_pms_resa_updated/ack_pms_resa_deleted",
    "id_web": "A36",
    "id_pms": "A",
    "id_synchro_pms": INT
}, ...

Explications :

Cette liste contient les accusés de réception des ordres envoyés précédemment par la plateforme au PMS.

retour OK: JSON: { "success": true,
         "resa_changed_from_web": [ {<rendez-vous-1>}, {<rendez-vous-2>}, ...],
         "ack_from_web": [ {<accusé-de-réception-1>}, {<accusé-de-réception-2>}, ...]
      }

Description de la liste "resa_changed_from_web" :

Cette liste contient les ordres de synchronisation demandés par la plateforme au PMS.
{
   "id_resa_web": "A36",
   "id_resa_pms": "A60",
   "id_etablissement": "A36",
   "id_synchro_web": INT,
   "id_user_web": "A36",
   "dt_utc_change": "A23", //format yyyy-mm-dd hh:nn:ss.zzz, en UTC0 (heure Greenwich)
   "deleted": 0/1,
   "id_day": INT, //format yyyymmdd
   "debut_minutes": INT, //valeurs possibles [0..1440]
   "duree_minutes": INT, //valeurs possibles [1..1440] et (debut_minutes+duree_minutes<=1440)
   "motif": "A60",
   "notes": "TEXT",
   "id_client": "A36",
   "client_email": "A100",
   "client_nom": "A60",
   "client_tel_fixe": "A20",
   "client_tel_mobile": "A20",
   "field01_use": 0/1,
   "field01_label": "A30",
   "field01_value": "A30",
   "field02_use": 0/1,
   "field02_label": "A30",
   "field02_value": "A30",
   "field03_use": 0/1,
   "field03_label": "A30",
   "field03_value": "A30",
   "field04_use": 0/1,
   "field04_label": "A30",
   "field04_value": "A30"
}

Description de la liste "ack_from_web" :

Cette liste contient les accusés de réception des ordres envoyés précédemment par le PMS à la plateforme.
{
   "type_ack": "ack_web_resa_created/ack_web_resa_updated/ack_web_resa_deleted/ack_presence",    "id_resa_web": "A36",
   "id_resa_pms": "A60",
   "id_synchro_pms": INT,
   "precision": "A" //éventuel commentaire qui peut être ignoré
}

retour KO: JSON: { "success": false, "error_code": "CODE", "error_message": "MESSAGE" }
error_code possibles :
_ERROR_PARAMETER_UNKNOWN
_ERROR_PARAMETER_INCOHERENT
_ERROR_YOU_ARE_NOT_A_ROBOT
_ERROR_GENERATOR_TOKEN
_ERROR_MAINTENANCE_EN_COURS
_ERROR_TOO_MUCH_RECORDS_IN_JSON_LIST
_ERROR_FREQUENCE_FAIR_PLAY
_ERROR_CREDITER_LE_COMPTE

la signification des codes erreurs se trouve dans le paramètre "error_message"


token-test

Cette fonction permet de vérifier si un token est toujours vivant.
Paramètre Valeur Type

token

str200
obligatoire
retour OK: JSON: { "success": true, "vivant": true/false }
retour KO: JSON: { "success": false, "error_code": "CODE", "error_message": "MESSAGE" }
"error_code" possibles :
_ERROR_YOU_ARE_NOT_A_ROBOT
_ERROR_PARAMETER_UNKNOWN
_ERROR_PARAMETER_INCOHERENT
_ERROR_CONNEXION_DATABASE
_ERROR_MAINTENANCE_EN_COURS
_ERROR_CALLING_API
_ERROR_EXCEPTION
_ERROR_UNKNOWN

la signification des codes erreurs se trouve dans le paramètre "error_message"

user-load

Récupération des champs d'un utilisateur.
Paramètre Valeur Type

token

str200
obligatoire

id_user

str36
obligatoire
retour OK: JSON: { "success": true,
        "user": {
             "id_user": "A36",
             "login": "A70",
             "nature": "praticien/assistant/robot",
             "actif": 0/1,
             "colonne": 0/1, //possède une colonne dans le planning
             "titre": "A15",
             "nom": "A60",
             "prenom": "A60",
             "initiales": "A2",
             "profession": "A60",
             "specialites": "TEXT",
             "deleted": 0/1,
             "dt_utc_deleted": null/"timestamp"
        }
    }
retour KO: JSON: { "success": false, "error_code": "CODE", "error_message": "MESSAGE" }
"error_code" possibles :
_ERROR_YOU_ARE_NOT_A_ROBOT
_ERROR_PARAMETER_UNKNOWN
_ERROR_PARAMETER_INCOHERENT
_ERROR_CONNEXION_DATABASE
_ERROR_MAINTENANCE_EN_COURS
_ERROR_CALLING_API
_ERROR_EXCEPTION
_ERROR_UNKNOWN

la signification des codes erreurs se trouve dans le paramètre "error_message"

user-list-load

Récupération de tous les utilisateurs.
Paramètre Valeur Type

token

str200
obligatoire
retour OK: JSON: { "success": true,
        "userList": [
          {
             "id_user": "A36",
             "login": "A70",
             "nature": "praticien/assistant/robot",
             "actif": 0/1,
             "colonne": 0/1, //possède une colonne dans le planning
             "titre": "A15",
             "nom": "A60",
             "prenom": "A60",
             "initiales": "A2",
             "profession": "A60",
             "specialites": "TEXT",
             "deleted": 0/1,
             "dt_utc_deleted": null/"timestamp"
          },
          {
             "id_user": "A36",
             "login": "170",
             ...,
          }
       ]
    }
retour KO: JSON: { "success": false, "error_code": "CODE", "error_message": "MESSAGE" }
"error_code" possibles :
_ERROR_YOU_ARE_NOT_A_ROBOT
_ERROR_PARAMETER_UNKNOWN
_ERROR_PARAMETER_INCOHERENT
_ERROR_CONNEXION_DATABASE
_ERROR_MAINTENANCE_EN_COURS
_ERROR_CALLING_API
_ERROR_EXCEPTION
_ERROR_UNKNOWN

la signification des codes erreurs se trouve dans le paramètre "error_message"

Résultat retour appel fonction API

URL appelée :

data envoyés en POST :

réponse JSON :