Retrouvez tous les éléments concernant le Temps Réel dans les projets Apidae.
Pour les projets exploitant les API, Apidae a mis en place un nouveau fonctionnement « Temps Réel » permettant :
- D’être alerté tout de suite de la modification d’un objet touristique faisant partie des sélections du projet,
- De mieux solliciter nos APIs pour des appels pertinents.
Fonctionnement
Modification d’une fiche
Le Temps Réel a besoin d’un webhook sur lequel il pourra notifier de la modification d’une fiche ou d’une modification d’une sélection. Le process est simple :
- Une fiche est modifiée par le propriétaire de la donnée dans le SIT,
- Un calcul a lieu pour identifier les projets concernés par cette fiche,
- Une notification est envoyée sur le webhook renseigné dans le projet, avec l’ID de la fiche concernée par la modification ainsi que le type de message (modification / ajout / suppression),
- Le système notifié doit alors faire un appel API pour récupérer la fiche modifiée. (Un appel /v002/objet-touristique/get-by-id/{ID de l’objet} répond parfaitement à ce besoin, voir la documentation sur les différents services proposés).
NB : dans le cas d’une suppression de fiche ou de sélection, il n’est pas nécessaire d’appeler la fiche en question.
Modification des sélections du projet ou de leur périmètre :
Dans le cas d’une modification des sélections du projet (ajout ou suppression de sélection), le fonctionnement est quasi identique :
- La modification se fait via l’interface de gestion de projet SIT,
- Pour une suppression, un message est immédiatement envoyé au webhook du projet concerné. Pour un ajout de sélection, au moment du recalcul nocturne, un message est envoyé au webhook du projet concerné. Dans les deux cas, sont communiqués l’ID de la sélection, le type de modification ainsi que celui du projet. (voir le détail des messages)
- Le système notifié peut alors soit supprimer l’ID de la sélection qui a été supprimée, soit faire un appel à /v002/recherche/list-identifiants en passant en paramètre l’ID de la nouvelle sélection. Cela permet ainsi de récupérer les identifiants des offres contenues dans cette sélection.
Pour l’ajout ou le retrait de fiches d’une sélection déjà présente dans le projet, le principe est le même :
- Les sélections sont recalculées chaque nuit,
- Si des ajouts/retraits de fiches sont détectés, un message est envoyé au webhook dès la fin des recalculs. Il contient alors l’ensemble des IDs des fiches ajoutées/retirées pour chaque sélection, ainsi que le type d’opération.
NB : Pour les gros ajouts/retraits de fiches, une limite de 200 IDs par notification au webhook a été mise en place afin de garder des messages de taille raisonnable.
Si 750 fiches sont ajoutées à une sélection, 3 messages de 200 IDs + 1 message de 150 IDs seront alors envoyés sur le webhook. - Le système notifié peut alors, via un appel /v002/objet-touristique/get-by-id/{ID de l’objet}, récupérer les nouvelles fiches, ou bien retirer les IDs de son référentiel.
Paramétrage
Lors du paramétrage d’un projet en API, il est désormais possible d’activer le temps réel dans « configuration technique » :
Cocher la case « Temps réel » permet d’afficher le champ « Webhook ». Dans ce champ, indiquer l’URL à notifier.
Format de message envoyé
Les notifications envoyées sur le webhook ont le format suivant :
hook {"query":[],"request":[],"content":"{\"referenceIds\":[6411425],\"operation\":\"UPDATE_OBJET_TOURISTIQUE\",\"projectId\":7210,\"timestamp\":1696508522964}","headers":{"connection":["close"],"x-forwarded-proto":["https"],"via":["2.0 alproxy"],"content-length":["108"],"user-agent":["Java-http-client/17.0.2"],"content-type":["application/json"],"host":["console.apidae-tourisme.dev"],"authorization":["Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6ICJKV1QifQ.eyJyZWZlcmVuY2VJZHMiOls2NDExNDI1XSwib3BlcmF0aW9uIjoiVVBEQVRFX09CSkVUX1RPVVJJU1RJUVVFIiwicHJvamVjdElkIjo3MjEwLCJ0aW1lc3RhbXAiOjE2OTY1MDg1MjI5NjR9.kqiyze4N6ufPQt8OMrPp9uDnZBig3VuiKp56_OWpvibNaxD6Ep65BuTgDMwzNZizxZACeTRbyrb83ykzlPP9qDoG2QgXLrNfVfXjs4qldccVWmH0eKl7ptFUIRsxZ9UMbgG_0C8L1z1GTzkQNbVxArK0Kv4MlpjTRiKljCCaClEtZRydaE1hcvQT8ETKx8jf38wkutWqOLr9HjGQ69jrB2jwcW64PA1SxqNXg8rWnwQsbLih64TxvhRVqg6XUaoYFsPFxpVOhrP5hrT2PN7Zg00FGpH2xm8ouZNmJaHtUjD7U8x_aVlWvF337uLKN2Pt2eMKU4zmZ50LJJ_Agis1iw"],"x-php-ob-level":["1"]},"method":"POST"} []
Le bloc « content » contient toutes les informations importantes.
Le temps réel notifie donc le webhook renseigné dans les cas suivants :
- Modification d’une fiche étant dans le périmètre du projet, format de « content » dans le message envoyé :
{\"referenceIds\":[ID DE LA FICHE],\"operation\":\"UPDATE_OBJET_TOURISTIQUE\",\"projectId\":PROJETID,\"timestamp\":1694762386983} - Suppression d’une fiche étant dans le périmètre d’une sélection du projet :
{\"referenceIds\":[ID DE LA FICHE],\"operation\":\"DELETE_OBJET_TOURISTIQUE\",\"projectId\":PROJETID,\"timestamp\":1696508356740} - Ajout d’une ou plusieurs fiches au périmètre d’une sélection du projet :
{\"referenceIds\":[1234],\"operation\":\"ADD_REFERENCE_SELECTION\",\"projectId\":PROJETID,\"selectionId\":SELECTIONID,\"timestamp\":1696508327396}
(NB : la notification est renvoyée au moment du recalcul quotidien des sélections) - Suppression d’une ou plusieurs fiches du périmètre du projet :
{\"referenceIds\":[123, 1234, 12345],\"operation\":\"REMOVE_REFERENCE_SELECTION\",\"projectId\":PROJETID,\"selectionId\":SELECTIONID,\"timestamp\":1696508327396}
(NB : la notification est envoyée au moment du recalcul quotidien des sélections) - Ajout d’une sélection au périmètre du projet :
{\"operation\":\"ADD_SELECTION_PROJECT\",\"projectId\":PROJETID,\"selectionId\":SELECTIONID,\"timestamp\":1696508087481}
(NB : la notification est envoyée au moment du recalcul quotidien des sélections) - Suppression d’une sélection au périmètre du projet :
{\"operation\":\"DELETE_SELECTION_PROJECT\",\"projectId\":PROJETID,\"selectionId\":SELECTIONID,\"timestamp\":1696508087481}
(NB : la notification est envoyée immédiatement après la suppression)
Signature des appels
Chaque appel est signé par un JWT qui peut être décodé. Cette signature est vérifiable à partir de la clé publique : https://static.apidae-tourisme.com/filestore/temps-reel/certificates/public.pem.
Exemple à partir du payload ci-dessus sur jtw.io :
F.A.Q
Une mise à jour de métadonnée déclenche-t-elle un appel au temps réel ?
Oui : une métadonnée modifiée entraînera donc un export de l’offre lors des prochains calculs de sélections qui la contiennent, et un appel au temps réel.
Dans certains cas, il n’y aura aucune modification sur l’offre, si la métadonnée n’était pas générale par exemple (et donc pas visible sur tous les projets) : dans les faits, depuis la mise en place des métadonnées, toutes sont systématiquement générales (au 06/02/2024).