API ouverte Guesty : Démarrage rapide et résolution de problèmes

Ce guide s'adresse aux développeurs qui intègrent l'API ouverte de Guesty pour la première fois. Référence complète : open-api-docs.guesty.com

Démarrage rapide

1. Obtenez vos informations d'authentification

Commencez par vérifier que votre compte Guesty dispose d'un accès à l'API ouverte. Vous aurez besoin de vos informations d'authentification OAuth : client_id et client_secret. Pour des instructions détaillées, consultez la section « Démarrer ».

2. Authentification

Échangez vos informations d'authentification contre un jeton d'authentification : POST https://open-api.guesty.com/oauth2/token avec les paramètres suivants : grant_type=client_credentials, scope=open-api, client_id et client_secret. Ce jeton est valable 24 heures.

Conservez votre jeton en lieu sûr et surveillez sa date d'expiration. Chaque client_id peut demander un nouveau jeton jusqu'à cinq fois en 24 heures. Si cette limite est atteinte, vous ne pourrez plus obtenir de jeton avant la réinitialisation du cycle. Pour éviter tout problème, prévoyez de renouveler votre jeton quelques minutes avant son expiration. Pour des exemples de code en Node.js, Python et PHP, consultez la documentation sur la Gestion des jetons d'accès. Pour plus d'informations, consultez la section Authentification.

3. Passez votre premier appel

Envoyez le jeton en tant qu'en-tête porteur sur chaque requête :

GET https://open-api.guesty.com/v1/listings
Authorization: Bearer {access_token}

4. Gérer la pagination

La plupart des points de terminaison utilisent les paramètres de requête limit et skip pour la pagination et renvoient items, count, limit et skip dans la réponse. Certains points de terminaison peuvent utiliser offset ou cursor, ou renvoyer un format de réponse différent. Si les paramètres standard ne fonctionnent pas, consultez la page de référence du point de terminaison concerné. Par exemple :

offset au lieu de skip : GET /properties-api/groups/group
Requête basée sur cursor : GET /communication/conversations, GET /communication/conversations/{conversationId}/posts
results + un objet pagination imbriqué : GET /reservations-v3/search (le même point de terminaison de recherche de Réservations v3 utilisé ailleurs dans ce guide)
results / count au lieu d' items / count : GET /vendors, GET /users, GET /property-logs/{id}

Résolution de problèmes et FAQ

Avant de relancer une requête, vérifiez le code d'état. Seules les erreurs 429 et 5xx doivent faire l'objet d'une nouvelle tentative automatique. Les autres codes d'état indiquent que la requête doit être modifiée avant d'être relancée.

Par code de réponse

401 / 403 — "Non autorisé" juste après l'authentification : Votre jeton a expiré (il est valable 24 heures) ou n'a pas été envoyé correctement. Remarque : l'API de Guesty renvoie une 403 même lorsque le message indique "Non autorisé" ; ce comportement est normal et ne provient pas de votre côté. Solution : Réauthentifiez-vous et mettez à jour le cache du jeton ; vérifiez que l'en-tête est exactement : Authorization: Bearer <token> . Le point de terminaison du jeton expose également les en-têtes x-ratelimit-remaining-day / x-ratelimit-limit-day si vous souhaitez consulter directement votre budget de jetons quotidien. Plus d'informations : Authentification .

404 — Ressource introuvable, mais l'ID semble correct : Généralement, l'ID appartient à un compte/une portée différente de celle de votre jeton, l'enregistrement n'a pas encore été synchronisé ou provient d'un canal dont la visibilité de l'API est limitée. Vérifiez l'ID sur le tableau de bord du compte auquel vos informations d'authentification sont associées. Par exemple, GET /reservations-v3/group/{groupId} renvoie une erreur 404 aussi bien pour un ID apparemment valide associé à un compte incorrect que pour un ID inexistant. Plus d'informations : Codes de réponse .

410 — Devis expiré : Les devis ont une durée de validité limitée. Une fois expiré, un devis ne peut plus être modifié ni réservé. Veuillez en créer un nouveau plutôt que de réessayer avec l’ancien identifiant.

