Guide technique de l'API Asterio

L'API Asterio est une interface REST-JSON permettant à toute application autorisée de lire et d'écrire les données d'un compte propriété : réservations, tarifs, restrictions, profils clients, canaux de distribution, rapports. Ce guide couvre les principes concrets qu'un intégrateur doit maîtriser pour bâtir une intégration robuste, sécurisée et respectueuse des limites de la plateforme.

Structure des endpoints

L'API Asterio suit une convention ressource-centric. Les endpoints sont groupés par domaine métier et versionnés dans le chemin. Les endpoints principaux sont :

• GET /v1/reservations — liste paginée des réservations, avec filtres par date d'arrivée, statut ou canal d'origine.
• GET /v1/reservations/{id} — détail complet d'une réservation, y compris paiements, notes internes et historique de modification.
• POST /v1/reservations — création d'une réservation directe (utile pour le portage depuis un autre PMS).
• PATCH /v1/reservations/{id} — mise à jour partielle d'une réservation existante.
• GET /v1/rate-plans — liste des plans tarifaires actifs, avec leurs restrictions et disponibilités.
• PUT /v1/rate-plans/{id}/availability — poussée de tarifs et de restrictions par plage de dates.
• GET /v1/guests/{id} et PATCH /v1/guests/{id} — lecture et mise à jour des profils clients.
• GET /v1/channels — liste en lecture seule des canaux connectés et de leur statut.
• POST /v1/webhooks — enregistrement d'un endpoint de notification pour les événements de réservation.

Authentification

Chaque requête doit inclure la clé API Asterio dans l'en-tête X-Api-Key. Exemple : X-Api-Key: sk_live_XXXXXXXXXXXXXXXX. Les clés doivent rester confidentielles ; en cas de compromission, révoquez-les immédiatement depuis Administration → Intégrations → Accès API et régénérez-en une nouvelle. Les scopes de permission doivent être limités au strict nécessaire pour chaque intégration.

Exemples cURL

Un GET de la liste des réservations d'arrivée du jour :

curl -X GET \\
  "https://api.asterio-booking.example/v1/reservations?arrival=2026-08-15" \\
  -H "X-Api-Key: sk_live_XXXXXXXXXXXXXXXX" \\
  -H "Accept: application/json"

Une poussée tarifaire sur une plage de dates :

curl -X PUT \\
  "https://api.asterio-booking.example/v1/rate-plans/BAR/availability" \\
  -H "X-Api-Key: sk_live_XXXXXXXXXXXXXXXX" \\
  -H "Content-Type: application/json" \\
  -d '{"start":"2026-09-01","end":"2026-09-07","rate":149.00,"currency":"EUR"}'

Un enregistrement de webhook sur l'événement de création de réservation :

curl -X POST \\
  "https://api.asterio-booking.example/v1/webhooks" \\
  -H "X-Api-Key: sk_live_XXXXXXXXXXXXXXXX" \\
  -H "Content-Type: application/json" \\
  -d '{"event":"reservation.created","url":"https://votre-app.example/webhooks/asterio","secret":"whsec_xxx"}'

Limites de débit

Asterio applique une limite de débit par clé API — typiquement 60 requêtes par minute et 5 000 par heure sur les plans standard. Un dépassement retourne un code HTTP 429 avec un en-tête Retry-After exprimant en secondes le délai avant nouvelle tentative. Implémentez un back-off exponentiel : 1 seconde après le premier 429, 2 secondes après le second, 4 secondes après le troisième, plafonné à 60 secondes. Regroupez systématiquement les mises à jour tarifaires par plage de dates plutôt que d'itérer nuit par nuit.

Gestion des erreurs

Débogage pratique

Les intégrations qui produisent des erreurs intermittentes gagnent à instrumenter en profondeur les appels API. Loguez systématiquement l'URL, la méthode, le code de statut et le corps de la réponse. Attribuez un identifiant de corrélation unique à chaque enchaînement d'appels, afin de pouvoir reconstruire une chronologie complète lors d'un incident. Enfin, activez un mode « dry-run » sur toutes les opérations d'écriture pendant la phase d'intégration : le module simule l'appel, journalise le payload, mais ne le transmet pas à Asterio. Ce filet de sécurité évite la majorité des incidents de mise en production.

Environnement de test

Asterio propose un environnement sandbox sur certains niveaux de plan. Contactez votre gestionnaire de compte Asterio pour y accéder. Chaque module publié par Asteriomod est validé contre le sandbox avant chaque publication et à chaque notification de mise à jour de l'API. Ce cycle de validation garantit qu'aucune régression n'est expédiée à un client en production.