Getting started

yaReserva is the system a hotel runs and sells with. This API is the door for another program to do part of that work: check what is available and book from the hotel’s own website, charge dinner at the restaurant to the room, or issue the digital key at check-in.

It is not a public catalogue API: every credential belongs to one hotel and to one of its properties, and only sees that property’s data. The hotel creates it from its panel and can switch it off at any time.

There are two environments and they are two separate worlds. Credentials from one do not work in the other: a test key in production answers 401, and the other way round too. The hotel asks for the test ones in its panel and gets the base URL to point at along with them.

Keep the base URL in your configuration, never in code. Going from test to production must be a matter of changing two values: the URL and the credential pair.

There are no tokens and no sessions. Every request is signed on its own with the connection’s secret, and the secret never travels: what travels is the signature, which is the only thing you can compute if you hold it.

Each integration has its own trio of headers. The name changes, the shape does not: public key, time and signature.

1. 1Serialize the body to JSON and keep those exact bytes. From here on do not reformat it: one extra space changes the signature.
2. 2Take the current time in Unix seconds, in UTC. That number is the timestamp.
3. 3Build the string to sign by joining the timestamp, a dot and the body: “timestamp + "." + body”. On a GET the body is empty, so the string ends at the dot.
4. 4Compute HMAC-SHA256 of that string using the secret as the key, and render it as lowercase hexadecimal.
5. 5Send the three headers: the public key, the timestamp you used, and the signature prefixed with “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

A valid signature stays valid forever if nobody looks at the clock. So we look: the timestamp you send cannot differ from ours by more than five minutes. Outside that window the request is rejected even if the signature is correct.

• Sync the server clock with NTP. The most common 401 is not a badly computed signature, it is a slow clock.
• Generate a fresh timestamp and signature on every retry. Resending the whole request as-is fails as soon as five minutes go by.
• The time goes in seconds, not milliseconds. A value in milliseconds lands thousands of years in the future and is rejected.

A dropped connection does not tell you whether the request arrived. Retrying blind is what duplicates a booking or charges the same dinner twice. That is why everything that creates something carries an idempotency key.

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

• Generate the key once, before the first attempt, and reuse it on every retry of that same operation. A UUID v4 will do.
• The same key returns the same result: the resource that was already created, not a new one and not an error.
• The key is recorded alongside the resource it created. Reusing it with different data creates nothing new and raises no error: it returns the first one. If the data changes, change the key.
• The key accepts letters, digits and . _ : - and fits in 100 characters. A UUID v4 will do.
• The key check and the sale happen inside a lock, so two simultaneous requests with the same key cannot create two resources: they are serialized.

Every response is JSON with the same envelope. When it went well you get “data”; when it did not, you get “error”. Never both. “meta” only shows up on paginated lists.

{
  "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" }
  }
}

The HTTP status says what kind of problem it is and “error.code” says exactly which one. Program against the code, not against the message text: the message is there for a person to read and may change.