Guesty Open API: Inicio rápido y solución de problemas

Esta guía está dirigida a desarrolladores que se integran por primera vez con la API abierta de Guesty. Referencia completa: open-api-docs.guesty.com

Inicio rápido

1. Obtén tus credenciales

Para empezar, asegúrate de que tu cuenta de Guesty tenga acceso a la API abierta. Necesitarás tus credenciales de OAuth: client_id y client_secret. Para obtener instrucciones paso a paso, consulta la sección Empezar.

2. Autenticar

Intercambia tus credenciales por un token de portador: POST https://open-api.guesty.com/oauth2/token con grant_type=client_credentials, scope=open-api, client_id, y client_secret. El token es válido durante 24 horas.

Mantén tu token seguro y controla su fecha de caducidad. Cada client_id puede solicitar un nuevo token hasta cinco veces en 24 horas. Si alcanzas este límite, no podrás obtener un nuevo token hasta que se reinicie el plazo. Para evitar problemas, planifica la renovación de tu token unos minutos antes de que caduque. Para ver ejemplos de código en Node.js, Python y PHP, consulta la receta de Gestión de tokens de acceso. Para más detalles, consulta Autenticación.

3. Haz tu primera llamada

Envía el token como encabezado de portador en cada solicitud:

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

4. Gestionar la paginación

La mayoría de los puntos finales utilizan los parámetros de consulta limit y skip para la paginación y devuelven items , count , limit y skip en la respuesta. Algunos puntos finales pueden usar offset o cursor , o devolver un formato de respuesta diferente. Si los parámetros estándar no funcionan, reseña la página de referencia de ese punto final específico. Por ejemplo:

offset en lugar de skip : GET /properties-api/groups/group
basado en cursor : GET /communication/conversations , GET /communication/conversations/{conversationId}/posts
results + un objeto pagination anidado: GET /reservations-v3/search (el mismo punto final de búsqueda de Reservas v3 que se utiliza en otras partes de esta guía)
results / count en lugar de items / count : GET /vendors, GET /users, GET /property-logs/{id}

Solución de problemas y preguntas frecuentes

Antes de volver a intentar una solicitud, compruebe el código de estado. Solo los errores 429 y 5xx deben reintentarse automáticamente. Otros códigos de estado indican que la solicitud debe modificarse antes de volver a intentarlo.

Por código de respuesta

401 / 403 — "No autorizado" inmediatamente después de la autenticación : Su token ha caducado (su validez es de 24 horas) o no se ha enviado correctamente. Nota: La API de Guesty devuelve un 403 incluso cuando el mensaje indica "No autorizado". Esto es normal y no constituye un error por su parte. Solución: Vuelva a autenticarse y vuelva a almacenar el token en caché; confirme que el encabezado sea exactamente Authorization: Bearer <token> . El endpoint del token también expone los encabezados x-ratelimit-remaining-day / x-ratelimit-limit-day si desea consultar su presupuesto diario de tokens directamente. Más información: Autenticación .

404 — Recurso no encontrado, pero el ID parece correcto : Normalmente, el ID pertenece a una cuenta o ámbito diferente al de su token, o el registro aún no se ha sincronizado, o proviene de un canal con visibilidad limitada en la API. Confirme el ID con el panel de control de la misma cuenta a la que pertenecen sus credenciales. Por ejemplo, GET /reservations-v3/group/{groupId} devuelve 404 tanto para un ID que parece válido en la cuenta incorrecta como para uno inexistente. Más información: Códigos de respuesta .

410 — Cotización caducada : Las cotizaciones tienen un plazo de caducidad fijo. Una vez caducadas, no se pueden modificar ni reservar. Cree una nueva en lugar de volver a intentar con la ID anterior.

