Empezar

yaReserva es el sistema con el que un hotel opera y vende. Esta API es la puerta para que otro programa haga una parte de ese trabajo: consultar qué hay libre y reservar desde el sitio web del propio hotel, cargar la cena del restaurante a la habitación, o emitir la llave digital al hacer check-in.

No es una API pública de catálogo: cada credencial pertenece a un hotel y a una propiedad suya, y solo ve lo de esa propiedad. El hotel la crea desde su panel y la puede apagar cuando quiera.

Hay dos ambientes y son dos mundos separados. Las credenciales de uno no sirven en el otro: una llave de pruebas en producción responde 401, y al revés también. El hotel pide las de prueba en su panel y con ellas recibe la URL base contra la que apuntar.

Guarda la URL base en tu configuración, nunca en el código. Pasar de pruebas a producción tiene que ser cambiar dos valores: la URL y el par de credenciales.

No hay tokens ni sesiones. Cada petición se firma por separado con el secreto de la conexión, y el secreto nunca viaja: lo que viaja es la firma, que es lo único que se puede calcular teniéndolo.

Cada integración tiene su terna de headers. Cambia el nombre, no la forma: llave pública, hora y firma.

1. 1Serializa el cuerpo a JSON y quédate con esos bytes exactos. A partir de aquí no lo vuelvas a formatear: un espacio de más cambia la firma.
2. 2Toma la hora actual en segundos Unix, en UTC. Ese número es el timestamp.
3. 3Arma la cadena a firmar concatenando el timestamp, un punto y el cuerpo: «timestamp + "." + cuerpo». En un GET el cuerpo es vacío, así que la cadena termina en el punto.
4. 4Calcula HMAC-SHA256 de esa cadena usando el secreto como llave, y pásalo a hexadecimal en minúsculas.
5. 5Manda los tres headers: la llave pública, el timestamp que usaste y la firma con el prefijo «sha256=».

X-YR-ENG-Key:       yreng_3f9a1c0b7d2e4a6f8b0c1d2e
X-YR-ENG-Timestamp: 1789459391
X-YR-ENG-Signature: sha256=9c1f0a7d4b2e6c8a1f3d5b7e9c0a2d4f6b8e0c2a4d6f8b0c2e4a6d8f0b2c4e6a

KEY=yreng_3f9a1c0b7d2e4a6f8b0c1d2e
SECRET=yreng_sk_...
BODY='{"offers":["eyJ2IjoxLCJyIjoi..."],"guest":{"firstName":"Ana","lastName":"Ruiz","email":"ana@correo.mx"},"acceptedTerms":true,"acceptedPrivacy":true}'
TS=$(date +%s)
SIG=$(printf '%s.%s' "$TS" "$BODY" | openssl dgst -sha256 -hmac "$SECRET" -hex | sed 's/^.* //')

curl -X POST https://api.yareserva.com/api/v1/engine/bookings \
  -H "Content-Type: application/json" \
  -H "X-YR-ENG-Key: $KEY" \
  -H "X-YR-ENG-Timestamp: $TS" \
  -H "X-YR-ENG-Signature: sha256=$SIG" \
  -H "X-Idempotency-Key: 8c2e1f04-5a6b-4c7d-8e9f-0a1b2c3d4e5f" \
  --data-binary "$BODY"

const crypto = require('crypto');

function firmar(payload, secret) {
  const body = JSON.stringify(payload);
  const ts = Math.floor(Date.now() / 1000).toString();
  const sig = crypto.createHmac('sha256', secret).update(`${ts}.${body}`).digest('hex');
  return { body, ts, sig: `sha256=${sig}` };
}

// Manda `body` tal cual, sin volver a serializar el objeto.

import hashlib, hmac, json, time

def firmar(payload, secret):
    body = json.dumps(payload, separators=(",", ":")).encode()
    ts = str(int(time.time()))
    sig = hmac.new(secret.encode(), ts.encode() + b"." + body, hashlib.sha256).hexdigest()
    return body, ts, "sha256=" + sig

Una firma válida sigue siendo válida para siempre si nadie mira la hora. Por eso la miramos: el timestamp que mandas no puede diferir del nuestro en más de cinco minutos. Fuera de ese margen la petición se rechaza aunque la firma esté bien.

• Sincroniza el reloj del servidor con NTP. El 401 más común no es una firma mal calculada, es un reloj atrasado.
• Genera un timestamp y una firma nuevos en cada reintento. Reenviar la petición completa tal cual falla en cuanto pasan cinco minutos.
• La hora va en segundos, no en milisegundos. Un valor en milisegundos queda miles de años en el futuro y se rechaza.

Una red que se corta no te dice si la petición llegó. Reintentar a ciegas es lo que duplica una reserva o cobra dos veces la misma cena. Por eso todo lo que crea algo lleva una llave de idempotencia.

X-Idempotency-Key: 8c2e1f04-5a6b-4c7d-8e9f-0a1b2c3d4e5f

• Genera la llave una vez, antes del primer intento, y reúsala en todos los reintentos de esa misma operación. Un UUID v4 sirve.
• La misma llave devuelve el mismo resultado: el recurso que ya se creó, no uno nuevo y no un error.
• La llave queda anotada junto al recurso que creó. Reusarla con datos distintos no crea nada nuevo ni da error: devuelve el primero. Si cambian los datos, cambia la llave.
• La llave admite letras, dígitos y . _ : - y cabe en 100 caracteres. Un UUID v4 sirve.
• La comprobación de la llave y la venta ocurren dentro de un lock, así que dos peticiones simultáneas con la misma llave no pueden crear dos recursos: se serializan.

Toda respuesta es JSON con la misma envoltura. Cuando salió bien viene «data»; cuando no, viene «error». Nunca los dos. «meta» aparece solo en las listas paginadas.

{
  "data": {
    "id": "5d0c3f1e-2b7a-4c1d-9e8f-0a1b2c3d4e5f",
    "totalCents": 372000,
    "currency": "MXN",
    "createdAt": "2026-11-20T21:03:11Z"
  },
  "meta": { "page": 1, "limit": 20, "total": 37 }
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "checkOut must be after checkIn",
    "details": { "field": "checkOut" }
  }
}

El código HTTP dice de qué tipo es el problema y «error.code» dice cuál exactamente. Programa contra el código, no contra el texto del mensaje: el mensaje está para leerlo una persona y puede cambiar.