Utiliser l'API Asterio pour intégrer des modules tiers

L'API Asterio permet à toute application tierce dûment autorisée de lire et d'écrire les données de réservation, les plans tarifaires, les profils clients et la configuration des canaux de distribution d'un compte Asterio. Cet article présente les grands principes de connectivité de l'API Asterio et la manière dont les modules d'Asteriomod établissent, sécurisent et maintiennent cette connexion au quotidien.

Introduction à l'API Asterio

L'API Asterio est une interface REST-JSON. Toutes les requêtes se font via HTTPS et les réponses sont renvoyées au format JSON avec un encodage UTF-8. L'API est structurée autour d'objets métier : réservations, chambres, plans tarifaires, canaux, profils clients, factures et rapports. Chaque objet dispose de ses propres endpoints (GET pour la lecture, POST pour la création, PATCH pour la mise à jour partielle et DELETE lorsque cette opération est autorisée par le plan de licence).

La convention de nommage suit un style ressource-centric : par exemple /v1/reservations, /v1/rate-plans, /v1/guests/{id}. Les identifiants renvoyés par Asterio sont des chaînes alphanumériques stables : ils peuvent être stockés sans risque dans une base tierce, et servent de clé de rapprochement pour les modules d'Asteriomod lorsqu'ils synchronisent l'état d'une réservation entre plusieurs systèmes.

Authentification et clés API

L'API Asterio repose sur une authentification par clé API. Chaque compte propriété peut générer une ou plusieurs clés depuis la section Administration → Intégrations → Accès API. La clé prend la forme d'une longue chaîne alphanumérique transmise à chaque appel dans l'en-tête X-Api-Key. À réception, Asterio résout la clé pour identifier à la fois l'application appelante et le périmètre du compte auquel elle donne accès.

Les clés Asterio se déclinent en scopes de permissions. Les scopes les plus courants sont : lecture des réservations, écriture des réservations, lecture des tarifs, écriture des tarifs, lecture des profils clients, écriture des profils clients, lecture de la configuration des canaux et lecture des données de reporting. Les modules tiers doivent demander uniquement le minimum requis : ce principe du moindre privilège limite fortement l'exposition en cas de compromission de la clé.

Une clé API doit être considérée comme un secret équivalent à un mot de passe. Elle donne un accès complet, dans son scope, à l'ensemble du compte propriété auquel elle est rattachée. Toutes les clés doivent être stockées chiffrées, transmises exclusivement en HTTPS et renouvelées à intervalles réguliers. Lorsque vous connectez un module via Asteriomod, la clé est conservée chiffrée en AES-256 dans notre coffre-fort logiciel : elle n'est jamais consultable en clair, y compris par nos équipes support.

Récupérer des réservations

L'API Asterio propose plusieurs endpoints pour interroger les réservations sur une plage de dates. Une réponse typique inclut l'identifiant, le nom du voyageur, les dates d'arrivée et de départ, le type de chambre, le plan tarifaire, le montant total, le statut de paiement, le canal d'origine et les coordonnées client. Ces informations forment la base de la plupart des intégrations tierces destinées à la relation client, à la comptabilité ou à la distribution.

Pour un module comme Module Facture Client PDF, le flux type est le suivant : (1) interroger Asterio pour la liste des réservations arrivées et facturables sur les 7 derniers jours ; (2) récupérer le profil client associé à chaque réservation ; (3) générer le PDF de facture au format légal attendu ; (4) réécrire l'URL du document dans la fiche réservation Asterio pour que le personnel de réception puisse le retrouver. Les étapes 1 et 2 sont des opérations de lecture, l'étape 4 requiert le scope d'écriture sur les réservations.

Écrire dans Asterio

L'API supporte l'écriture sur les tarifs, les restrictions, les profils clients et certaines métadonnées de réservation. Un appel type de mise à jour tarifaire précise l'identifiant du plan, les dates concernées, les types de chambres visés et la nouvelle valeur. Les mises à jour poussées par API sont ensuite propagées au channel manager Asterio et redistribuées aux OTA connectées selon le cycle normal de mise à jour des canaux.

L'Extension API Rate Distribution exploite ce mécanisme : elle lit l'occupation en temps réel, calcule la recommandation tarifaire d'après vos règles métier, puis pousse la nouvelle valeur dans Asterio via l'API. La cohérence est garantie par un mécanisme d'idempotence côté module — chaque poussée porte un identifiant unique qui empêche la duplication en cas de rejeu.

Gestion des webhooks

En complément des appels API classiques, Asterio propose la livraison de webhooks pour certains événements de cycle de vie : création de réservation, modification, annulation, arrivée, départ, encaissement. Un webhook est un simple POST HTTP envoyé par Asterio vers une URL de votre choix, avec un payload JSON décrivant l'événement. Configurez vos abonnements depuis Administration → Intégrations → Webhooks.

L'Extension Notification Slack Réservations exploite ce mécanisme d'événement : dès qu'Asterio émet un webhook « réservation créée », l'extension déclenche l'envoi d'un message dans le canal Slack configuré, sans devoir sonder Asterio en boucle. Cette architecture évènementielle réduit fortement le volume d'appels API et améliore le temps de réaction sur les communications sensibles.

Limites de débit

Asterio applique une limitation de débit sur chaque clé API afin de préserver la stabilité de la plateforme. Un dépassement retourne un code HTTP 429. Les modules tiers bien conçus mettent en place un back-off exponentiel : 1 seconde après la première erreur, 2 secondes après la deuxième, 4 secondes après la troisième, etc., jusqu'à un plafond de 60 secondes. Les appels doivent être regroupés (batching) chaque fois que possible, plutôt que d'itérer chambre par chambre ou nuit par nuit.

Tous les modules d'Asteriomod sont conçus pour respecter ces limites. Les mises à jour tarifaires sont regroupées par plage de dates. Les intervalles de polling sont paramétrés de manière conservative. Lorsque plusieurs modules du même compte Asterio sont actifs simultanément, leurs appels sont orchestrés par un coordinateur central afin de ne jamais surcharger l'API.

Conclusion

L'API Asterio couvre l'essentiel des besoins d'intégration modernes d'un exploitant hôtelier. Elle offre les briques nécessaires pour connecter des modules de revenue management, d'automatisation, de reporting ou de distribution, tout en préservant la maîtrise complète du compte propriétaire. Les principes présentés dans cet article — moindre privilège, chiffrement au repos, back-off exponentiel, événements plutôt que polling — définissent la charte que suit chaque module publié par Asteriomod.