¿Cómo configuro la autenticación HMAC en la API?

A partir del 25 de septiembre de 2026, todas las solicitudes a la API de Smoobu deberán autenticarse mediante firmas HMAC-SHA256. En esta guía te explicamos cómo te afecta esto y te ofrecemos instrucciones paso a paso para actualizar tu integración.

¿Qué es la autenticación HMAC?

HMAC (Hash-based Message Authentication Code) es un estándar de seguridad que garantiza que cada solicitud de API sea auténtica y no haya sido manipulada.

En lugar de enviar solo tu clave de API, cada solicitud se firma con un secreto, de forma similar a como los bancos verifican las transacciones.

¿Me afecta esto?

• No: No te afecta si solo utilizas integraciones oficiales de socios conectadas a través del Smoobu Marketplace (por ejemplo, PriceLabs, Chekin). Estos socios se encargan de la migración automáticamente por su parte.
• Sí:
  • Si utilizas la API de Smoobu directamente a través de tus propios scripts o integraciones personalizadas en las que controlas el código, sigue los pasos que se indican a continuación.
  • Si has pegado tu clave API de Smoobu en una herramienta de terceros que no controlas (por ejemplo, una herramienta de precios o un gestor de canales que no está en el Smoobu Marketplace). No puedes migrar esto tú mismo, porque el proveedor de la herramienta tiene que implementar la nueva firma por su parte. Consulta «¿Usas una herramienta de terceros?» más abajo.

¿Usas una herramienta de terceros?

Si tu clave API la utiliza una herramienta de terceros que no controlas, no elimines tu clave ni intentes migrarla tú mismo, ya que eso rompería la integración.

En su lugar, ponte en contacto con nuestro equipo de soporte y dinos qué herramienta estás utilizando. Nos pondremos en contacto directamente con el proveedor y le configuraremos el nuevo método de firma. Tu clave API actual seguirá siendo la misma y tu integración seguirá funcionando durante todo el proceso de migración mientras nos encargamos de esto.

Paso a paso

1) Abre tu cuenta de Smoobu y ve a Avanzado > Claves API

2) Haz clic en «Crear nuevo» y, a continuación, ponle a tu clave un nombre descriptivo (por ejemplo, «Mi integración con Smoobu» o «Script de sincronización de canales») para que puedas identificarla fácilmente más adelante. Haz clic en «Enviar».

3) Después de hacer clic en «Enviar», se mostrará tu clave secreta una sola vez: cópiala inmediatamente y guárdala en un lugar seguro (como un gestor de contraseñas o las variables de entorno de tu aplicación).

💡 Consejo: Si pierdes tu clave secreta, puedes volver a generarla en esta página. Ten en cuenta que al volver a generarla, la clave secreta actual quedará invalidada de inmediato, así que asegúrate de actualizar primero tus Integraciones.

4) Actualiza tu integración para firmar las solicitudes. La guía técnica completa con ejemplos de código está disponible aquí: docs.smoobu.com/#hmac-authentication

Ahora, todas las solicitudes a la API deben incluir estos encabezados:

5) Durante el periodo de migración (desde ahora hasta el 25 de septiembre de 2026), Smoobu acepta tanto solicitudes firmadas como sin firmar. Puedes implementar tu integración actualizada y comprobar que funciona sin afectar a tu configuración actual.

💡Consejo: Envía unas cuantas solicitudes con los nuevos encabezados y comprueba que recibes respuestas correctas. Si ves un error 401 No autorizado, revisa bien tu marca de tiempo (debe estar dentro de los 5 minutos de la hora del servidor) y asegúrate de que tu nonce no se ha reutilizado

6) Elimina tu clave API antigua (opcional, pero recomendable). Si tienes una clave API en «Claves API heredadas», puedes eliminarla una vez que hayas configurado tu nueva clave. Durante el periodo de migración, tanto las claves antiguas como las nuevas funcionan, por lo que puedes hacerlo después de completar las pruebas.

💡 Consejo: No elimines tu clave antigua hasta que tu nueva integración firmada esté funcionando. Ambas pueden coexistir durante el periodo de migración.

Preguntas frecuentes

¿A quiénes se aplican estos cambios?

Esto se aplica si utilizas la API de Smoobu directamente, por ejemplo con:

• Tus propios scripts
• Integraciones personalizadas
• Herramientas de terceros en las que has introducido manualmente tu clave API

Si utilizas una integración de un socio a través del Smoobu Marketplace (como Pricelabs, Chekin o integraciones similares), no es necesario que hagas nada. Tu socio de integración se encargará de la actualización.

Además, las conexiones API con portales de reservas (Airbnb, Booking.com, etc.) tampoco se ven afectadas por este cambio.

¿Qué sigue igual?

• El valor de tu clave API no cambia
• Todos los puntos de conexión de la API de Smoobu funcionan exactamente igual que antes
• Se aplican los mismos formatos de datos y respuestas

¿Qué hay de nuevo?

• Cada solicitud incluye una marca de tiempo, un nonce único y una firma
• Generas un secreto desde tu panel de control de Smoobu para crear esa firma

Me sale un error 401 No autorizado, ¿qué debería comprobar?

Causas habituales:

• Desfase de reloj: la hora de tu sistema tiene una diferencia de más de 5 minutos. Asegúrate de que tu servidor usa NTP.
• Nonce reutilizado: cada solicitud debe tener un X-Nonceúnico. Usa UUID v4 o bytes aleatorios.
• Hash del cuerpo incorrecto: para solicitudes GET/DELETE, aplica un hash a una cadena vacía (no null ni undefined).
• Orden de la cadena de consulta: los parámetros deben ordenarse alfabéticamente al construir la cadena canónica.
• Discrepancia de codificación: firma el cuerpo JSON sin procesar exactamente tal y como se envía (con los mismos espacios y la misma codificación).

Mi antigua clave API ha dejado de funcionar, ¿qué ha pasado?

Si has pasado la fecha límite del 25 de septiembre de 2026 y no has añadido la firma HMAC, las solicitudes sin firmar devuelven un error 401.

Para solucionarlo:

1. Ve a Avanzado > Claves API
2. Crea una nueva clave y genera un secreto
3. Actualiza tu integración para firmar las solicitudes

¿Puedo seguir usando mi antigua clave API?

Sí. Tu clave API sigue siendo la misma.

Solo tienes que añadir estos encabezados junto a tu X-API-Keyexistente:

• X-Timestamp
• X-Nonce
• X-Signature

¿Qué pasa si pierdo mi secreto?

1. Ve a: Avanzado > Claves API
2. Busca tu clave y haz clic en Regenerar secreto.
3. El secreto antiguo dejará de funcionar inmediatamente, así que actualiza tu integración cuanto antes.

¿Cuál es el calendario de migración?

Guía técnica completa

Para consultar la referencia técnica completa —que incluye ejemplos de código detallados en cURL, PHP y Node.js—, visita la documentación de la API de Smoobu:

https://docs.smoobu.com/#hmac-authentication

Esta página contiene todo lo que necesitas para implementar la firma HMAC en tus integraciones.