400 / 422 — Error de validación : Compruebe el cuerpo de la solicitud con el esquema de ese endpoint en su página de referencia. Las respuestas de error de Guesty no tienen un formato consistente en toda la API: algunos campos anidan dentro del error, otros no, y los nombres de los campos varían. Por lo tanto, no asuma que el nombre de un campo de error de un endpoint se aplica a otro. Por ejemplo, POST /reservations-v3 (reserva rápida) devuelve tanto 400 como 422 dependiendo de si la solicitud en sí está mal formada o infringe una regla de reserva (por ejemplo, fechas no disponibles). Compruebe cuál recibió antes de asumir la solución.

429 — límite de tarifa: Esto significa que ha alcanzado el límite de la cuenta de 15 solicitudes por segundo, 120 por minuto o 5000 por hora, compartido entre todos los tokens. Espere el tiempo especificado en el encabezado Retry-After antes de enviar otra solicitud. Supervise los encabezados X-RateLimit-Remaining-Second, X-RateLimit-Remaining-Minute y X-RateLimit-Remaining-Hour para realizar un seguimiento de su uso. También puede ver los encabezados ratelimit-limit, ratelimit-remaining y ratelimit-reset, que reflejan la ventana por segundo. Antes de solicitar un límite más alto, considere el procesamiento por lotes, el almacenamiento en caché, el filtrado o el uso de webhooks para optimizar su integración. Si se aplica un límite más bajo después de un exceso sostenido, esto puede indicar que se revirtió un aumento anterior. Para obtener más detalles, consulte Límites de Tarifa.

"No puedo crear otra aplicación OAuth / client_id": Este es un límite independiente (el número de aplicaciones OAuth por cuenta es de cinco), distinto del límite de solicitudes mencionado anteriormente. Si necesita más, póngase en contacto con el servicio de asistencia y explique su caso de uso.

5xx — error del servidor: Reintente con retroceso exponencial y fluctuación en lugar de un bucle inmediato. La mayoría de los errores 5xx son transitorios; si un punto final falla repetidamente, incluya el encabezado de respuesta x-request-id cuando se comunique con el servicio de asistencia. Excepción: Para una solicitud de pago o modificación de reserva, verifique primero el estado resultante real; no reintente a ciegas, o corre el riesgo de cobrar dos veces a un huésped. Más: Manejo de solicitudes fallidas.

Por síntoma

Si una reserva o anuncio no aparece en los resultados de búsqueda o en el listado, primero revise los parámetros de filtro y alcance. Esta es la causa más común. Para los registros recientes, espere a que se sincronicen, especialmente para las reservas de plataformas como Airbnb, Vrbo o Booking.com. Para esto sirve específicamente GET /reservations-v3/search, confirme que lo está utilizando (con los parámetros filter[...] correctos) en lugar de un endpoint anterior o más limitado. Si el registro sigue sin aparecer, póngase en contacto con la asistencia e indique el ID específico y la solicitud exacta que utilizó.

Si tu webhook no se activa o no puedes suscribirte a uno, verifica lo siguiente: (1) Confirma que estás suscrito al nombre de evento v2 correcto, ya que los webhooks heredados y v2 no son intercambiables. (2) Asegúrate de que tu endpoint devuelva una respuesta 2xx, ya que Guesty dejará de reintentar si no lo hace. (3) En cuentas de prueba o sandbox, verifica que la suscripción se haya creado correctamente. La entrega puede retrasarse durante períodos de alta carga. El evento listing.calendar.updated se activa solo para ediciones directas del calendario, la tarifa o la estadía mínima, no para reservas nuevas o modificadas. Para verificar la autenticidad de un webhook, recupera el secreto de firma de tu endpoint usando GET /webhooks-v2/secret. Para obtener más información, consulta Resumen de los webhooks.

