Documentation en ligne

Paramétrage avancé des workflows pour les agendas

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

Annulation depuis l'agenda

L'annulation d'une réservation peut se faire via le workflow, c'est la méthode classique, mais il est également possible d'annuler une réservation depuis la vue back-office des agendas (lien « Annuler » à droite des réservations dans la vue back-office d'un agenda). Le clic sur le lien « Annuler » n'est effectif que si l'on a configuré le nécessaire dans le workflow, pour renseigner le paramètre cancel_callback_url dans l'acttion webservice d'enregistrement.

La méthode recommandée pour cela est :
  1. ajouter une action globale (ex. « Annulation depuis l'agenda »), avec un déclencheur de type « Appel externe ».
    Vous pouvez également ajouter un saut automatique vers le statut dans lequel se trouve les messages qui informent l'usager de l'annulation du RDV.
  2. dans le webservice de réservation du créneau, vérifier que l'URL à passer dans le paramètre cancel_callback_url est {{form_api_url}}hooks/IDENTIFIANT-APPEL-EXTERNE/ 
Attention, si on annule un RDV depuis l'agenda sans renseigner cancel_callback_url, il sera supprimé de la vue calendaire mais il ne sera pas annulé au niveau de la demande, il faut donc toujours renseigner ce paramètre.

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

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

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

Une action de saut automatique avec une condition reservation_response_in_waiting_list == true permettra de passer vers un statut approprié pour les personnes en attente

Dans ce statut d'attente, pour accepter la réservation et la sortir de la file d'attente, il faut configurer une action webservice en 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 sur un même événement (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/IDENTIFIANT-AGENDA/fillslot/{{form_var_event_raw}}/?count={{form_var_nb_places}}

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

Il est possible de réaliser une réservation sur plusieurs événements plutôt qu'un seul.

Le champ « event » que l'on va alors utiliser dans le formulaire sera de type liste à choix multiple pour permettre la sélection de plusieurs événements. Ensuite dans le workflow, l'action d'appel webservice qui pose la réservation doit utiliser l'URL suivante (noter le « s » final à fillslots) :

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

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

  • slots pour les identifiants des événements à réserver (usuellement {{form_var_event_raw}})
  • 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 la réponse apportée lors d'une 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

Si une nouvelle réservation multiple est effectuée pour le même usager, elle annule et remplace la précédente : si une première réservation a permis de sélectionner un événement le lundi et un autre le mardi, une seconde réservation ne retenant que l'événement du mardi, annulera l'inscription du lundi.

Pour récupérer les évènements réservés par un usager, il faut passer par un appel webservice GET à  /api/agenda/SLUG-DE-LAGENDA/datetimes/, en passant le paramètre ?user_external_id=xxx. Tous les évènements sont renvoyés.

Les évènements réservés comportent une clé booked_for_external_user qui vaut main-list pour les événements pour lesquels l'usager est réellement inscrit, ou waiting-list pour les événements pour lesquels l'usager est sur liste d'attente.

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

Par exemple : {'err': 1, 'reason': 'sold out'}

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 30 mai 2022 14:15 — Éditer