400 / 422 — Erreur de validation : Vérifiez le corps de la requête par rapport au schéma de ce point de terminaison sur sa page de référence. Les réponses d'erreur de Guesty ne sont pas uniformes sur l'ensemble de l'API : certaines contiennent des champs imbriqués dans l'erreur, d'autres non, et les noms de champs varient. Par conséquent, ne présumez pas qu'un nom de champ d'erreur d'un point de terminaison s'applique à un autre. Par exemple, POST /reservations-v3 (réservation rapide) renvoie à la fois 400 et 422 selon que la requête elle-même est mal formée ou qu'elle enfreint une règle de réservation (par exemple, dates indisponibles). Vérifiez le code d'erreur obtenu avant de tenter de résoudre le problème.

429 - Limitation de débit : Vous avez atteint la limite globale de 15 requêtes par seconde, 120 par minute ou 5 000 par heure, partagée entre tous les jetons. Veuillez patienter jusqu'à l'expiration du délai indiqué dans l'en-tête Retry-After avant d'envoyer une nouvelle requête. Surveillez les en-têtes X-RateLimit-Remaining-Second , X-RateLimit-Remaining-Minute et X-RateLimit-Remaining-Hour pour suivre votre consommation. Vous pouvez également consulter les en-têtes ratelimit-limit , ratelimit-remaining et ratelimit-reset, qui reflètent la limite par seconde. Avant de demander une limite supérieure, envisagez le traitement par lots, la mise en cache, le filtrage ou l'utilisation de webhooks pour optimiser votre intégration. Si vous constatez une diminution de la limite après un dépassement prolongé, cela peut indiquer qu'une augmentation précédente a été annulée. Pour plus d'informations, consultez la section Limites de débit .

"Impossible de créer une autre application OAuth / un autre ID client" : Il s'agit d'une limite distincte (cinq applications OAuth par compte) et différente de la limite de requêtes mentionnée ci-dessus. Si vous avez besoin de plus d'applications, veuillez contacter l'assistance en précisant votre cas d'utilisation.

5xx — Erreur serveur : effectuez une nouvelle tentative avec un délai exponentiel et une gestion des erreurs plutôt que de boucler immédiatement. La plupart des erreurs 5xx sont temporaires ; si un point de terminaison échoue de manière répétée, veuillez inclure l'en-tête de réponse x-request-id lorsque vous contactez l'assistance. Exception : pour une requête modifiant un paiement ou une réservation, vérifiez d'abord le statut de la requête ; ne réessayez pas inutilement, au risque de facturer deux fois le voyageur. Plus d'informations : Gestion des requêtes ayant échoué .

Par symptôme

Si une réservation ou une annonce n'apparaît pas dans vos résultats de recherche, vérifiez d'abord vos paramètres de filtre et de portée. C'est la cause la plus fréquente. Pour les enregistrements récents, patientez le temps de la synchronisation, notamment pour les réservations provenant de plateformes comme Airbnb, Vrbo ou Booking.com. C'est précisément le rôle de GET /reservations-v3/search : assurez-vous de l'utiliser (avec les bons paramètres filter[...]) plutôt qu'une requête plus ancienne ou moins ciblée. Si l'enregistrement est toujours introuvable, contactez l'assistance en indiquant l'identifiant précis et la requête exacte utilisée.

Si votre webhook ne se déclenche pas ou si vous ne parvenez pas à vous y abonner, vérifiez les points suivants : (1) Assurez-vous d'être abonné au nom d'événement v2 correct, car les webhooks classiques et v2 ne sont pas interchangeables. (2) Assurez-vous que votre point de terminaison renvoie une réponse 2xx, car Guesty cessera les tentatives de connexion dans le cas contraire. (3) Sur les comptes de test ou de bac à sable, vérifiez que l'abonnement a bien été créé. La diffusion peut être retardée en période de forte charge. L'événement listing.calendar.updated se déclenche uniquement lors de modifications directes du calendrier, du tarif ou de la durée minimale de séjour, et non pour les réservations nouvelles ou modifiées. Pour vérifier l'authenticité d'un webhook, récupérez le secret de signature de votre point de terminaison à l'aide de la requête GET /webhooks-v2/secret. Pour plus d'informations, consultez la Vue d'ensemble des webhooks.

