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 Empezar.

La API abierta proporciona un único ámbito de administrador. Tus credenciales te dan acceso a todas las funciones que ofrece. Los puntos de acceso de la API abierta para los complementos de Guesty, como contabilidad (que incluye proveedores, gastos y estados de cuenta de los propietarios) y GuestyPay™ (transacciones de pago y desembolsos), requieren una suscripción a dichos productos. Asimismo, los puntos de acceso piloto o beta requieren la participación en el grupo de prueba correspondiente (los puntos de acceso de reservas v3, cotizaciones e informes de reservas son la excepción).

Las credenciales de la API abierta no son intercambiables con las credenciales de la API del Motor de reservas. Además, las credenciales están vinculadas a la cuenta con la que se crearon. Si tienes más de una cuenta de Guesty, asegúrate de usar las credenciales correctas para cada API y cada cuenta. Dispones de 5 espacios por defecto. Ponte en contacto con el equipo de Experiencia del Cliente si estás utilizando los 5 espacios y necesitas más.

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 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.

Los intentos fallidos de tokenización también consumen tu cuota.

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, consulta 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}

5. Suscribirse a los webhooks y gestionarlos.

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" justo después de autenticarme : Su token ha caducado (duran 24 horas) o no se ha enviado correctamente. Nota: La API de Guesty devuelve un 401 / 403 incluso cuando el mensaje dice "No autorizado"; esto es normal, no un error de su parte. Solución: vuelva a autenticarse y vuelva a almacenar en caché el token; 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 ver su presupuesto diario de tokens directamente. Más: Autenticación .

404 — recurso no encontrado, pero el ID parece correcto : Normalmente, el ID pertenece a una cuenta/ámbito diferente al de tu token, o el registro aún no se ha sincronizado, o proviene de un canal con visibilidad limitada de la API. Confirma el ID con el panel de control de la misma cuenta a la que pertenecen tus credenciales. Por ejemplo, GET /reservations-v3/group/{groupId} devuelve 404 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 una forma consistente en toda la API: Algunos campos anidan dentro del error, otros no, y los nombres de los campos varían, así que 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 la 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 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 lista, 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 su webhook no se activa o no puede suscribirse a uno, verifique lo siguiente: (1) Confirme que está suscrito al nombre de evento v2 correcto, ya que los webhooks heredados y v2 no son intercambiables. (2) Garantice que su endpoint devuelva una respuesta 2xx, ya que Guesty dejará de reintentar si no lo hace. (3) En cuentas de prueba o sandbox, verifique 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, tarifa o estadía mínima, no para reservas nuevas o modificadas. Para verificar la autenticidad de un webhook, recupere el secreto de firma de su endpoint usando GET /webhooks-v2/secret. Para obtener más información, consulte Resumen de los webhooks.

La automatización de pago programada no se ha recalculado al importe correcto: La intervención manual en los pagos de la reserva desactiva las automatizaciones de pago, dejando los pagos programados sin cambios. Valide el estado de la automatización recuperando el parámetro money.isTouchedPayments de su reserva mediante GET /reservations/{id}?fields?money.isTouchedPayments. Si devuelve false, su automatización está intacta; de lo contrario, true significa que debe cancelar y reprogramar los próximos pagos con los importes recalculados.

Si actualizó el título o la descripción del anuncio a través de la API y no ve el cambio en Airbnb, verifique 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 desbloquee 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, consulte 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 "Bandeja de bolos incorrecta 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 la 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 toda la integración y el desarrollo inicial, 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.

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: Se esperaba en la versión beta; el servidor MCP es de solo lectura por ahora.

MCP Server (Beta)

The Guesty MCP Server lets MCP-compatible AI assistants — currently Cursor, Claude Desktop, VS Code (Copilot), and Google Antigravity — read Guesty data through a controlled tool interface. It's read-only in beta: assistants can look up and summarize data, but can't create, update, or delete records yet. Tool coverage may still change before general availability.

All Guesty Pro accounts have access to the MCP authenticated with the same OAuth credentials used for the Guesty Open API. The 5-slot limit refers to the number of available slots; contact Customer Experience if you are using all 5 slots and need additional ones. 

Connecting

• Local (stdio, recommended): Run using npx -y @guestyorg/sdk mcp. You can use a BEARER_TOKEN environment variable for a static access token, or CLIENT_ID and CLIENT_SECRET environment variables. The MCP server will exchange these credentials for you, so no manual token step is required.
• Hosted (HTTP, https://mcp.guesty.com/v1): Authenticate using an Authorization header at the start of the session, or use the set_token tool after connecting.

Troubleshooting

401 on every tool call: This indicates that no token was set. For hosted or HTTP connections, ensure you set the token using set_token or the Authorization header before using any other tool.

403, inconsistently: 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: Se esperaba en la versión beta; el servidor MCP es de solo lectura por ahora.

Abrir un ticket de asistencia

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

Una vez que hayas descartado problemas de tu parte, contacta con el equipo de 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 la asistencia pueda reproducirlo, no solo la solicitud final que falló.
• Cuándo ocurrió: una marca de tiempo exacta si la tienes, de lo contrario, una fecha o un rango de fechas; esto es una de las cosas más útiles que puedes 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

• Referencia completa de la API
• Servidor MCP (Beta)
• Empezar
• Autenticación
• Límites de Tarifa
• Códigos de respuesta
• Gestión de solicitudes fallidas
• Resumen de los webhooks
• Guía de la colección de Postman
• Contactar con Experiencia del Cliente o Chat en vivo