La documentation est accessible en ligne au sein de la documentation Publik : https://doc-publik.entrouvert.com/dev/api-agendas/.
Elle est synchronisées avec les pages suivantes, qui permettent de l'éditer.→ https://doc-publik.entrouvert.com/admin-fonctionnel/prises-de-rendez-vous/
Les informations sur un évènement sont accessibles à l’adresse /api/agenda/SLUG-DE-LAGENDA/status/SLUG-DE-LEVENEMENT/
via la méthode HTTP GET
.
GET /api/agenda/foo-bar/status/event-slug/ { "err": 0, "id": "event-slug", "slug": "event-slug", "text": "Event", "label": "Event", "date": "2020-06-11", "datetime": "2020-06-11 10:00:00", "description": null, "pricing": null, "url": null, "disabled": true, "checked": false, "api": { "bookings_url": "http://chrono.dev.publik.love/api/agenda/foo-bar/bookings/event-slug/", "fillslot_url": "http://chrono.dev.publik.love/api/agenda/foo-bar/fillslot/event-slug/", "status_url": "http://chrono.dev.publik.love/api/agenda/foo-bar/status/event-slug/", "check_url": "http://chrono.dev.publik.love/api/agenda/foo-bar/check/event-slug/", }, "places": { "available": 0, "full": true, "has_waiting_list": false, "reserved": 3, "total": 3 } }
Quand une liste d'attente existe, le dictionnaire places
est complété ainsi :
... "places": { "available": 0, "full": true, "reserved": 5, "total": 30, "has_waiting_list": true, "waiting_list_total": 10, "waiting_list_reserved": 2, "waiting_list_available": 8, "waiting_list_activated": true }
Le booléen waiting_list_activated
signifie que la prochaine réservation sera envoyée en liste d'attente.
La liste des réservations d’un utilisateur pour un évènement donné est accessible à l’adresse /api/agenda/SLUG-DE-LAGENDA/bookings/SLUG-DE-LEVENEMENT/
via la méthode HTTP GET
. Le paramètre user_external_id
est obligatoire pour désigner l’utilisateur.
GET /api/agenda/foo-bar/bookings/event-slug/?user_external_id=xxx { "err": 0, "data": [ {"id": 1, "in_waiting_list": true}, {"id": 2, "in_waiting_list": false} ] }
Un évènement peut être marqué comme pointé via un appel à l’adresse /api/agenda/SLUG-DE-LAGENDA/check/SLUG-DE-LEVENEMENT/
via la méthode HTTP GET
.
GET /api/agenda/foo-bar/check/event-slug/ { "err": 0, }
L’ajout d’un évènement s’effectue par un appel à l’adresse /api/agenda/SLUG-DE-LAGENDA/event/
via la méthode HTTP POST
.
Deux paramètres doivent obligatoirement être présents.
Nom | Description | Exemple |
start_datetime | Date et heure | "2021-10-22 09:45", sous forme de gabarit {{today |date:"Y-m-d"}} {{today |time:"H:i"}} |
places | Nombre de places | 10 |
Paramètres optionnels.
Nom | Description | Exemple |
label | Libellé optionnel pour identifier la date | "..." |
duration | Durée (en minutes) | 90 |
publication_datetime | Date·heure de publication | "2021-10-07 10:00", sous forme de gabarit, par exemple {{today |date:"Y-m-d 10:00"}} |
waiting_list_places | Places dans la liste d’attente | 3 |
description | Description | "..." |
pricing | Tarif (text) | "2€", "gratuit", ... |
url | URL vers un site tiers | "https://doc-publik.entrouvert.com" |
Des paramètres supplémentaires permettent de définir un événement
récurrent :
Nom | Description | Exemple |
recurrence_days | Jours de la récurrence | "0,1,6" pour lundi, mardi et dimanche |
recurrence_week_interval | Répéter toutes X semaines | 1 (défaut), 2 ou 3 |
recurrence_end_date | Date de fin de la récurrence | "2021-10-20" |
Les jours de la récurrence et la date de fin de récurrence doivent
être fournis pour créer un événement récurrent.
POST /api/agenda/SLUG-DE-LAGENDA/event/ { "data" : { "date" : "2021-11-22", "datetime" : "2021-11-22 09:45:00", "description" : "Une description associée", "duration" : 90, "id" : "mon-evenement", "label" : "Mon événement", "pricing" : "2€", "recurrence_days" : [ 0, 1, 6 ], "recurrence_end_date" : "2021-10-20", "recurrence_week_interval" : 2, "slug" : "mon-evenement", "text" : "Mon événement", "url" : "https://doc-publik.entrouvert.com" }, "err" : 0 }
Les événements sont modifiables à l’adresse /api/agenda/SLUG-DE-LAGENDA/event/SLUG-DE-LEVENEMENT/
via la méthode HTTP PATCH
.
Les paramètres utilisables sont les mêmes que ceux de la requête d’ajout.
Il n'y a pas besoin de passer l'ensemble des paramètres, seul les paramètres fournis seront mis à jour.
PATCH /api/agenda/foo-bar/event/mon-evenement/ (même retour que pour la méthode POST)
Il y a cependant certaines restrictions :
On ne peut pas modifier les paramètres start_datetime
, recurrence_days
et recurrence_week_interval
{ "err": 1, "err_class": "start_datetime cannot be modified because some recurrences have bookings attached to them." }
On ne peut pas réduire la date de fin de récurrence
(recurrence_end_date
) avant un la date de la dernière réservation faite sur l’événement.
{ "err": 1, "err_class": "recurrence_end_date cannot be modified because bookings exist after this date." }
Les champs publication_datetime
et ceux définissant la
récurrence (recurrence_days
, recurrence_week_interval
etrecurrence_end_date
) ne sont pas modifiables sur les récurrences
d’événements récurrents.
{ "err": 1, "err_class": "publication_datetime cannot be modified on an event recurrence" }
La demande : exprimée par Alfortville
https://dev.entrouvert.org/projects/alfortville-gru/wiki/File_d%E2%80%99attente
Idéalement lien avec Chrono pour insérer les créneaux depuis flux dans créneaux libres des RV
mais pour ne pas complexifier dans un premier temps, on pourrait séparer les agents ayant des RV fixés par Chrono, des agents dispos pour recevoir le flux.
A terme serait bien de "travailler sur un aspect back-office de chrono : présentation "graphique" des créneaux dispos selon un type de rendez-vous choisi" (Thomas)
"On peut supposer que les agents traitants disposent d'une vue leur donnant la prochaine personne à prendre et permettant de dire c'est fini, ou ça va durer plus longtemps que prévu." (Benjamin)
Lien également avec welco : choix compétence peut guider directement vers bonne démarche.
Bureau - 1-n > Ouverture < *-* - Compétence
^
1
|
*
|
Période
Les types de rendez-vous d’un agenda sont accessibles à l’adresse /api/agenda/SLUG-DE-LAGENDA/meetings/
via la méthode HTTP GET
.
GET /api/agenda/rdvs-autre/meetings/ { "data": [ { "api": { "datetimes_url": "https://chrono.dev.publik.love/api/agenda/rdvs-autre/meetings/base/datetimes/" }, "duration": 30, "id": "base", "text": "base" }, { "api": { "datetimes_url": "https://chrono.dev.publik.love/api/agenda/rdvs-autre/meetings/court/datetimes/" }, "duration": 15, "id": "court", "text": "court" } ] }
De manière analogue, il est possible de préciser un type de rendez-vous et d’obtenir les informations le concernant via un appel à l’adresse /api/agenda/SLUG-DE-LAGENDA/meetings/SLUG-DU-TYPE-DE-RDV/
.
GET /api/agenda/rdvs-autre/meetings/base/ { "data": { "api": { "datetimes_url": "https://chrono.dev.publik.love/api/agenda/rdvs-autre/meetings/base/datetimes/" }, "duration": 30, "id": "base", "text": "base" } }
Les guichets d’un agenda sont accessibles à l’adresse /api/agenda/SLUG-DE-LAGENDA/desks/
via la méthode HTTP GET
.
GET /api/agenda/rdvs-autre/desks/ { "data": [ { "id": "aa", "text": "aa" }, { "id": "bb", "text": "bb" }, { "id": "guichet-1", "text": "Guichet 1" } ] }
Les ressources d’un agenda sont accessibles à l’adresse /api/agenda/SLUG-DE-LAGENDA/resources/
via la méthode HTTP GET
.
GET /api/agenda/rdvs-autre/resources/ { "data": [ { "id": "resource-1", "text": "Resource 1", "description": "Foo bar resource 1" }, { "id": "resource-2", "text": "Resource 2", "description": "Foo bar resource 2" } ] }
La liste des réservations d’un utilisateur est accessible à l’adresse /api/bookings/
via la méthode HTTP GET
.
Nom | Description | Exemple |
user_external_id | Identifiant unique de l’utilisateur (obligatoire). | {{form_user_nameid}} |
agenda | Restreindre les réservations à un agenda. | Slug d’un agenda. |
category | Restreindre les réservations à une catégorie d’agenda. | Slug d’une catégorie. |
date_start | Filtrer les réservations selon leur date de début. | 2021-09-15 |
date_end | Filtrer les réservations selon leur date de fin. | 2021-09-20 |
GET /api/bookings/?user_external_id=xxx { "err": 0, "data": [ { "id": 4, "in_waiting_list": false, "user_was_present": true, "user_absence_reason": "", "extra_data": null }, { "id": 11, "in_waiting_list": false, "user_was_present": null, "user_absence_reason": "", "extra_data": null } ] }
Les informations sur une réservation sont accessibles à l’adresse /api/booking/ID-DE-LA-RESERVATION/
via la méthode HTTP GET
.
GET /api/booking/4/ { "err": 0, "data": { "booking_id": 4, "in_waiting_list": false, "user_was_present": true, "user_absence_reason": "", "extra_data": null } }
{ "err": 1, "err_class": "booking is cancelled" }
Les informations sur une réservation sont modifiables à l’adresse /api/booking/ID-DE-LA-RESERVATION/
via la méthode HTTP PATCH
.
Nom | Description | Exemple |
user_was_present | Information de pointage témoignant de la présence de l’utilisateur. | true |
user_absence_reason | Motif d’absence |
Il est possible de passer n’importe quel paramètre en plus de ceux ci-dessus : ils seront enregistrés et apparaîtront dans la clé extra_data
de l’API qui retourne les informations d’une réservation.
PATCH /api/booking/4/ { "err": 0, "booking_id": 4, }
{ "err": 1, "err_class": "booking is cancelled" }
{ "err": 3, "err_class": "booking is in waiting list" }
{ "err": 5, "err_class": "event is marked as checked" }
Il est possible d’annuler une réservation grâce à un appel à l’adresse /api/booking/ID-DE-LA-RESERVATION/cancel/
via la méthode HTTP POST
.
POST /api/booking/4/cancel/ { "err": 0, "booking_id": 4, }
{ "err": 1, "err_class": "already cancelled" }
Il est possible de déplacer une réservation de la liste d’attente vers la liste principale grâce à un appel à l’adresse /api/booking/ID-DE-LA-RESERVATION/accept/
via la méthode HTTP POST
.
POST /api/booking/4/accept/ { "err": 0, "booking_id": 4, "overbooked_places": 0 }
{ "err": 1, "err_class": "booking is cancelled" }
{ "err": 3, "err_class": "booking is not in waiting list" }
Inversement, il est possible de déplacer une réservation de la liste principale vers la liste d’attente grâce à un appel à l’adresse /api/booking/ID-DE-LA-RESERVATION/suspend/
via la méthode HTTP POST
.
POST /api/booking/4/accept/ { "err": 0, "booking_id": 4, }
{ "err": 1, "err_class": "booking is cancelled" }
{ "err": 3, "err_class": "booking is already in waiting list" }
Il est possible de modifier le nombre de places prises par une réservation grâce à un appel à l’adresse /api/booking/ID-DE-LA-RESERVATION/resize/
via la méthode HTTP POST
.
Nom | Description | Exemple |
count |
Nombre de places. | 2 |
POST /api/booking/4/resize/ { "err": 0, "booking_id": 4, }
{ "err": 1, "err_class": "booking is cancelled" }
{ "err": 3, "err_class": "sold out" }
Il est possible d’anonymiser une réservation grâce à un appel à l’adresse /api/booking/ID-DE-LA-RESERVATION/anonymize/
via la méthode HTTP POST
.
POST /api/booking/4/anonymize/ { "err": 0, "booking_id": 4, }
Il est possible de supprimer une réservation grâce à un appel à l’adresse /api/booking/ID-DE-LA-RESERVATION/
via la méthode HTTP DELETE
.
DELETE /api/booking/4/ { "err": 0, "booking_id": 4, }
{ "err": 1, "err_class": "booking is cancelled" }
La liste des agendas est accessible à l’adresse /api/agenda/
via la méthode HTTP GET
.
Nom | Description | Exemple |
q | Filtrer les agendas selon leur slug. | q=piscine retournera les agendas dont les slugs sont « piscine_1 » et « first_piscine » mais pas « salle_des_fetes ». |
category | Filtrer les agendas selon leur catégorie. | |
with_open_events | Exclure les agendas qui n’ont pas d’évènements ouverts. | with_open_events=true ne retournera que les agendas ayant des évènements ouverts. |
GET /api/agenda/ { "data": [ { "text": "Un agenda", "id": "un-agenda", "slug": "un-agenda", "kind": "events", "minimal_booking_delay": 1, "minimal_booking_delay_in_working_days": False, "maximal_booking_delay": 56, "edit_role" : "Agent", "view_role" : "Agent", "category" : "une-categorie", "absence_reasons": [ {"id": "reason-1", "slug": "reason-1", "text": "Reason 1", "label": "Reason 1"}, {"id": "reason-2", "slug": "reason-2", "text": "Reason 2", "label": "Reason 2"}, ], "api": { "datetimes_url": "http://chrono.dev.publik.love/api/agenda/un-agenda/datetimes/", "fillslots_url": "http://chrono.dev.publik.love/api/agenda/un-agenda/fillslots/", }, }, { "text": "Un autre agenda", "id": "un-autre-agenda", "slug": "un-autre-agenda", "kind": "meetings", "minimal_booking_delay": 1, "maximal_booking_delay": 56, "edit_role" : "Agent", "view_role" : "Agent", "category" : "une-categorie", "resources": [ {"id": "resource-1", "text": "Resource 1", "description": "Foo bar Resource 1"}, {"id": "resource-2", "text": "Resource 2", "description": "Foo bar Resource 2"}, ], "api": { "meetings_url": "http://chrono.dev.publik.love/api/agenda/un-autre-agenda/meetings/", "desks_url": "http://chrono.dev.publik.love/api/agenda/un-autre-agenda/desks/", "resources_url": "http://chrono.dev.publik.love/api/agenda/un-autre-agenda/resources/", "fillslots_url": "http://chrono.dev.publik.love/api/agenda/un-autre-agenda/fillslots/", }, }, }
L’ajout d’un agenda s’effectue par un appel à l’adresse /api/agenda/
via la méthode HTTP POST
.
Cette procédure est commune aux agendas de type rendez-vous et évènement.
Deux paramètres doivent obligatoirement être présents.
Nom | Description | Exemple |
slug | Identifiant pour adresse URL | "mon-agenda" |
label | Libellé | "Mon Agenda" |
La plupart des paramètres optionnels sont communs aux deux types d’agenda.
Nom | Description | Exemple |
kind | Type de l’agenda | "events" (défaut), "meetings" ou "virtual" |
minimal_booking_delay | Nombre de jours minimal (borne incluse) pour réserver | 1 |
maximal_booking_delay | Nombre de jours maximal (borne exclue) pour réserver | 56 |
anonymize_delay | Délai d’anonymisation (en jours) | 30 |
edit_role | Rôle d’édition | "Administateur fonctionnel" |
view_role | Rôle de visualisation | "Administateur fonctionnel" |
category | Slug de la catégorie de l'agenda | "une-category" |
Les paramètres qui encadrent la période de réservation sont mieux décrits ici
Un paramètre supplémentaire peut être inclut sur les agendas évènements :
Nom | Description | Exemple |
minimal_booking_delay_in_working_days | Délai de réservation minimal en jours ouvrés (booléen) | false (défaut), true |
POST /api/agenda/ { "data" : [ { "api" : { "datetimes_url" : "https://chrono.dev.publik.love/api/agenda/mon-agenda/datetimes/", "fillslots_url" : "https://chrono.dev.publik.love/api/agenda/mon-agenda/fillslots/" }, "category" : "une-categorie", "edit_role" : "Administrateur fonctionnel", "id" : "mon-agenda", "kind" : "events", "maximal_booking_delay" : 56, "minimal_booking_delay" : 1, "minimal_booking_delay_in_working_days" : true, "slug" : "mon-agenda", "text" : "Mon Agenda", "view_role" : "Administrateur fonctionnel" } ], "err" : 0 }
Les agendas sont modifiables à l’adresse /api/agenda/SLUG-DE-LAGENDA/
via la méthode HTTP PATCH
.
Les paramètres utilisables sont les mêmes que ceux de la requête d’ajout, à l'exception du paramètre kind
, car le type d'un agenda existant ne peut pas être modifié.
Il n'y a pas besoin de passer l'ensemble des paramètres, seul les paramètres fournis seront mis à jour.
PATCH /api/agenda/agenda-evenement/ (même retour que pour la méthode POST)
Les informations de paramétrage d’un agenda sont accessibles à l’adresse /api/agenda/SLUG-DE-LAGENDA/
via la méthode HTTP GET
.
GET /api/agenda/agenda-evenement/ { "data": { "api": { "datetimes_url": "https://chrono.dev.publik.love/api/agenda/agenda-evenement/datetimes/", "fillslots_url": "https://chrono.dev.publik.love/api/agenda/agenda-evenement/fillslots/" }, "id": "agenda-evenement", "kind": "events", "maximal_booking_delay": 56, "minimal_booking_delay": 1, "minimal_booking_delay_in_working_days": True, "slug": "agenda-evenement", "text": "Agenda Evenement", "edit_role" : "Agent", "view_role" : "Agent", "category" : "une-categorie", } }
La suppression d'un agenda s'effectue via un appel à l’adresse /api/agenda/SLUG-DE-LAGENDA/
via la méthode HTTP DELETE
.
L'appel échouera si l'agenda contient des réservation actives.
DELETE /api/agenda/agenda-evenement/ { "err": 0, }
Deux API existent pour récupérer les créneaux réservables d’un agenda, selon s’il est de type rendez-vous ou évènements. Certains paramètres sont communs :
Nom | Description | Valeurs permises | Notes |
date_start | Filtrer les évènements selon leur date de début. | Date au format YYYY-MM-DD. | {{today |date:"Y-m-d"}} retournera les événements disponibles à partir d’aujourd’hui. |
date_end | Filtrer les évènements selon leur date de fin. | Date au format YYYY-MM-DD. | {{today |add_days:16 |date:"Y-m-d"}} retournera les événements disponibles avant J+15 (la borne supérieure étant exclue). |
user_external_id | Inclure des informations supplémentaires en fonction de l’utilisateur spécifié. | Identifiant unique d’un utilisateur. | Chaque créneau contiendra une nouvelle clé booked_for_external_user qui indiquera si l’utilisateur a déjà une réservation. |
exclude_user_external_id | Désactiver les créneaux pour lesquels l’utilisateur spécifié a déjà une réservation. | Identifiant unique d’un utilisateur. | Les créneaux déjà réservés apparaîtront désactivés, de manière analogue à s’ils étaient complets. |
hide_disabled | Exclure les créneaux désactivés. | true ou false |
|
bypass_delays | Ne pas prendre en compte les délais de réservation. | true ou false (valeur par défaut) |
Usuellement pour permettre à un agent de passer outre ceux-ci; le paramètre doit alors également être mentionné au moment de la réservation (l’appel à l’API « fillslot »). |
La liste des évènements d’un agenda est accessible à l’adresse /api/agenda/SLUG-DE-LAGENDA/datetimes/
via la méthode HTTP GET
.
Nom | Description | Valeurs permises | Notes |
min_places | Filtrer les évènements selon leur nombre de places libres minimum. | Entier supérieur à 1. | Si un utilisateur souhaite réserver 2 places, il est utile de ne présenter que les évènements où au moins deux places sont vacantes. |
events | Inclure les évènements futurs (par défaut) ou passés. | all , future ou past . |
GET /api/agenda/foo-bar/datetimes/ { "err": 0, "data": [ { "id": "event-slug", "slug": "event-slug", "text": "Event", "label": "Event", "date": "2020-06-11", "datetime": "2020-06-11 10:00:00", "description": null, "pricing": null, "url": null, "disabled": true, "api": { "bookings_url": "http://chrono.dev.publik.love/api/agenda/foo-bar/bookings/event-slug/", "fillslot_url": "http://chrono.dev.publik.love/api/agenda/foo-bar/fillslot/event-slug/", "status_url": "http://chrono.dev.publik.love/api/agenda/foo-bar/status/event-slug/", "check_url": "http://chrono.dev.publik.love/api/agenda/foo-bar/check/event-slug/", }, "places": { "available": 0, "full": true, "has_waiting_list": false, "reserved": 3, "total": 3 } }, { "id": "event2-slug", "slug": "event2-slug", "text": "Event 2", "label": "Event 2", "date": "2020-06-12", "datetime": "2020-06-12 10:00:00", "description": null, "pricing": null, "url": null, "disabled": false, "api": { "bookings_url": "http://chrono.dev.publik.love/api/agenda/foo-bar/bookings/event2-slug/", "fillslot_url": "http://chrono.dev.publik.love/api/agenda/foo-bar/fillslot/event2-slug/", "status_url": "http://chrono.dev.publik.love/api/agenda/foo-bar/status/event2-slug/", "check_url": "http://chrono.dev.publik.love/api/agenda/foo-bar/check/event2-slug/", }, "places": { "available": 3, "full": false, "has_waiting_list": false, "reserved": 0, "total": 3 } } ], "meta": { "no_bookable_datetimes": false, "bookable_datetimes_number_total": 2, "bookable_datetimes_number_available": 1, "first_bookable_slot": { "id": "event2-slug", "slug": "event2-slug", ... } } }
La liste des évènements d’un agenda est accessible à l’adresse /api/agenda/SLUG-DE-LAGENDA/meetings/SLUG-DU-TYPE-DE-RDV/datetimes/
via la méthode HTTP GET
.
Nom | Description | Valeurs permises | Notes |
resources | Filtrer les créneaux où certaines resources sont disponibles. | Liste de slugs séparés par des virgules. | |
events | Inclure les évènements futurs (par défaut) ou passés. | all , future ou past . |
|
minutes | Filtrer les créneaux sur l'horaire de début du créneau | Des nombres entiers de 0 à 59, séparés par des virgules | 0,30 retournera les créneaux qui commencent au heures piles et au demi-heures. |
GET /api/agenda/rdvs-autre/meetings/base/datetimes/ { "data": [ { "api": { "fillslot_url": "https://chrono.dev.publik.love/api/agenda/rdvs-autre/fillslot/19:2020-08-05-1500/" }, "date": "2020-08-05", "datetime": "2020-08-05 15:00:00", "disabled": true, "id": "19:2020-08-05-1500", "text": "5 août 2020 15:00" }, { "api": { "fillslot_url": "https://chrono.dev.publik.love/api/agenda/rdvs-autre/fillslot/19:2020-08-05-1515/" }, "date": "2020-08-05", "datetime": "2020-08-05 15:15:00", "disabled": false, "id": "19:2020-08-05-1515", "text": "5 août 2020 15:15" }, { "api": { "fillslot_url": "https://chrono.dev.publik.love/api/agenda/rdvs-autre/fillslot/19:2020-08-05-1530/" }, "date": "2020-08-05", "datetime": "2020-08-05 15:30:00", "disabled": false, "id": "19:2020-08-05-1530", "text": "5 août 2020 15:30" } ], "meta": { "no_bookable_datetimes": false, "bookable_datetimes_number_total": 3, "bookable_datetimes_number_available": 2, "first_bookable_slot": { "api": { "fillslot_url": "https://chrono.dev.publik.love/api/agenda/rdvs-autre/fillslot/19:2020-08-05-1515/" }, "date": "2020-08-05", "datetime": "2020-08-05 15:15:00", "disabled": false, "id": "19:2020-08-05-1515", "text": "5 août 2020 15:15" } } }
Il est possible d’obtenir une liste d’évènements aggrégés depuis plusieurs agendas via un appel HTTP GET
à l’adresse /api/agendas/datetimes/
(noter les pluriels).
Nom | Description | Exemple |
agendas | Identifiants des agendas. | agenda-slug,agenda2-slug |
Ce paramètre est obligatoire et vient s’ajouter à la liste des paramètres acceptés par l’API de récupération des évènements classique.
La réponse est la même que celle de l’API de récupération des évènements classique. La seule différence est que les identifiants des évènements (clé "id") sont constitués de la concaténation entre le slug de l’agenda et le slug de l’évènement. Cela permet leur réutilisation dans l’API de réservation multiple.
La liste des évènements récurrents définis sur un agenda est accessible à l’adresse /api/agendas/recurring-events/?agendas=SLUG-DE-LAGENDA
via la méthode HTTP GET
.
Attention, les occurrences d’un évènement récurrents sont bien retournées par l’API /datetimes/
décrite plus haut. Cette API n’est utile que dans des cas très spécifiques, où l’on voudrait récupérer l’évènement récurrent source plutôt que les évènements directement réservables qui en découlent.
Les évènements retournés sont réservables grâce à l’API de réservation multiple des évènements récurrents.
Nom | Description | Exemple |
agendas | Identifiants des agendas. | agenda-slug,agenda2-slug |
Ce paramètre est obligatoire.
GET /api/agendas/recurring-events/?agenda=SLUG-DE-LAGENDA { "data": [ { "date": "2021-09-06", "datetime": "2021-09-06 14:00:00", "description": null, "id": "xxx@event-slug:0", "pricing": null, "text": "Lundi: Évènement", "url": null }, { "date": "2021-09-21", "datetime": "2021-09-21 14:00:00", "description": null, "id": "xxx@other-event-slug:1", "pricing": null, "text": "Mardi: Autre Évènement", "url": null } ] }
La réservation d'un créneau s'effectue par un appel à l’adresse /api/agenda/SLUG-DE-LAGENDA/fillslot/IDENTIFIANT-DU-CRENEAU/
via la méthode HTTP POST
.
Cette procédure est commune aux agendas de type rendez-vous et évènement, seul le format de l'identifiant du créneau diffère.
Cette adresse est mentionnée dans le champ fillslot_url
obtenu en demandant la liste des créneaux disponibles, ce qui évite la plupart du temps d'avoir à la construire manuellement.
La plupart des paramètres sont communs aux deux types d’agenda.
Nom | Description | Exemple |
backoffice_url | URL de la démarche effectuant la réservation | {{form_url_backoffice}} |
form_url | URL de la demande | {{form_url}} |
cancel_callback_url | URL à appeler lors d’une annulation | |
cancel_booking_id | Identifiant de réservation à annuler | 45 |
count | Nombre de places à réserver | 2 |
label | Texte arbitraire pour l’affichage en backoffice | {{form_name|safe}} |
user_display_label | Texte pour affichage dans export ics | {{form_name|safe}} |
user_name | Nom complet l’utilisateur (peut être décomposé et remplacé par user_first_name et user_last_name) | {{form_user_display_name}} |
user_first_name | Prénom de l’utilisateur | {{form_user_var_first_name}} |
user_last_name | Nom de l’utilisateur | {{form_user_var_last_name}} |
user_email | Adresse de courriel de l’utilisateur | {{form_user_email}} |
user_phone_number | Numéro de téléphone de l’utilisateur | {{form_user_var_phone}} |
user_external_id | Identifiant unique de l’utilisateur | {{form_user_nameid}} |
exclude_user | Interdire à l’utilisateur d’avoir plusieurs réservations en même temps | true (false par défaut) |
bypass_delays | Ne pas prendre en compte les délais de réservation | true (false par défaut) |
extra_emails | Adresses de courriel supplémentaires où envoyer un rappel | {{form_var_emails_raw}} ou "a@example.com,b@example.com" |
extra_phone_numbers | Numéros de téléphone supplémentaires où envoyer un rappel | {{form_var_numbers_raw}} ou "+33122334455,+33122334466" |
absence_callback_url | URL à appeler lorsque l’événement est marqué comme pointé, en cas d’absence | |
presence_callback_url | URL à appeler lorsque l’événement est marqué comme pointé, en cas de présence |
Il est possible de passer n’importe quel paramètre en plus de ceux ci-dessus : ils seront enregistrés et apparaîtront dans la clé extra_data
de l’API qui retourne les informations d’une réservation.
Les appels à absence_callback_url et presence_callback_url se feront en POSTant un objet avec les clés user_was_present (booléen), user_check_type_slug (identifiant du motif d’absence), user_check_type_label (libellé du motif d’absence).
Le cancel_booking_id permet de combiner l’annulation d’un créneau et la réservation d’un nouveau (par exemple sur un agenda différent).
Certains paramètres supplémentaires peuvent être inclus :
Nom | Description | Exemple |
events | Restreindre la réservation aux évènements passés ou futurs ("future" par défaut) | "future", "past", "all" |
force_waiting_list | Forcer le passage en liste d’attente | true |
POST /api/agenda/foo-bar/fillslot/event-slug/ { "agenda": { "label": "Foo bar", "slug": "foo-bar" }, "api": { "accept_url": "http://chrono.dev.publik.love/api/booking/8/accept/", "anonymize_url": "http://chrono.dev.publik.love/api/booking/8/anonymize/", "booking_url": "http://chrono.dev.publik.love/api/booking/8/", "cancel_url": "http://chrono.dev.publik.love/api/booking/8/cancel/", "ics_url": "http://chrono.dev.publik.love/api/booking/8/ics/", "suspend_url": "http://chrono.dev.publik.love/api/booking/8/suspend/" }, "booking_id": 8, "datetime": "2017-05-21 17:00:00", "end_datetime": null, "err": 0, "in_waiting_list": False, "places": { "available": 19, "full": False, "has_waiting_list": False, "reserved": 1, "total": 20 } }
Certains paramètres supplémentaires peuvent être inclus :
Nom | Description | Exemple |
use_color_for | Libellé auquel associer la couleur d’un rendez-vous dans le backoffice |
POST /api/agenda/rdv-pref/fillslot/18:2020-06-16-1000/ { "agenda": { "label": "rdv pref", "slug": "rdv-pref" }, "api": { "anonymize_url": "https://chrono.dev.publik.love/api/booking/50/anonymize/", "cancel_url": "https://chrono.dev.publik.love/api/booking/50/cancel/", "ics_url": "https://chrono.dev.publik.love/api/booking/50/ics/", "suspend_url": "https://chrono.dev.publik.love/api/booking/50/suspend/" }, "booking_id": 50, "datetime": "2020-06-16 10:00:00", "desk": { "label": "ds", "slug": "ds" }, "duration": 30, "end_datetime": "2020-06-16 10:30:00", "err": 0, "in_waiting_list": false, "resources": [] }
Il est possible de réserver plusieurs évènements en une seule fois via un appel POST
à l’adresse /api/agenda/SLUG-DE-LAGENDA/events/fillslots/
.
Par rapport à l’appel classique de réservation d’un évènement, deux paramètres doivent obligatoirement être présents.
Nom | Description | Exemple |
user_external_id | Identifiant unique de l’utilisateur. Grâce à cet identifiant, chaque appel aura pour effet de mettre à jour les réservations. | {{form_user_nameid}} |
slots | Slugs des évènements à réserver. Une valeur vide aura pour effet d’annuler les réservations de l’utilisateur. | {{form_var_event_raw|join:","}} |
POST /api/agenda/foo-bar/events/fillslots/ { "err": 0, "booking_count": 3, "waiting_list_events": [ { "id": "event-slug", "slug": "event-slug", ... } ], "cancelled_booking_count": 0 }
Il est possible de réserver plusieurs évènements qui se trouvent sur des agendas différents via un appel HTTP POST
à l’adresse /api/agendas/events/fillslots/
.
Nom | Description | Exemple |
agendas | Slugs des agendas concernés par l’appel. Ils permettent de savoir quelles réservations mettre à jour. | agenda-slug,agenda2-slug,agenda3-slug |
Par rapport à l’appel classique de réservation d’un évènement, deux paramètres doivent obligatoirement être présents.
Nom | Description | Exemple |
user_external_id | Identifiant unique de l’utilisateur. Grâce à cet identifiant, chaque appel aura pour effet de mettre à jour les réservations. | {{form_user_nameid}} |
slots | Slugs des évènements à réserver. Une valeur vide aura pour effet d’annuler les réservations de l’utilisateur. | agenda-slug@event-slug,agenda2-slug@event-slug |
POST /api/agendas/events/fillslots/?agendas=agenda-slug { "err": 0, "booking_count": 3, "waiting_list_events": [ { "id": "event-slug", "slug": "event-slug", ... } ], "cancelled_booking_count": 0 }
Il est possible de réserver un ou plusieurs évènements récurrents, en totalité ou sur une plage temporelle définie, via un appel POST
à l’adresse /api/agendas/recurring-events/fillslots/
.
Nom | Description | Exemple |
agendas | Slugs des agendas concernés par l’appel. | agenda-slug,agenda2-slug,agenda3-slug |
action | Action à réaliser sur les évènements. | update , book ou unbook |
date_start | Réserver seulement les évènements commençant après cette date. | 2021-09-04 |
date_end | Réserver seulement les évènements commençant avant cette date. | 2022-06-21 |
Par rapport à l’appel classique de réservation d’un évènement, deux paramètres doivent obligatoirement être présents.
Nom | Description | Exemple |
user_external_id | Identifiant unique de l’utilisateur. Grâce à cet identifiant, chaque appel aura pour effet de mettre à jour les réservations. | {{form_user_nameid}} |
slots | Slugs et jours des évènements à réserver. | agenda-slug@event-slug:0,agenda-slug@event2-slug:1 pour réserver le premier évènement tous les lundis et le second tous les mardis. |
POST /api/agendas/recurring-events/fillslots/?agendas=agenda-slug { "err": 0, "booking_count": 142, "full_events": [ { "id": "event-slug", "slug": "event-slug", ... } ], "cancelled_booking_count": 0 }
Plan posé par Frédéric, mail "Module de rendez-vous", 5 juin 2016
Voilà pour le côté backoffice.
Pour le frontoffice, c'est simple, il ne doit pas y en avoir, la prise de rendez-vous se fait dans w.c.s. et en première étape il y a tout ce qu'il faut déjà.
Restent les API pour combiner les deux, il me semble qu'on peut juste avoir :
C'est utilisé pour remplir une liste
Ça enregistre le payload (même si ça n'a pas d'importance pour le début) et ça retire une place.
Si jamais il n'y avait plus de place, ça retourne une erreur, que w.c.s. peut traiter. (pour par exemple envoyer dans un statut "File d'attente").
Et voilà.
Juste derrière, on devra ajouter la possibilité de récupérer la liste des rendez-vous pris, pour affichage dans Combo, et à la même occasion avoir pour ceux-ci une URL d'annulation.
Au-delà de ça, quand il s'agira de rendez-vous et plus seulement de quelques événements, il faudra voir côté w.c.s. pour avoir un widget de sélection date/heure adapté (genre présentant les slots disponibles dans une vue type agenda hebdomadaire).
À partir de là, il n'y a plus vraiment de plan, ça dépendra nettement des besoins. Envoi de rappels à l'usager, vue "calendrier" dans le backoffice de w.c.s. (avec les filtres comme sur le listing de
demandes), backoffice côté Chrono pour avoir une vue sur le remplissage des slots, etc.
Spécifications mentionnées dans CCTP de Blois + compléments oraux par S. Briaud le 16/12/15
Cette gestion de RV :Il peut être question d'activités ponctuelles ou récurrentes.
Une activité comporte généralement une liste principale et une liste d'attente.
Pour une activité récurrente il est nécessaire de pouvoir définir un délais de réservation (je ne peux pas réserver moins de 48 heures à l'avance).
Il est possible de s'inscrire à plusieurs activités depuis un même formulaire.
La soumission d'une demande de réservation consomme une place dans le quota disponible (dans certains cas est-il possible que la demande de l'usager ne soit qu'un souhait et que l'agent valide l'application au quota depuis le workflow ?)
Il est possible depuis le workflow de libérer la place (l'agent refuse l'inscription, l'usager annule sa réservation...)
Est-il possible d'afficher le nombre de places restantes à l'usager lors de l'accès au formulaire ?
Est-il possible d'utiliser une condition de sortie de page basée sur le fait qu' une agenda ne dispose plus d'une seule activité disponible ?
Possibilité de fixer des bornes d'age pour une activité, et permettre un filtre côté formulaire sur les activités dans les bornes d'age.
Ville de Meyzieu a mis en place fonctionnalités d'inscription à évènements (spectacles, ...) avec gestion de la capacité et liste d'attente, cf. copie de la slide ci-dessous
Dreux utilise la solution Myrdv (https://myrdv2.espacerendezvous.com).
La Ville de Dreux constate de façon non anecdotique que des usagers font des réservations sur plusieurs créneaux, il est constaté une proportion de 20 % de rendez-vous non honorés.
Pour info, la solution myrdv a une fonctionnalité de blacklistage des usagers trop "demandeurs", cette fonctionnalité n'est pas (encore ?) utilisée à Dreux.
chrono-manage graph_models -o agendas_model.png 'agendas'