Si vous avez mis à jour le titre ou la description d'une annonce via l'API et que la modification n'apparaît pas sur Airbnb, vérifiez si le champ a été modifié directement sur Airbnb. Si c'est le cas, Airbnb verrouille le champ et les mises à jour de l'API ne seront pas synchronisées tant que vous ne l'aurez pas déverrouillé sur Airbnb. Les mises à jour effectuées via les requêtes PUT /marketing/description-sets/{id} ou POST /marketing/description-sets ne seront pas synchronisées avec Airbnb tant que le champ n'est pas déverrouillé. D'autres plateformes comme Booking.com et Vrbo peuvent avoir des exigences similaires. Pour plus d'informations, consultez la section « Champs Marketing et traductions ».

GuestyPay renvoie l'erreur 402 ERR_BAD_REQUEST : si la réponse contient « La requête contredit la configuration de l'interface de nettoyage » ou « Corbeille incorrecte ou déconnexion de l'Hôte », le compte GuestyPay lui-même présente un problème de configuration ou est hors ligne. Vous ne pouvez pas résoudre ce problème via votre intégration. Veuillez contacter l'Expérience Client .

Le format de l'erreur ne correspond pas à celui observé sur un autre point de terminaison : c'est normal, car il n'existe pas de format error unique pour l'ensemble de l'API. Un modèle est cependant le plus fréquent : un message imbriqué sous une seule clé d'erreur, par exemple : GET /accounting-api/reservations/{id}/balance → {"error": {"message": "...", "status": 404}} . Ce n'est toutefois pas systématique : certains points de terminaison affichent un message sous forme de tableau de chaînes de caractères ( GET /guest-folio/invoice-items → {"statusCode": 400, "message": [...]} ), tandis que d'autres incluent leur propre champ requestId au niveau du corps de la requête, distinct de l'en-tête de réponse x-request-id ( GET /availability-pricing/api/calendar/listings/{id} ). Un bon nombre de points de terminaison ne documentent pas du tout le format du corps de l'erreur, mais uniquement une description textuelle. Veuillez consulter le schéma d'erreur documenté du point de terminaison spécifique plutôt que de coder en dur une structure fixe.

Ai-je besoin d'un compte de test ou d'un compte de test (sandbox) ? Voici une règle simple : utilisez un compte de test pour la quasi-totalité des phases initiales d'intégration et de développement, sauf si vous testez spécifiquement les flux liés à Stripe, auquel cas un environnement de test est nécessaire. N'utilisez l'environnement de production que lorsque vous êtes prêt à déployer des données réelles. Les comptes de test sont la norme pour les nouvelles demandes d'intégration et fonctionnent comme votre environnement de production, à l'exception des données de test. Les environnements de test (sandbox) sont des environnements distincts (vérifiez la présence de « sandbox » dans l'URL) utilisés pour les tests d'intégration Stripe, car Guesty n'accepte pas les clés de test Stripe, ni en production ni dans les comptes de test classiques. GuestyPay ne dispose d'aucun environnement de test : il fonctionne uniquement en production. Vous devez donc utiliser une carte réelle pour les tests GuestyPay, quel que soit le type de compte utilisé.

Un compte de test est une option payante et est distinct de votre environnement de production. Les données ne sont pas transférées depuis la production ; vous devrez donc configurer les annonces, les réservations et d'autres informations de A à Z. Pour obtenir un compte de test, contactez votre gestionnaire de compte.

Serveur MCP (Bêta)

Le serveur Guesty MCP permet aux assistants IA compatibles MCP (actuellement Cursor, Claude Desktop, VS Code (Copilot) et Google Antigravity) de lire les données Guesty via une interface contrôlée. En version bêta, l'accès est en lecture seule : les assistants peuvent consulter et synthétiser les données, mais ne peuvent ni créer, ni modifier, ni supprimer d'enregistrements. La compatibilité avec d'autres outils est susceptible d'évoluer avant la disponibilité générale.

Connexion

Actuellement, vous pouvez vous connecter en local ou via un serveur hébergé. Un déploiement entièrement géré avec des informations d'authentification préconfigurées n'est pas encore disponible.