Si actualizaste el título o la descripción del anuncio a través de la API y no ves el cambio en Airbnb, verifica si el campo se editó directamente en Airbnb. Si fue así, Airbnb bloquea el campo y las actualizaciones de la API no se sincronizarán hasta que lo desbloquees en Airbnb. Las actualizaciones que utilicen PUT /marketing/description-sets/{id} o POST /marketing/description-sets no se sincronizarán con Airbnb hasta que se desbloquee el campo. Otros canales como Booking.com y Vrbo pueden tener requisitos similares. Para obtener más información, consulta Campos de Marketing y traducciones.

GuestyPay devuelve 402 ERR_BAD_REQUEST: Si la respuesta incluye "La solicitud contradice la configuración de la interfaz de limpieza" o "Credenciales incorrectas o desconexión del anfitrión", la cuenta de GuestyPay tiene un problema de configuración o está sin conexión; esto no es algo que pueda solucionar en su integración. Póngase en contacto con el equipo de Experiencia del Cliente.

La forma del error no coincide con lo que vi en otro endpoint: Como era de esperar, no hay un único sobre de error en toda la API. Aunque un patrón es el más común: un mensaje anidado bajo una única clave de error, por ejemplo, GET /accounting-api/reservations/{id}/balance → {"error": {"message": "...", "status": 404}}. Sin embargo, no es universal: algunos endpoints son planos con el mensaje como una matriz de cadenas ( GET /guest-folio/invoice-items → {"statusCode": 400, "message": [...]}), y algunos incluyen su propio campo requestId a nivel de cuerpo, separado del encabezado de respuesta x-request-id ( GET /availability-pricing/api/calendar/listings/{id}). Un buen número de endpoints no documentan en absoluto la forma del cuerpo del error, solo una descripción de texto. Consulte el esquema de errores documentado del punto final específico en lugar de codificar una forma fija.

¿Necesito una cuenta de prueba o una cuenta de entorno de pruebas? Aquí tienes una regla general: usa una cuenta de prueba para casi todas las integraciones y el desarrollo iniciales, a menos que estés probando específicamente flujos relacionados con Stripe, en cuyo caso necesitas un entorno de pruebas. Usa el entorno de producción solo cuando estés listo para lanzar con datos reales. Las cuentas de prueba son el estándar para las nuevas solicitudes de integración y funcionan igual que tu entorno de producción, solo que con datos de prueba separados. Los entornos de pruebas son entornos separados (busca "sandbox" en la URL) que se usan para las pruebas de integración de Stripe porque Guesty no acepta claves de prueba de Stripe ni en las cuentas de producción ni en las de prueba habituales. GuestyPay no tiene ningún entorno de prueba; solo funciona en vivo, por lo que debes usar una tarjeta real para las pruebas de GuestyPay, independientemente del tipo de cuenta que uses.

Una cuenta de prueba es un complemento de pago y es independiente de su entorno de producción. Los datos no se transfieren desde producción, por lo que deberá configurar los anuncios, las reservas y otra información desde cero. Para obtener una cuenta de prueba, póngase en contacto con su gestor de cuentas.

Servidor MCP (Beta)

El servidor Guesty MCP permite que los asistentes de IA compatibles con MCP (actualmente Cursor, Claude Desktop, VS Code (Copilot) y Google Antigravity) lean los datos de Guesty a través de una interfaz de herramientas controlada. En versión beta, solo permite la lectura: los asistentes pueden consultar y resumir datos, pero aún no pueden crear, actualizar ni eliminar registros. La compatibilidad con las herramientas podría cambiar antes de su disponibilidad general.

Conexión

Actualmente, puede conectarse mediante el método local o el alojado. Todavía no está disponible una implementación totalmente administrada con credenciales preconfiguradas.

