Documentation en ligne

Enregistrement dans un agenda

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

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 nom de variable à l'appel webservice, par exemple « reservation », on aura désormais cet identifiant de réservation accessible dans {{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/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ésevation simple,  la donnée suivante  :

  • slots pour les identifiants des événements à réserver (usuellement {{form_var_event_raw|join:","}})

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 17 juin 2020 11:08 — Éditer