Door locks

yaReserva does not run locks. What it does is notify the hotel’s bridge at three moments, and the bridge talks to Salto KS, TTLock, Dormakaba/Saflok, Assa Abloy Vostio or whichever system is installed.

The front desk can also issue an extra key or revoke one from the booking screen.

The hotel creates the connection in its panel, under Settings → Locks. It picks a property, the “Webhook bridge” type and your bridge’s base URL, which must be https and resolve to a public IP. There it receives, once and only once, the credential pair.

Next, the hotel maps each room to the id of its lock in the provider’s system, the “lockId”. That is what we send you so you know which door to open.

All three calls are POST with Content-Type: application/json to your base URL plus a path. They all carry the same 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. 1Look up the secret by X-YR-Lock-Key.
2. 2Reject if the timestamp differs from your clock by more than five minutes. Sync with NTP.
3. 3Compute the HMAC over the exact bytes of the body you received, without re-serializing the JSON, and compare in constant time.
4. 4Answer 401 if anything is off, without processing anything.

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

Revoking twice must be harmless. We read a 404 as success, not as an error: if the key does not exist, it certainly does not open.

{ "keyId": "yrlock_3f9a1c0b7d2e4a6f8b0c1d2e" }

Answer 200 only if you genuinely reach the lock system. A ping that always says yes leaves the hotel believing everything is fine until the first check-in.

Any response outside 2xx — except the 404 on revoke — is a failure. If you send a JSON body with “message” or “error”, we show it to the front desk trimmed to 200 characters. Do not put personal data or secrets in that text.

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

• Failed check-in: the guest goes in anyway and the front desk sees the LOCK_SYSTEM_ERROR warning. It retries with “Issue key” from the booking. Each retry carries a fresh reference; if your system had already issued the previous one, it stays alive until its validUntil.
• Failed check-out: the guest leaves anyway. The key stays marked active until the front desk revokes it or its validUntil arrives, which is check-out time.
• Failed manual revoke: we hand the error back. The front desk can force the revocation, for instance if the card was destroyed. In that case we note it as revoked alongside your system’s error, and the lock may keep opening until validUntil.
• Room move: we revoke the old key first and then issue the new one. If the revocation fails, we issue anyway and warn.

When your system has its own retry towards the lock — a gateway with no network, say — answer 2xx as soon as you accept the order and resolve it afterwards. All we need is the externalId.

• We only call https URLs that resolve to public IPs. Private, loopback, link-local and CGNAT addresses are rejected at connection time too, not just when saving.
• The secret is stored encrypted with AES-256-GCM. If you suspect a leak, ask the hotel to rotate it.
• The full PIN is not stored in yaReserva: only its last four digits, so the front desk can recognize it without being able to read it again.