Local (stdio, recomendado) : Ejecute con npx -y @guestyorg/sdk mcp. Puede usar la variable de entorno BEARER_TOKEN para un token de acceso estático, o las variables de entorno CLIENT_ID y CLIENT_SECRET. El servidor MCP intercambiará estas credenciales automáticamente, por lo que no se requiere ningún paso manual para el token.
Alojado (HTTP, https://mcp.guesty.com/v1 ) : Autentíquese mediante un encabezado Authorization al inicio de la sesión o utilice la herramienta set_token después de conectarse.

Solución de problemas

Error 401 en cada llamada a la herramienta : Esto indica que no se ha configurado ningún token. Para conexiones alojadas o HTTP, asegúrese de configurar el token mediante set_token o el encabezado Authorization antes de usar cualquier otra herramienta.

403, Inconsistente: Este error puede ocurrir con tokens caducados o cuando los clientes OAuth tienen permisos para el acceso estándar a la API abierta, pero no para MCP. Primero, vuelva a autenticarse con un nuevo token. Si el problema persiste, confirme que el cliente OAuth tenga permisos para MCP, además del acceso a la API abierta v1.

Conectado a través de Claude.ai (web), pero no aparecen las herramientas: Claude.ai web no es un cliente compatible actualmente. Si se agrega como conector solo URL, se activará por defecto la detección OAuth, que este servidor no admite. Utilice un cliente compatible a través de stdio para obtener todas las funcionalidades.

Si se producen limitaciones de velocidad o errores 401 repetidos tras reiniciar el MCP: al usar CLIENT_ID y CLIENT_SECRET, cada reinicio solicita un nuevo token, que se contabiliza dentro del límite de 5 tokens cada 24 horas. Para evitarlo, reutilice un token almacenado en caché entre reinicios o utilice un BEARER_TOKEN estático, que no requiere intercambio.

Si los resultados de las reservas o los asientos contables aparecen incompletos, confirme que está utilizando la Search Reservations tool v3, que admite filter[confirmationCode]. La herramienta de búsqueda anterior está quedando obsoleta y es posible que no muestre todos los resultados. Para las búsquedas de asientos contables ( Get recognized journal entries / Get all journal entries ), si continúa viendo resultados inesperados, envíe una solicitud de asistencia con información detallada.

Le pedí al asistente que creara, actualizara o cancelara algo, y no lo hizo: Era de esperar en la versión beta; el servidor MCP es de solo lectura por ahora.

Abrir un ticket de asistencia

Primero, revise su propio sistema. Guesty no puede diagnosticar problemas en aplicaciones externas. Si el problema pudiera estar en su código, pida a su desarrollador web o proveedor técnico que lo revise antes de contactar a Guesty. Si un socio del mercado creó su integración, contáctelo primero. Ellos se comunicarán con Guesty si es necesario.

Una vez que hayas descartado problemas de tu parte, contacta con la Experiencia del cliente o utiliza el chat en vivo . Ambas opciones están disponibles a través del panel de control de Guesty y el Centro de ayuda. Proporcionar contexto nos ayuda a resolver tu problema más rápidamente, así que incluye:

Lo que intentabas lograr (el objetivo real, no solo la llamada fallida, por ejemplo, "sincronizar el estado de pago de una nueva reserva", no solo "POST devolvió 422")
Los pasos que llevaron al error , en orden, para que el equipo de asistencia pueda reproducirlo, no solo la solicitud final que falló.
Cuándo ocurrió : una marca de tiempo exacta si la tiene, de lo contrario una fecha o un rango de fechas; esta es una de las cosas más útiles que puede proporcionar.
La URL completa de la solicitud y el método en formato cURL.
El mensaje de error exacto y el código de estado
El valor del encabezado de respuesta x-request-id
El encabezado x-gst-kong-dc , si está presente (ayuda a determinar qué centro de datos atendió la solicitud).
Ya sea que se trate de un comportamiento nuevo o que siempre haya fallado
Para problemas con MCP: qué cliente y modo de conexión (stdio/HTTP), y si la autenticación se realizó mediante BEARER_TOKEN , CLIENT_ID / CLIENT_SECRET o set_token

Para más información

Relacionada con:

GFP: Open Api