Para usar la API de ThinkReservations, creas una Restricted API Key en tu cuenta y la compartes con quien esté desarrollando tu integración. Este artículo explica cómo crear una clave, elegir su alcance, mantenerla segura y revocarla.
Si aún no estás seguro de si la API es adecuada para ti, empieza con el artículo The ThinkReservations API.
Antes de empezar
Necesitas el permiso de usuario "Can manage API keys". Los propietarios de la cuenta ya lo tienen. Si no eres propietario de la cuenta, alguien que pueda editar la configuración de usuarios puede darte acceso.
Este permiso controla tanto la creación de claves como la visualización de las existentes. Si no ves una página de API Keys en tu configuración, lo más probable es que la causa sea este permiso. El propietario de tu cuenta puede otorgártelo.
Como una clave de API puede leer tus reservas y, potencialmente, los datos de contacto de tus huéspedes, te recomendamos otorgar este permiso solo a las personas que realmente se encargarían de coordinar una conexión con un desarrollador, en lugar de otorgarlo de forma amplia.
Crear una clave
Ve a Settings → API Keys (manage.thinkreservations.com/settings/api-keys).
Crea una clave nueva.
Selecciona los alcances (scopes) que debe tener la clave. Consulta Selección de alcances más abajo.
Guarda la clave, luego cópiala y entrégala a tu desarrollador usando un método seguro.
Copia la clave en un lugar seguro cuando la crees, y trátala como una contraseña desde ese momento.
Actualmente no hay límite en la cantidad de claves que puedes crear.
Selección de alcances
El acceso se divide en permisos individuales, llamados alcances (scopes). Otorgas cada uno por separado. Tu clave solo incluye lo que selecciones al crearla.
Alcances disponibles:
read:hotel - Leer los detalles del hotel
read:rate - Leer la información de tarifas
write:rate - Actualizar tarifas diarias y reglas de disponibilidad
read:room - Leer los detalles de habitaciones/unidades y los tipos de habitación
read:availability - Leer la disponibilidad de las unidades
read:reservation - Leer los detalles de las reservas
read:customer - Leer los datos de contacto de huéspedes y clientes
Otorga solo lo que la integración necesita. Si tu desarrollador está creando un reporte de ocupación, no necesita permiso para actualizar tus tarifas. Si está creando un resumen de ingresos, probablemente no necesita los correos electrónicos de los huéspedes. Pregunta a tu desarrollador qué permisos requiere realmente, en lugar de otorgarlo todo.
Los datos de contacto de los huéspedes merecen especial atención. Este permiso cubre nombre, correo electrónico, teléfono, empresa, dirección y notas del huésped. Sin él, tus reservas igualmente se reciben; simplemente no incluyen el registro de contacto del huésped.
Consulta la sección de privacidad en The ThinkReservations API para saber qué oculta y qué no oculta.
Los permisos quedan fijos una vez creada la clave. No puedes editarlos después. Para cambiar a qué puede acceder una clave, crea una clave nueva con los permisos que quieras, apunta la integración a la nueva clave y elimina la anterior. No hay límite en la cantidad de claves que puedes crear, así que esto es algo rutinario y no una solución improvisada.
Tu Hotel ID
Tu desarrollador necesitará el Hotel ID de tu propiedad. Se muestra junto a tu clave en la página Settings → API Keys.
Cada clave funciona con una sola propiedad. Si administras varias propiedades, tendrás que crear una clave en cada una. Las claves son específicas de cada propiedad; es decir, una clave de una propiedad no puede acceder a los datos de otra.
Cómo mantener tu clave segura
Una clave de API es una credencial, como una contraseña. Cualquiera que la tenga puede leer los datos que permitan los permisos de la clave. Trátala en consecuencia:
No la envíes por correo a varias personas ni la publiques en un documento compartido.
Entrégala a tu desarrollador usando un administrador de contraseñas u otro método seguro.
Si crees que una clave pudo haber quedado expuesta, elimínala y crea una de reemplazo.
Crea una clave por cada propósito. Si tienes dos usos distintos, por ejemplo un script de reportes y el proyecto de un desarrollador, crea dos claves en lugar de compartir una. Así puedes desactivar una sin afectar la otra. Como las claves son ilimitadas, no hay razón para compartirlas.
Revocar una clave
Elimina la clave en Settings → API Keys. Cualquier usuario con el permiso "Can manage API keys" puede hacerlo.
La eliminación surte efecto de inmediato. Lo que estuviera usando esa clave deja de funcionar al instante. No hay periodo de espera y no necesitamos hacer nada de nuestra parte. Si terminas la relación con un desarrollador o proveedor que tiene tu clave, eliminarla corta su acceso de inmediato.
Como el corte es inmediato, asegúrate de saber qué depende de una clave antes de eliminarla, o podrías interrumpir un reporte o una conexión que quieres conservar.
Si vas a cerrar tu cuenta
Las claves de API no se desactivan automáticamente cuando se cierra una cuenta. Si vas a cerrar tu cuenta de ThinkReservations, te recomendamos eliminar tus claves de API como parte del cierre, sobre todo si un desarrollador o un tercero estaba usando una.
Si una empresa de software te pide una clave
De vez en cuando, una empresa de tecnología te pedirá que crees una clave de API y la compartas con ella para conectar su producto con ThinkReservations.
Es tu cuenta y tu decisión, pero hay algunas cosas que conviene saber antes de hacerlo:
Eres responsable de proteger la información personal de tus clientes y huéspedes.
La clave les da acceso a los datos de tu propiedad con los permisos que selecciones. Es una credencial, así que compártela con el mismo cuidado que aplicarías a cualquier otro inicio de sesión.
Las Restricted API Keys están diseñadas para que una propiedad trabaje con sus propios datos. Se espera que las empresas que desarrollan productos que se conectan con propiedades de ThinkReservations trabajen con nosotros a través de nuestro programa de socios, que usa un tipo de acceso diferente.
Cualquier cosa creada de esta manera es un asunto entre tú y esa empresa. Si deja de funcionar, no podemos dar soporte ni reparar su integración.
Si un proveedor está interesado en convertirse en un socio oficial de integración de ThinkReservations, nos gustaría saber de él directamente. Pídele que escriba a product@thinkreservations.com.
Solución de problemas
No veo una página de API Keys en mi configuración. Lo más probable es que no tengas el permiso "Can manage API keys". Los propietarios de la cuenta lo tienen por defecto y pueden otorgarlo a otros usuarios. Este permiso también controla la visualización de las claves existentes, así que sin él la página no aparecerá.
Mi desarrollador dice que se está rechazando una solicitud. Si se trata de una solicitud de una lista de propiedades o de datos de varias propiedades, es lo esperado. Las Restricted API Keys no pueden usar esa solicitud y no la necesitan. Tu Hotel ID único se muestra en la página Settings → API Keys.
Los correos electrónicos de los huéspedes no aparecen en los resultados. A la clave no se le otorgó permiso para acceder a los datos de contacto de los huéspedes. Como los permisos quedan fijos al crear la clave, tendrás que crear una clave nueva con ese permiso seleccionado y eliminar la anterior.
Necesito cambiar a qué puede acceder mi clave. Los permisos no se pueden editar después de crear una clave. Crea una clave nueva con los permisos que necesitas, cambia la integración a ella y luego elimina la clave anterior.
Algo que funcionaba dejó de funcionar. Verifica que la clave no haya sido eliminada. Si aún necesitas ayuda, comunícate con soporte para ver si hay un problema conocido con la API.
¿Puedo ver si mi clave se ha usado? Sí. Hay una columna "Last used" en la página API Keys, dentro del menú Settings de tu cuenta de ThinkReservations.
Recursos adicionales: La documentación de la API creada por nuestro equipo de desarrollo es muy completa y será tu recurso principal para cualquier pregunta adicional.
Nuestro soporte se limita a los siguientes recursos de documentación: