Documentation en ligne

Enregistrement dans un agenda

Pour une utilisation avancée des agendas, il peut-être utile de consulter leur API spécifique.

C'est dans le workflow que l'on va pouvoir procéder à l'enregistrement dans un agenda, pour prendre, annuler ou encore déplacer une ou plusieurs réservations, grâce à une action d'appel webservice.

L'action d'appel webservice doit être configurée en POST. L'URL à utiliser dans cet appel, en considérant que le champ présentant le choix avait comme identifiant «EVENT », sera {{form_var_EVENT_api_fillslot_url}}.

Afin de permettre un lien depuis l'agenda vers la demande à l'origine de la réservation, l'appel webservice doit inclure les « Données à envoyer dans le corps de la requête » suivantes :

  • label pour le libellé qui sera affiché dans les plages réservées dans les agendas, vue back-office (par exemple pourrait être {{form_name}},
  • user_name pour le nom de l'usager, si défini viendra s'afficher dans la plage réservée à la suite de label,
  • backoffice_url pour la demande vers laquelle créer un lien activé sur le libellé précédent (usuellement doit être {{form_url_backoffice}}),
  • user_display_label pour le libellé qui sera présenté à l'usager (par exemple « Rendez-vous passeport »). Ces deux dernières données ne sont utilisées que dans le cas de génération d'un fichier ics (cf. infra et le tutoriel dédié).
  • cancel_callback_url, optionnel, cf. page Annulation dans un agenda
Il est possible d'ajouter n'importe quelle couple donnée/valeur dans l'appel webservice. La donnée pourra être utilisée ensuite pour configurer un filtre dans l'écran de pointage. Par exemple, si j'utilise regime: "végétarien", je pourrais dans les paramètres de l'écran de pointage indiquer regime comme filtre. Cela permettra d'avoir dans l'écran de pointage un bouton radio pour chaque valeur associée à la donnée regime (Végétarien, Allergique, etc.). Ces boutons radio permettent de n'afficher que les réservations concernées.

L'appel ne doit pas reprendre intégralement  les données de la demande (l'option « Envoyer les données du formulaire » doit rester décochée).

L'appel pourra retourner une erreur {'err': 1, 'reason': 'sold out'} mais plus souvent, ça retournera l'identifiant de la réservation, par exemple :

  {'err': 0, 'booking_id': 14}

Ainsi, en ayant attribué un identifiant à l'appel webservice, par exemple « reservation », on aura désormais un identifiant de réservation accessible dans la variable {{reservation_response_booking_id}}.  Aussi, pour un agenda de type « rendez-vous », la réponse contiendra l'information sur le guichet attribué, par exemple :

  {'err': 0, 'booking_id': 14, 'desk': {'label': 'Guichet C', 'slug': 'guichet-c'}}

Ces réponses contiendront également les adresses à appeler pour agir par la suite sur la réservation, pour demander l'annulation (cancel_url) ou pour accepter une demande ayant été mise en liste d'attente (accept_url).

  {'err': 0, 'booking_id': 14, 'api': {'cancel_url': 'https://...'}}

