POS de restaurante

El POS sigue cobrando todo lo demás como siempre: efectivo, tarjeta, transferencia. Solo cambia una cosa. Cuando el mesero cierra una cuenta «a la habitación», el POS nos manda el cargo, entra al folio de la estancia del huésped y se paga al hacer check-out.

Sirve para Soft Restaurant, Parrot, Loyverse o cualquier otro punto de venta que pueda hacer una llamada HTTP firmada al cerrar la cuenta.

• Son tres llamadas: buscar al huésped de una habitación, cargar, y anular si el mesero se equivocó.
• Los importes viajan en centavos y en la moneda de la reserva.
• El folio del ticket es la llave de idempotencia. Reintentar con el mismo folio no cobra dos veces.

El hotel crea la conexión en su panel, en Configuración → POS del restaurante, y recibe una sola vez el par de credenciales.

Cada conexión pertenece a una propiedad: solo ve y carga a las estancias de esa propiedad. El hotel puede limitar el importe máximo por cargo, apagar los cargos, rotar el secreto —el anterior deja de valer en el acto— o revocar la conexión entera.

https://api.yareserva.com/api/v1/webhooks/pos

X-YR-POS-Key:       <keyId>
X-YR-POS-Timestamp: <segundos Unix, UTC>
X-YR-POS-Signature: sha256=<hex(HMAC-SHA256(secret, timestamp + "." + cuerpo))>

• El cuerpo son los bytes exactos que envías. Firma después de serializar el JSON y no lo reformatees.
• En los GET el cuerpo es vacío: se firma «timestamp + "."», o sea la cadena termina en el punto.
• La hora del POS puede diferir de la nuestra como mucho cinco minutos. Fuera de ese margen la petición se rechaza; sincroniza el reloj con NTP.
• Cualquier fallo —llave desconocida o revocada, firma incorrecta, hora fuera de margen— responde 401 INVALID_SIGNATURE y no se procesa nada.
• El cuerpo no puede pasar de 64 KB, y hay un tope de 300 peticiones por minuto por IP.

KEY=yrpos_3f9a1c0b7d2e4a6f8b0c1d2e
SECRET=yrpos_sk_...
BODY='{"externalId":"TK-000123","roomNumber":"204","amountCents":45000,"description":"Cena mesa 7"}'
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/webhooks/pos/charges \
  -H "Content-Type: application/json" \
  -H "X-YR-POS-Key: $KEY" \
  -H "X-YR-POS-Timestamp: $TS" \
  -H "X-YR-POS-Signature: sha256=$SIG" \
  --data-binary "$BODY"

const crypto = require('crypto');

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

// headers: X-YR-POS-Key, X-YR-POS-Timestamp: ts, X-YR-POS-Signature: `sha256=${sig}`

import hashlib, hmac, json, time

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

• Reintenta con el mismo externalId ante cualquier error de red, timeout o 5xx. Si el cargo ya había entrado, recibes 200 con «duplicate»: true y el mismo chargeId: no se carga dos veces.
• El registro del cargo y el movimiento del folio se escriben en la misma transacción. Dos reintentos a la vez no pueden duplicar el cargo.
• Genera un timestamp y una firma nuevos en cada reintento: la firma vieja caduca a los cinco minutos.
• No reintentes un 4xx sin corregir la petición. La excepción es el 429, que se reintenta respetando Retry-After.
• Anular es seguro de repetir: la segunda vez responde 409 CHARGE_ALREADY_VOIDED, que para ti es lo mismo que haber salido bien.