En local (sortie standard, recommandée) : exécutez la commande npx -y @guestyorg/sdk mcp . Vous pouvez utiliser la variable d'environnement BEARER_TOKEN pour un jeton d'accès statique, ou les variables d'environnement CLIENT_ID et CLIENT_SECRET . Le serveur MCP se chargera d'échanger ces informations d'authentification ; aucune étape manuelle n'est donc requise.
Hébergé (HTTP, https://mcp.guesty.com/v1 ) : Authentifiez-vous à l'aide d'un en-tête Authorization au début de la session, ou utilisez l'outil set_token après la connexion.

Résolution de problèmes

Erreur 401 à chaque appel d'outil : cela indique qu'aucun jeton n'a été défini. Pour les connexions hébergées ou HTTP, assurez-vous de définir le jeton à l'aide de set_token ou de l'en-tête Authorization avant d'utiliser tout autre outil.

403 : Comportement incohérent : Cette erreur peut survenir avec des jetons expirés ou lorsque les clients OAuth disposent d'autorisations pour l'accès standard à l'API ouverte, mais pas pour MCP. Commencez par vous réauthentifier avec un nouveau jeton. Si le problème persiste, vérifiez que le client OAuth dispose bien des autorisations MCP en plus de l'accès à l'API ouverte v1.

Connexion établie via Claude.ai (web), mais aucun outil n'apparaît : Claude.ai (web) n'est actuellement pas un client pris en charge. Son ajout en tant que connecteur URL uniquement entraîne l'utilisation par défaut de la découverte OAuth et n'est pas pris en charge par ce serveur. Pour bénéficier de toutes les fonctionnalités, veuillez utiliser un client compatible via stdio.

Vous rencontrez des limitations de débit ou des erreurs 401 répétées après le redémarrage du MCP ? Lorsque vous utilisez CLIENT_ID et CLIENT_SECRET , chaque redémarrage nécessite un nouveau jeton, ce qui est comptabilisé dans la limite de 5 jetons par période de 24 heures. Pour éviter cela, réutilisez un jeton mis en cache entre les redémarrages ou utilisez un BEARER_TOKEN statique, qui ne nécessite pas de nouvel échange.

Si les résultats de réservation ou d'écritures comptables semblent incomplets, assurez-vous d'utiliser l'outil Search Reservations v3, qui prend en charge filter[confirmationCode] . L'ancien outil de recherche est obsolète et peut ne pas renvoyer tous les résultats. Pour les recherches d'écritures comptables ( Get recognized journal entries / Get all journal entries ), si vous continuez à obtenir des résultats inattendus, veuillez ouvrir un ticket d'assistance en fournissant des informations détaillées.

J'ai demandé à l'assistant de créer, de mettre à jour ou d'annuler quelque chose, et il ne l'a pas fait : comportement attendu en version bêta — le serveur MCP est pour l'instant en lecture seule.

Ouverture d'un ticket d'assistance

Commencez par vérifier votre système. Guesty ne peut pas diagnostiquer les problèmes des applications externes. Si le problème provient de votre code, demandez à votre développeur web ou à votre fournisseur technique de l'examiner avant de contacter Guesty. Si votre intégration a été développée par un partenaire de la marketplace, contactez-le en premier lieu. Il contactera Guesty si nécessaire.

Une fois que vous avez écarté tout problème de votre côté, contactez l'Expérience Client ou utilisez le chat en direct. Ces deux options sont disponibles via le tableau de bord Guesty et le Centre d'aide. Plus vous nous fournirez de contexte, plus nous pourrons résoudre votre problème rapidement. Veuillez donc inclure les informations suivantes :

Ce que vous essayiez d'accomplir (l'objectif réel, et pas seulement l'appel qui a échoué — par exemple, « synchroniser le statut de paiement d'une nouvelle réservation », et non pas simplement « la requête POST a renvoyé une erreur 422 »)
Les étapes qui ont conduit à l'erreur , dans l'ordre, afin que l'assistance puisse la reproduire — et pas seulement la requête finale ayant échoué
Quand cela s'est produit — une date et une heure précises si vous en avez une, sinon une date ou une plage de dates ; c'est l'une des informations les plus utiles que vous puissiez fournir.
L'URL complète de la requête et la méthode au format cURL
Le message d'erreur exact et le code d'état
La valeur de l'en-tête de réponse x-request-id
L'en-tête x-gst-kong-dc , s'il est présent (il permet de déterminer quel centre de données a traité la requête)
S'il s'agit d'un nouveau comportement ou si le problème a toujours existé
Pour les problèmes liés à MCP : quel client et quel mode de connexion (stdio/HTTP) ? L’authentification a-t-elle été effectuée via BEARER_TOKEN, CLIENT_ID/CLIENT_SECRET ou set_token ?

Pour en savoir plus

Associé à:

GFP: Open Api