Index par titre

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/


Gestion des évènements

Obtenir des informations sur un évènement

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.

Exemple

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.

Obtenir la liste des réservations d’un évènement

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.

Exemple

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}
    ]
}

Agenda évènement : Marquer un évènement comme pointé

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,
}

Ajouter un évènement

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.

Paramètres JSON, corps de la requête

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.

Exemple

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
}

Mettre à jour un événement

Les événements sont modifiables à l’adresse /api/agenda/SLUG-DE-LAGENDA/event/SLUG-DE-LEVENEMENT/ via la méthode HTTP PATCH.

Paramètres JSON, corps de la requête

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.

Exemple

PATCH /api/agenda/foo-bar/event/mon-evenement/

(même retour que pour la méthode POST)

Il y a cependant certaines restrictions :

Restrictions sur les événements récurrents

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." 
}

Restrictions sur les occurrences des événements récurrents

Les champs publication_datetime et ceux définissant la
récurrence (recurrence_days, recurrence_week_interval et
recurrence_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

Généralités

Principe général :

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.

à voir avec Alfortville

Premières réflexions

Notions : Mesures : Plutôt partir sur notion de bureau/guichet :

Bureau - 1-n > Ouverture < *-* - Compétence
^
1 | * |
Période


Gestion des rendez-vous

Obtenir les types de rendez-vous

Les types de rendez-vous d’un agenda sont accessibles à l’adresse /api/agenda/SLUG-DE-LAGENDA/meetings/ via la méthode HTTP GET.

Exemple

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" 
    }
}

Obtenir les guichets

Les guichets d’un agenda sont accessibles à l’adresse /api/agenda/SLUG-DE-LAGENDA/desks/ via la méthode HTTP GET.

Exemple

GET /api/agenda/rdvs-autre/desks/

{
    "data": [
        {
            "id": "aa",
            "text": "aa" 
        },
        {
            "id": "bb",
            "text": "bb" 
        },
        {
            "id": "guichet-1",
            "text": "Guichet 1" 
        }
    ]
}

Obtenir les resources

Les ressources d’un agenda sont accessibles à l’adresse /api/agenda/SLUG-DE-LAGENDA/resources/ via la méthode HTTP GET.

Exemple

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" 
        }
    ]
}

Gestion des réservations

Obtenir la liste des réservations d’un utilisateur

La liste des réservations d’un utilisateur est accessible à l’adresse /api/bookings/ via la méthode HTTP GET.

Paramètres

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

Exemple

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
    }
    ]
}

Obtenir des informations sur une réservation

Les informations sur une réservation sont accessibles à l’adresse /api/booking/ID-DE-LA-RESERVATION/ via la méthode HTTP GET.

Exemple

GET /api/booking/4/

{
    "err": 0,
    "data": {
    "booking_id": 4,
    "in_waiting_list": false,
    "user_was_present": true,
    "user_absence_reason": "",
    "extra_data": null
    }
}

Erreur : réservation annulée

{
    "err": 1,
    "err_class": "booking is cancelled" 
}

Mettre à jour les informations sur une réservation

Les informations sur une réservation sont modifiables à l’adresse /api/booking/ID-DE-LA-RESERVATION/ via la méthode HTTP PATCH.

Paramètres JSON, corps de la requête

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.

Exemple

PATCH /api/booking/4/

{
    "err": 0,
    "booking_id": 4,
}

Erreur : réservation annulée

{
    "err": 1,
    "err_class": "booking is cancelled" 
}

Erreur : réservation en liste d’attente

{
    "err": 3,
    "err_class": "booking is in waiting list" 
}

Erreur : l’évènement est marqué comme déjà pointé

{
    "err": 5,
    "err_class": "event is marked as checked" 
}

Annuler une réservation

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.

Exemple

POST /api/booking/4/cancel/

{
    "err": 0,
    "booking_id": 4,
}

Erreur : réservation déjà annulée

{
    "err": 1,
    "err_class": "already cancelled" 
}

Accepter une réservation

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.

Exemple

POST /api/booking/4/accept/

{
    "err": 0,
    "booking_id": 4,
    "overbooked_places": 0
}

Erreur : réservation annulée

{
    "err": 1,
    "err_class": "booking is cancelled" 
}

Erreur : la réservation n’est pas en liste d’attente

{
    "err": 3,
    "err_class": "booking is not in waiting list" 
}

Suspendre une réservation

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.

Exemple

POST /api/booking/4/accept/

{
    "err": 0,
    "booking_id": 4,
}

Erreur : réservation annulée

{
    "err": 1,
    "err_class": "booking is cancelled" 
}

Erreur : la réservation est déjà en liste d’attente

{
    "err": 3,
    "err_class": "booking is already in waiting list" 
}

Redimensionner une réservation

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.

Paramètres JSON, corps de la requête

Nom Description Exemple
count Nombre de places. 2

Exemple

POST /api/booking/4/resize/

{
    "err": 0,
    "booking_id": 4,
}

Erreur : réservation annulée

{
    "err": 1,
    "err_class": "booking is cancelled" 
}

Erreur : évènement plein

{
    "err": 3,
    "err_class": "sold out" 
}

Anonymiser une réservation

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.

Exemple

POST /api/booking/4/anonymize/

{
    "err": 0,
    "booking_id": 4,
}

Supprimer une réservation

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.

Exemple

DELETE /api/booking/4/

{
    "err": 0,
    "booking_id": 4,
}

Erreur : réservation annulée

{
    "err": 1,
    "err_class": "booking is cancelled" 
}

Informations sur les agendas

Lister les agendas

La liste des agendas est accessible à l’adresse /api/agenda/ via la méthode HTTP GET.

Paramètres

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.

Exemple

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/",
      },
      },
}

Ajouter un agenda

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.

Paramètres JSON, corps de la requête

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

Exemple

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
}

Mettre à jour un agenda

Les agendas sont modifiables à l’adresse /api/agenda/SLUG-DE-LAGENDA/ via la méthode HTTP PATCH.

Paramètres JSON, corps de la requête

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.

Exemple

PATCH /api/agenda/agenda-evenement/

(même retour que pour la méthode POST)

Obtenir des informations sur un agenda

Les informations de paramétrage d’un agenda sont accessibles à l’adresse /api/agenda/SLUG-DE-LAGENDA/ via la méthode HTTP GET.

Exemple

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",
    }
}

Supprimer un agenda

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.

Exemple

DELETE /api/agenda/agenda-evenement/

{
    "err": 0,
}

Obtenir les créneaux d’un agenda

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 »).

Agenda évènement : obtenir l’ensemble des évènements

La liste des évènements d’un agenda est accessible à l’adresse /api/agenda/SLUG-DE-LAGENDA/datetimes/ via la méthode HTTP GET.

Paramètres

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.

Exemple

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",
        ...
    }
    }
}

Agenda rendez-vous : obtenir les créneaux disponibles

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.

Paramètres

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.

Exemple

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" 
        }
    }
}

Agenda évènement : obtenir l’ensemble des évènements de plusieurs agendas

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).

Paramètres

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.

Réponse

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.

Agenda évènement : obtenir les évènements récurrents

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.

Paramètres

Nom Description Exemple
agendas Identifiants des agendas. agenda-slug,agenda2-slug

Ce paramètre est obligatoire.

Exemple

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
    }
    ]
}

Réservation d'un créneau

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.

Paramètres JSON, corps de la requête

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 ","
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).

Agenda évènement

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

Exemple

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
     }
}

Agenda rendez-vous

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

Exemple

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": []
}

Agenda évènement : poser plusieurs réservations

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/.

Paramètres JSON, corps de la requête

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:","}}

Exemple

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
}

Agenda évènement : poser plusieurs réservations sur plusieurs agendas

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/.

Paramètres de l’URL

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

Paramètres JSON, corps de la requête

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

Exemple

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
}

Agenda évènement : réserver toutes les occurrences d’évènements récurrents

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/.

Paramètres de l’URL

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

Paramètres JSON, corps de la requête

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.

Exemple

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
}

Esquisses de spécifications

Plan posé par Frédéric, mail "Module de rendez-vous", 5 juin 2016

Puis, plus tard, ça évoluera avec :

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.

Demandes exprimées

Compréhension de la demande de Blois

Spécifications mentionnées dans CCTP de Blois + compléments oraux par S. Briaud le 16/12/15

Cette gestion de RV : Cas d'usage, côté usager : Point à discuter :

Inscription à des activités

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.

Pê prendre également exemple de Meyzieu

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

Solutions existantes

à Dreux

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.


Sections obsolètes