Interrogation d'un calendrier gAppointment via API

Pour son calendrier de réservation, notre site web utilise le module gAppointments (sous wordpress).

L’objectif est de mettre à disposition les données de ce calendrier à un site tiers qui viendra l’interroger selon les spécifications complètes fournies par l'entité tier.

L’objectif de la demande n’est pas forcément de formater chacun des endpoints sur la structure exacte demandée, mais a minima de fournir le code source permettant d’interroger le module gAppointments, la structure de la requête et de restituer des informations brutes. Le formatage de la réponse tel qu'attendu dans les spécifications pourra être fait a posteriori par nos soins.
Dans cette optique, la priorité est donnée à au moins une des 3 API + le deep-linking.

Introduction
L'affichage des disponibilités sur xxx permet aux joueurs de voir en un coup d'oeil les prochains créneaux encore disponibles à la réservation et d'en ajouter un à son panier sur le site de l'enseigne.
Pour fonctionner l'enseigne doit fournir 3 endpoints d'API pour récupérer les créneaux disponibles à la vente et un système de deep-linking pour amener les utilisateurs vers leur panier.
API
Il y a 3 endpoints d'API nécessaires au fonctionnement du site : un pour une date en particulier, un pour une semaine, et un pour le prochain créneau disponible.
L'API renvoie des données formatées en json.
Il est important de noter que, pour être à jour en temps réel, ces données sont appelées directement coté client. L'enseigne doit donc s'assurer du bon fonctionnement de son server en cas de montée en charge.
baseUrl
Chaque enseigne partenaire doit fournir une URL de base qui sera ensuite utilisée pour tous les appels API.
Il s'agit généralement d'un nom de domaine et d'un dossier :
[URL visible pour les membres Pro]
[URL visible pour les membres Pro]
[URL visible pour les membres Pro]
Il peut également s'agir d'un sous domaine :
[URL visible pour les membres Pro]
[URL visible pour les membres Pro]
Attention ! Il faut obligatoirement que les endpoints soient accessibles en https.
Tous les endpoints doivent avoir un entête Access-Control-Allow-Origin: [URL visible pour les membres Pro]
gameID
Afin de cibler le bon jeu dans les requêtes, l'enseigne doit également fournir un identifiant de jeu. Cet identifiant est généralement un numéro (exemple : 3) mais il est possible de définir une chaine de caractère (exemple : nom-de-mon-scenario)
Nuance jeu/salle : Dans le cas où un jeu est doublé, les deux salles enfants sont regroupées sous le même gameID.
Endpoints
Par jour
Ce endpoint est utilisé sur notre calendrier global où la navigation fonctionne de jour en jour.
Structure de l'URL :
[baseUrl]/day/[gameID]/[date au format yyyy-mm-dd]
Exemple
Requête :
[URL visible pour les membres Pro]
Réponse :
{
"date-selected":"[Téléphone visible pour les membres Pro]",
"mode":"day",
"rooms":{
"1":[
{
"id": 19453,
"time": "10h",
"available": true,
"book-url": "https:\/\/exemple.com\/cart\/?booking=19453"
},
{"id": 19454, "time": "11h20", "available": true, "book-url": "https:\/\/exemple.com\/cart\/?booking=19454"},
{"id": 19455, "time": "12h40", "available": false, "book-url": "https:\/\/exemple.com\/cart\/?booking=19455"},
...
],
"2":[
{
"id": 19463,
"time": "10h",
"available": true,
"book-url": "https:\/\/exemple.com\/cart\/?booking=19463"
},
{"id": 19464, "time": "11h20", "available": true, "book-url": "https:\/\/exemple.com\/cart\/?booking=19464"},
...
],
...
}
}

L'exemple ci-dessus présente un jeu doublé, si votre jeu n'est pas doublé vous n'aurez alors qu'un élément dans rooms.
L'heure du créneau est au format « 00h » ou « 00h00 » si les créneaux ne sont pas à l'heure pile.
L'API renvoie tous les créneaux disponibles et indisponible, il faut donc préciser l'attribut "available": true ou false dans la réponse.
book-url correspond au deep-link que l'utilisateur va emprunter. (Détails dans le paragraphe dédié plus bas)
date-selected, mode, et les id des créneaux sont optionnels mais peuvent nous servir à débuguer.
Par semaine
Ce endpoint est utilisé sur les fiches des jeux pour afficher les prochaines disponibilités sur plusieurs jours.
Structure de l'URL :
[baseUrl]/week/[gameID]/[date au format yyyy-mm-dd]
Exemple
Requête :
[URL visible pour les membres Pro]
Réponse :
{
"monday":"[Téléphone visible pour les membres Pro]",
"mode":"week",
"days":{
"1":{
"date":"[Téléphone visible pour les membres Pro]",
"rooms":{
"1":[
{
"id":56346,
"time":"10h",
"available":false,
"book-url":"https:\/\/exemple.com\/cart\/?booking=56346"
},
{"id":56347,"time":"12h","available":false,"book-url":"https:\/\/exemple.com\/cart\/?booking=56347"},
{"id":56348,"time":"14h","available":false,"book-url":"https:\/\/exemple.com\/cart\/?booking=56348"},
...
]
}
},
"2":{
"date":"[Téléphone visible pour les membres Pro]",
"rooms":{
"1":[...]
}
},
...
"7":{
"date":"[Téléphone visible pour les membres Pro]",
"rooms":{
"1":[...]
}
}
}
}

Le endpoint renvoie toujours une semaine complète à partir du lundi et non 7 jours glissants !
Il est possible de passer n'importe quelle date dans l'appel et pas forcément un lundi. Si par exemple la date de l'appel est un mercredi, l'API renvoie une semaine complète à partir du lundi précédent la date.
Les dates sont toujours au format yyyy-mm-dd.
La structure des créneaux reprend les mêmes caractéristiques définies dans l'endpoint /day.
Prochain créneau
Ce endpoint est utilisé sur les cartes des jeux pour afficher uniquement le prochain créneau disponible.
Structure de l'URL :
[baseUrl]/upcoming/[gameID]
Exemple
Requête :
[URL visible pour les membres Pro]
Réponse :
{
"id":32753,
"date":"[Téléphone visible pour les membres Pro]",
"time":"16h",
"book-url":"https:\/\/exemple.com\/cart\/?booking=32753"
}

La structure des créneaux reprend les mêmes caractéristiques définies dans l'endpoint /day avec la date en plus au format yyyy-mm-dd et sans l'attribut available.
Deep-linking
Lorsque le joueur clique sur un créneau un écran lui demande de confirmer son choix (ce qu'on appelle le booking-attempt). Une fois qu'il confirme et clique sur « Réserver » il est alors redirigé vers le site de l'enseigne. C'est à ce moment-là qu'il emprunte un lien profond (deep-link) lui permettant d'arriver directement dans son panier avec le créneau qu'il a précédement sélectionné sur xxx.fr.
Ce lien peut être complètement différent de la baseURL. Il s'agit généralement du véritable lien du panier incluant l'ID du créneau en paramètre.
Exemple :
[URL visible pour les membres Pro]
[URL visible pour les membres Pro]