Ces adresses peuvent alors être utilisés dans un appel webservice, un POST (n'incluant pas les données du formulaire) vers : {{reservation_response_api_cancel_url}}.

Information sur le statut (agendas de type « événements »)

Pour les agendas de type « événements », il existe également un webservice pour connaitre le nombre de places (totales, libres ou réservées), cela passe par l'enregistrement d'un nouvel appel dans le catalogue des webservice,  avec comme URL :

  {{agendas_url}}api/agenda/REUNIONS-D-INFORMATION/status/{{form_var_event_raw}}/

Et également en spécifiant reservations comme identifiant à cet appel. Il devient alors possible d'utiliser « reservations » dans par exemple un commentaire :

  Places dispos : {{webservice.reservations.places.available}}

À propos des appels, plutôt que mettre l'identifiant de l'agenda dans tous les appels, on pourrait passer ça via une option de workflow, qui pourrait être une liste alimentée depuis {{agendas_url}}api/agenda/ (qui reprend la liste des agendas).

Liste d'attente (agendas de type « événements »)

Si un événement dispose d'une liste d'attente, le retour d'une réservation peut contenir un attribut in_waiting_list à True.

  {'err': 0, 'booking_id': 14, 'in_waiting_list': True, 'api': {...}}

Pour changer de statut vers un statut d'attente, une condition sur reservation_response_in_waiting_list peut alors être posée.

Dans le statut d'attente, pour accepter la réservation, la sortir de la file d'attente, un appel à l'API « accept » doit être fait, un POST vers {{reservation_response_api_accept_url}}.

Quand une liste d'attente existe, le webservice de statut fournit trois informations supplémentaires, waiting_list_total, waiting_list_reserved, waiting_list_available.

Réserver plusieurs places (agendas de type « événements »)

L'API de réservation permet également en un appel de réaliser plusieurs réservations pour le même événement, il suffit de passer dans l'URL un paramètre count avec le nombre de places à réserver comme valeur, ex :

{{agendas_url}}api/agenda/REUNIONS-D-INFORMATION/fillslot/{{form_var_event_raw}}/?count={{form_var_nb_places}}

Réservation multiple (agendas de type « événements »)

Il est possible de réaliser une réservation sur plusieurs événements.

Tout d'abord dans le formulaire, utiliser un champ de type liste à choix multiple plutôt qu'un champ de type liste. Ensuite dans le workflow, l'action d'appel webservice qui pose la réservation doit utiliser l'URL suivant (noter le « s » final à fillslots) :

{{agendas_url}}api/agenda/REUNIONS-D-INFORMATION/events/fillslots/

Cet appel doit inclure dans le corps de la requête, en plus des données envoyées dans le cas d'une réservation simple, les données suivantes  :

  • slots pour les identifiants des événements à réserver (usuellement {{form_var_event_raw|join:","}})
  • user_external_id pour lier les réservations à l'usager (usuellement {{ form_user_nameid }})

La réponse de cet appel webservice est très différente de celle de la réservation unique, elle inclut seulement :

  • booking_count, le nombre d'évènement réservés
  • waiting_list_events, le détail des évènements où l'inscription s'est faite sur liste d'attente
  • cancelled_booking_count, le nombre d'inscriptions annulées par l'appel

Les réservation d'un usager sont mises à jours automatiquement. Par exemple, si deux évènements ont lieu lundi et mardi, un premier appel avec {'events': 'lundi,mardi', 'user_external_id': 'xxx'} réservera ces deux évènements, puis un second appel {'events': 'lundi', 'user_external_id': 'xxx'} ne gardera que la réservation du lundi en annulant celle du mardi (pour l'usager dont l'identifiant externe est xxx).

Pour récupérer les évènements réservés par un usager, il faut passer par un appel webservice à /datetimes/ comme pour l'affichage des créneaux de l'agenda, en passant le paramètre ?user_external_id=xxx. Tous les évènements sont renvoyés, mais les évènements réservés comportent une clé booked_for_external_user qui vaut main-list ou waiting-list. Ainsi il est possible de n'afficher que ces évènements, par exemple

{% for event in webservice.identifiant_du_webservice.data %}
{% if event.booked_for_external_user %}
événement : {{event.text}} 
date : {{event.datetime|date:"d/m/Y"}}
heure : {{event.datetime|time }}
{% endif %}
{% endfor %}

Méthode alternative (dépréciée)

Avant cette gestion exploitant le paramètre user_external_id, il était possible de passer par l'URL

{{agendas_url}}api/agenda/REUNIONS-D-INFORMATION/fillslots/

Néanmoins cette méthode ne permet pas la mise à jour des réservations d'un usager, ni l'annulation individuelle des réservations.

La réponse de cet appel webservice peut être exploitée pour afficher l'ensemble des réservations effectuées :

{% for  event in reservation_response_events %}
événement : {{event.text}} 
date : {{event.datetime|date:"d/m/Y"}}
heure : {{event.datetime|time }}
{% endfor %}

Gestion des erreurs

Lors d'une réservation une erreur peut être retournée, indiquant que l'événement est complet, ou que le créneau horaire a, entretemps, été occupé.  Pour gérer cela, dans le workflow de traitement, il faut utiliser le paramètre « Action en cas d'erreur applicative » pour placer la demande dans un statut particulier, pour prévenir l'usager de l'échec. (alternativement quand même, il est possible de gérer manuellement l'erreur, en créant un saut basé sur la condition reservation_app_error_code != 0).

Pour l'appel d'annulation, une erreur {'err': 1, 'reason': 'already cancelled'} sera retournée si la réservation a déjà été annulée.

Pour l'appel d'acceptation de réservation (de bascule hors de la liste d'attente), pour une réservation qui aurait été annulée le retour sera {'err': 1, 'reason': 'booking is cancelled'} et pour une réservation qui ne serait pas dans la liste d'attente, ce sera {'err': 2, 'reason': 'booking is not in waiting list'}.

Dernière mise à jour le 6 septembre 2021 09:54 — Éditer