Smoobu tiene una API para que una herramienta o tu propio código lean y escriban tus datos de reservas, además de webhooks que avisan a tu sistema en el momento en que algo cambia. Todo esto lo gestionas en Avanzado > Claves API. Úsalo cuando una herramienta de propiedades necesite acceso a tus reservas o cuando estés construyendo tu propia integración. Esto es solo para usuarios avanzados: el equipo de soporte solo puede ayudar con problemas de integración relacionados con socios del Marketplace, y no puede ayudar con desarrollos propios.
Antes de empezar
Necesitas esto antes de poder usar la API:
- Una cuenta de Smoobu de pago. Las claves no se pueden generar en una prueba gratuita.
- El acceso de la cuenta principal. Solo la cuenta principal tiene claves API. El acceso de un miembro del equipo no tiene la página Claves API. Por eso no puedes limitar una integración a algunas de tus propiedades dándole el acceso de un miembro del equipo.
- Ser consciente de que una clave da acceso a toda tu cuenta. Trata una clave como una contraseña. Lo único que una clave no puede leer sin tu permiso son los datos personales de tus huéspedes.
Consigue una clave API
- En Smoobu, abre Avanzado y luego Claves API.
- Haz clic en Crear nuevo, arriba a la derecha.
- En la ventana Crear un token de API, escribe un nombre corto en Etiqueta (opcional) para reconocer la clave más adelante. Si la herramienta necesita los nombres, las direcciones de correo electrónico o los números de teléfono de tus huéspedes, marca Permitir el acceso a los datos personales de los huéspedes. Si no los necesita, déjalo sin marcar. Haz clic en Enviar.
- Smoobu muestra Token creado con tu nueva clave en el campo Etiqueta y tu Secreto debajo. Copia los dos con los botones de copiar y guárdalos de inmediato en un sitio seguro, como un gestor de contraseñas: Smoobu muestra el secreto una sola vez. Marca He copiado mi secreto y haz clic en Cerrar.
- La nueva clave aparece en la lista con su etiqueta, y puedes volver a copiar la clave en cualquier momento desde la columna Clave. El secreto no se puede volver a mostrar: si lo pierdes, revoca la clave y crea una nueva. Pega la clave y el secreto en la herramienta o el código que necesita acceso.
Cada clave da acceso a toda tu cuenta. Lo único que puedes excluir son los datos personales de tus huéspedes: nombres, direcciones de correo electrónico, números de teléfono, notas y mensajes. La columna Datos de huéspedes de la lista de claves muestra qué claves pueden leerlos. Si usas más de una integración, genera una clave distinta para cada una, así puedes revocar una sin romper las demás. Para retirar una clave, haz clic en Revocar a su lado: cualquier solicitud que aún la use deja de funcionar de inmediato.
Claves que creaste antes del 26 de octubre de 2026
Las claves que ya existían antes de que se añadiera el acceso a los datos de huéspedes pueden seguir leyendo los datos personales de tus huéspedes hasta el 30 de noviembre de 2026. Después de esa fecha, no devuelven ningún dato de huéspedes, a menos que les hayas permitido el acceso a los datos de huéspedes. Si una herramienta necesita los datos de huéspedes, permite el acceso para su clave en la página Claves API antes del 30 de noviembre, para que la herramienta siga funcionando. Si una herramienta no los necesita, no hagas nada: a partir del 1 de diciembre, la clave deja de leer datos de huéspedes.
Mantén tu clave segura
Una clave es una contraseña de toda tu cuenta, así que trátala como tratarías una contraseña:
- Nunca escribas una clave directamente en tu código. Vale para claves API, contraseñas y tokens por igual: quien pueda ver el código puede ver la clave.
-
Guarda las credenciales en variables de entorno, por ejemplo en un archivo
.envque tu código lee en tiempo de ejecución. -
Mantén el archivo
.envfuera del control de versiones. Añade.envy cualquier otro archivo de configuración con secretos a tu.gitignore, para que nunca se suban a GitHub. - Haz privados tus repositorios. Si tu código de integración vive en GitHub, pon la visibilidad del repositorio en privado de inmediato, sobre todo cuando el código es tu propio trabajo.
Si una clave se filtra, revócala en la página Claves API y crea una nueva; la clave filtrada deja de funcionar de inmediato.
Configura un webhook
Un webhook avisa a tu propio sistema cuando algo cambia en Smoobu, así tu sistema no tiene que estar preguntando todo el rato.
- En la página Claves API, busca el campo Webhook URLs.
- Introduce la dirección de tu servidor que debe recibir las actualizaciones.
- Haz clic en Guardar. Puedes añadir más de un webhook.
Smoobu envía cada actualización una sola vez y no lo vuelve a intentar. Si tu servidor no responde en 60 segundos, esa actualización se pierde. Usa la API para recuperar los eventos que te hayan podido faltar. Para ver qué envía Smoobu antes de fiarte de ello, introduce una dirección temporal de un servicio como webhook.site y haz una reserva de prueba.
Smoobu envía un webhook para estos eventos:
- una nueva reserva
- una reserva actualizada
- una reserva cancelada
- una reserva eliminada
- un cambio en los precios, la estancia mínima o la disponibilidad
- un check-in online enviado
- un mensaje nuevo
Esta lista es la completa. No hay webhook para las reseñas, y no hay eventos ocultos ni sin documentar. Los cambios en las líneas de precio de una reserva (elementos de precio) solo se envían a los socios de integración que configura Smoobu, nunca a las direcciones que escribes aquí.
Ese campo solo contiene los webhooks que añades tú. Algunos socios del Marketplace registran los suyos a través de la API de Smoobu cuando los conectas, así que nunca tienes que escribir la dirección de un socio en este campo.
Para saber los datos exactos que Smoobu envía con cada evento, abre la documentación para desarrolladores (docs.smoobu.com): en la página Claves API, haz clic en Click here for API documentation. La misma documentación contiene la referencia completa de endpoints y ejemplos de código.
O conecta una herramienta del Marketplace
Si la herramienta que quieres ya es socio del Marketplace de Smoobu, por ejemplo una herramienta de precios o de check-in, no entregas ninguna clave. Solo sigue las guías del Marketplace de Smoobu. Puedes desconectar a los socios del Marketplace cuando quieras, lo que corta su acceso de inmediato. Esto, sin embargo, quizá no cancele tu suscripción al servicio correspondiente. Usa esta vía cuando exista, y genera tu propia clave solo para una herramienta o un script que no sea un socio de la lista.
Firma tus solicitudes con HMAC
Smoobu está pasando el acceso directo a la API a solicitudes firmadas (HMAC), para que cada llamada demuestre que es genuina y no ha sido alterada. Si construiste tu propia integración, tienes que añadir la firma antes del 31 de octubre de 2026; después de esa fecha, las solicitudes sin firmar se rechazan. Durante el cambio funcionan las dos, firmadas y sin firmar, así que puedes migrar y probar sin romper tu montaje en producción.
Quién tiene que hacer algo:
- Socios del Marketplace (herramientas de precios, de check-in y similares): nada que hacer, el socio se encarga.
- Conexiones de portal (Airbnb, Booking.com y otros portales): no les afecta.
- Tu propio script o integración que controlas tú: añade la firma con los pasos de abajo.
- Una herramienta que no controlas pero en la que pegaste tu clave: sigue los pasos 1 y 2 de abajo para activar la firma. Después, ponte en contacto con la empresa externa y compártele tu nueva clave API y tu secret para que pueda conectarse a Smoobu.
Para configurar la firma:
- Crea una clave como se explica arriba en Consigue una clave API. Cada clave que creas ahí viene con un secreto, que se muestra una sola vez en la ventana Token creado.
- Guarda el secreto a buen recaudo. Si lo pierdes, crea una clave nueva y actualiza tu integración con la nueva clave y el nuevo secreto antes de revocar la antigua, para que tu integración no deje de funcionar entre medias.
- Actualiza tu integración para que firme cada solicitud. Junto a tu clave, cada solicitud envía cuatro cabeceras más:
- X-API-Key (tu clave),
-
X-Timestamp (la hora actual en formato UTC ISO 8601 (ejemplo:
2026-04-01T12:00:00Z)), - X-Nonce (un valor único que no reutilizas nunca; usa UUID v4),
- y X-Signature (la firma HMAC-SHA256). Cómo construir la firma, y el formato exacto de cada cabecera, está en la documentación para desarrolladores: la guía técnica completa con ejemplos de código está disponible aquí: docs.smoobu.com/#hmac-authentication
Lleva tus reservas a tu propio sistema
Puedes traer los datos de tus reservas a tu propia web o a tu propio sistema a través de la API. Quien lo mantenga necesitará la documentación de la API de Smoobu y el endpoint de reservas, GET /api/reservations, con la clave API de tu cuenta. Los nombres y los datos de contacto de los huéspedes solo llegan si la clave tiene permiso para leer datos de huéspedes. Algo que conviene que le digas a tu desarrollador: de los parámetros de fecha de ese endpoint, por ahora solo funcionan from y to.
Problemas frecuentes
Crear nuevo no aparece o no hace nada
La generación de claves está desactivada en las cuentas de prueba gratuita.
Mi clave API ha dejado de funcionar
Smoobu desactiva cualquier clave que no se haya usado durante más de 90 días. No recibes ningún aviso antes, y una clave desactivada no se puede volver a activar. Crea una clave nueva como se describe más arriba y añádela, con su secreto, a tu herramienta o a tu código.
Si cancelas tu plan de pago, tus claves quedan suspendidas. Vuelven a funcionar si te suscribes de nuevo en un plazo de 90 días.
Los nombres y los datos de los huéspedes llegan vacíos
La clave no tiene acceso a los datos personales de tus huéspedes. En ese caso, los nombres, las direcciones de correo electrónico, los números de teléfono y las notas de los huéspedes llegan vacíos. Las solicitudes de datos de huéspedes o de datos del registro en línea se rechazan con 403 Forbidden. Permite el acceso a los datos de huéspedes para esa clave en la página Claves API, o crea una clave nueva con Permitir el acceso a los datos personales de los huéspedes marcado y úsala en tu herramienta. Las fechas, los precios, las propiedades y los pagos no se ven afectados.
Una herramienta de un socio recibe tus actualizaciones de reservas, pero en Smoobu no aparece ningún webhook
No hay nada roto ni nada que arreglar. Cuando un socio del Marketplace registra un webhook por ti, Smoobu lo guarda aparte de los tuyos y no se muestra en ese campo. Tus propios webhooks siguen igual. Si más adelante desconectas al socio, Smoobu elimina sus webhooks por ti.
Mi servidor no recibe algunos webhooks
Smoobu envía cada webhook una sola vez, sin reintentos. Una actualización no llega a tu sistema en estos casos:
- tu servidor no responde en 60 segundos. Smoobu descarta la actualización.
- tu servidor responde con HTTP 400. Tu servidor rechazó los datos que envió Smoobu. Revisa los registros de tu servidor para ver por qué.
Usa la API para recuperar las reservas y los cambios que te hayan podido faltar. Para comprobar qué llega, introduce en el campo de webhooks una dirección temporal de un servicio como webhook.site, haz una reserva de prueba y mira lo que entra. Si tu dirección sigue respondiendo con errores, Smoobu la desactiva y te envía un correo (mira la sección siguiente).
He recibido un correo que dice que mi URL de webhook se ha desactivado
Smoobu desactiva una dirección de webhook cuando responde una y otra vez con errores, y te envía este correo. Mientras está desactivada, esa dirección no recibe actualizaciones de Smoobu.
- Revisa el sistema que hay detrás de la dirección: tu propio servidor o la herramienta para la que la introdujiste. Tiene que estar en línea y aceptar las actualizaciones sin errores. Si la dirección es de una herramienta, ponte en contacto con la empresa que la ofrece.
- En la página Claves API, vuelve a introducir la misma dirección en el campo de webhooks y haz clic en Guardar.
Si la dirección sigue respondiendo con errores, Smoobu la vuelve a desactivar. Si ya no usas esa dirección, no tienes que hacer nada.
Las solicitudes se bloquean con 429
Tus solicitudes fallan con HTTP 429 y el mensaje «Requests limit exceeded»: tu integración envía más solicitudes de las que Smoobu permite. El bloqueo dura mientras tu integración siga llamando. Para salir de él:
- Llama con menos frecuencia. Reparte tus solicitudes en el tiempo.
- Haz una pausa y vuelve a intentarlo. Cuando recibas un 429, espera antes de enviar la siguiente solicitud, en lugar de reintentar enseguida.
- Agrupa solicitudes donde puedas, en lugar de enviar muchas pequeñas.
El límite exacto está en la documentación para desarrolladores (docs.smoobu.com).
Mis solicitudes firmadas fallan con 401 Unauthorized
La firma o la marca de tiempo son la causa habitual. Otras causas frecuentes:
- Desfase de reloj: la hora de tu sistema está desviada más de 5 minutos. Asegúrate de que tu servidor use NTP.
- Nonce reutilizado: cada solicitud debe llevar un X-Nonce único (usa UUID v4 o bytes aleatorios).
- Hash del cuerpo incorrecto: en las solicitudes GET y DELETE, calcula el hash de una cadena vacía, no de null ni undefined.
- Orden de la cadena de consulta: ordena los parámetros alfabéticamente al construir la cadena canónica.
- Codificación distinta: firma el cuerpo JSON en crudo exactamente como se envía, con los mismos espacios y la misma codificación.
Durante el cambio puedes volver a solicitudes sin firmar mientras lo arreglas.
Artículos relacionados
- Agrupa una propiedad y sus subpropiedades para que no se reserven dos veces
- Smoobu para gestores de propiedades
¿Sigues bloqueado?
Si estos pasos no lo han solucionado, contacta con el equipo de Smoobu: abre el menú Ayuda para abrir un ticket o reservar una franja de llamada, o usa la burbuja de chat de la esquina inferior derecha. Para obtener la respuesta más rápida, incluye:
- Tu Smoobu User ID (en el menú del icono de perfil, arriba a la derecha).
- El nombre o ID del alojamiento, si es sobre un alojamiento concreto.
- El Booking ID, si es sobre una reserva concreta (Reservas, luego Ver más).
- El nombre del portal, si es sobre sincronización de portal (Booking.com, Airbnb, Vrbo, etc.).
- Un breve paso a paso: qué hiciste, qué esperabas y qué pasó.
- Capturas de pantalla o una breve grabación de pantalla del problema.
- Tu navegador y sistema operativo, si algo se ve mal en pantalla.
Comentarios
0 comentarios
Inicie sesión para dejar un comentario.