Cerraduras

yaReserva no maneja cerraduras. Lo que hace es avisar al puente del hotel en tres momentos, y el puente habla con Salto KS, TTLock, Dormakaba/Saflok, Assa Abloy Vostio o el sistema que sea.

Recepción también puede emitir una llave extra o revocar una desde la pantalla de la reserva.

El hotel crea la conexión en su panel, en Configuración → Cerraduras. Elige una propiedad, el tipo «Puente por webhook» y la URL base de tu puente, que tiene que ser https y apuntar a una IP pública. Ahí recibe, una sola vez, el par de credenciales.

Después, el hotel mapea cada habitación con el id de su cerradura en el sistema del proveedor, el «lockId». Es lo que te mandamos para que sepas qué puerta abrir.

Las tres llamadas son POST con Content-Type: application/json a tu URL base más una ruta. Todas llevan los mismos headers.

X-YR-Lock-Key:       <keyId>
X-YR-Lock-Timestamp: <segundos Unix, UTC>
X-YR-Lock-Signature: sha256=<hex(HMAC-SHA256(secret, timestamp + "." + cuerpo))>
User-Agent:          yaReserva-Locks/1

1. 1Busca el secreto por X-YR-Lock-Key.
2. 2Rechaza si el timestamp difiere de tu reloj en más de cinco minutos. Sincroniza con NTP.
3. 3Calcula el HMAC sobre los bytes exactos del cuerpo recibido, sin re-serializar el JSON, y compáralo en tiempo constante.
4. 4Contesta 401 si algo no cuadra, sin procesar nada.

const crypto = require('crypto');

function verificar(req, rawBody, secret) {
  const ts = req.headers['x-yr-lock-timestamp'];
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;
  const esperada =
    'sha256=' +
    crypto.createHmac('sha256', secret).update(`${ts}.`).update(rawBody).digest('hex');
  const recibida = req.headers['x-yr-lock-signature'] || '';
  return (
    recibida.length === esperada.length &&
    crypto.timingSafeEqual(Buffer.from(recibida), Buffer.from(esperada))
  );
}

SECRET=yrlock_sk_...
BODY='{"keyId":"yrlock_3f9a1c0b7d2e4a6f8b0c1d2e"}'
TS=$(date +%s)
SIG=$(printf '%s.%s' "$TS" "$BODY" | openssl dgst -sha256 -hmac "$SECRET" -hex | sed 's/^.* //')

curl -X POST https://puente.hotel.mx/locks/ping \
  -H "Content-Type: application/json" \
  -H "X-YR-Lock-Key: yrlock_3f9a1c0b7d2e4a6f8b0c1d2e" \
  -H "X-YR-Lock-Timestamp: $TS" \
  -H "X-YR-Lock-Signature: sha256=$SIG" \
  --data-binary "$BODY"

{ "externalId": "K-889123" }

200 OK   · la llave ya no abre
204      · lo mismo, sin cuerpo
404      · cuenta como revocada: esa llave ya no existe en tu sistema

Revocar dos veces tiene que ser inofensivo. Un 404 lo leemos como éxito, no como error: si la llave no existe, desde luego no abre.

{ "keyId": "yrlock_3f9a1c0b7d2e4a6f8b0c1d2e" }

Contesta 200 solo si de verdad llegas al sistema de cerraduras. Un ping que siempre dice que sí deja al hotel creyendo que todo está bien hasta el primer check-in.

Cualquier respuesta fuera de 2xx —salvo el 404 de revoke— es un fallo. Si mandas un cuerpo JSON con «message» o «error», se lo enseñamos a recepción recortado a 200 caracteres. No incluyas datos personales ni secretos en ese texto.

{ "message": "cerradura 204 sin batería" }

• Check-in con fallo: el huésped entra igual y recepción ve el aviso LOCK_SYSTEM_ERROR. Reintenta con «Emitir llave» desde la reserva. Cada reintento lleva un reference nuevo; si tu sistema ya había emitido la anterior, quedará viva hasta su validUntil.
• Check-out con fallo: el huésped sale igual. La llave sigue marcada como activa hasta que recepción la revoque o llegue su validUntil, que es la hora de salida.
• Revocar a mano con fallo: te devolvemos el error. Recepción puede forzar la revocación, por ejemplo si la tarjeta se destruyó. En ese caso la apuntamos como revocada junto con el error de tu sistema, y la cerradura puede seguir abriendo hasta validUntil.
• Cambio de habitación: primero revocamos la llave vieja y después emitimos la nueva. Si la revocación falla, emitimos igual y avisamos.

Cuando tu sistema tenga su propio reintento hacia la cerradura —por ejemplo, un gateway sin red— contesta 2xx en cuanto aceptes la orden y resuélvela después. Nosotros solo necesitamos el externalId.

• Llamamos únicamente a URLs https que resuelvan a IPs públicas. Las privadas, loopback, link-local y CGNAT se rechazan también al conectar, no solo al guardar.
• El secreto se guarda cifrado con AES-256-GCM. Si sospechas una fuga, pide al hotel que lo rote.
• El PIN completo no se guarda en yaReserva: solo sus últimos cuatro dígitos, para que recepción lo reconozca sin poder volver a leerlo.