Reservas

Una reserva es una estadía, en una unidad, por un rango de
fechas.

Toda reserva:

• apunta a una sola unidad de una sola propiedad;
• lleva o un plan tarifario o una
  tarifa personalizada
  — nunca las dos, nunca ninguna;
• está atada a un huésped;
• opcionalmente queda fijada a una habitación física concreta, cuando la unidad
  es un room type con inventario;
• congela su desglose de precio al crearse.

El ciclo de vida

pending → confirmed → checked_in → checked_out
   └──────────┴────────────┘
          cancelled

cancelled se alcanza desde cualquier estado no terminal y es terminal en sí
mismo. No existe el borrado. Una reserva sale del conjunto activo al
cancelarse; nada elimina el registro, porque el código ya se entregó y la
historia es justamente el punto.

checked_in significa la llegada física, registrada por recepción cuando el
huésped está ahí parado. Nada más lo pone — completar un
check-in digital no lo hace, y nunca lo
hará.

El código

CDB-000001 — el prefijo
de la propiedad y un contador que corre por propiedad, no por cuenta. Es la
referencia que usan tanto el hotel como el huésped.

Como el prefijo no es único globalmente y el contador es secuencial, un código de
reserva es adivinable y no es una credencial. Cualquier cosa que necesite
autorizar acceso a una reserva usa un token opaco en su lugar.

El precio se congela al crear

El desglose se fotografía cuando se hace la reserva — no se recalcula al leer.
Un cambio de tarifa mañana no reescribe lo que un huésped aceptó hoy.

Una edición que afecte el precio lo vuelve a fotografiar. Eso incluye cambiar
fechas, unidad, plan tarifario u ocupación. Editar notas no.

Una edición sobre una unidad que no administra su propio inventario por
habitación vuelve a correr la guarda de disponibilidad, así que acortar un
horizonte de reserva puede volver ineditable una estadía ya vendida si no se
fuerza. force es la válvula de escape, y registra un conflicto en vez de
bloquear al operador.

Campos que significan menos de lo que parecen

total_price es el precio bruto de la habitación — incluida cualquier parte
que esté pagando alguien que no es el huésped.

paid_amount cuenta los pagos hechos contra esta reserva. Una empresa que
liquida la habitación por la cuenta de un grupo nunca
aparece acá, así que puede quedarse en 0.00 en una habitación totalmente
saldada.

balance_due es lo que todavía debe el huésped de esta reserva, y es el
único saldo correcto. Ya excluye todo lo facturado a un tercero.

No hay que derivar un saldo como total_price − paid_amount. No son un
par que case: la resta le cobra al huésped la habitación completa mientras le
acredita solo lo que se pagó directamente contra ella. Exagera lo que debe, sin
error alguno y sin ningún campo faltante que avise.

En una reserva creada por la External API y no tocada después, balance_due
sí es igual a total_price — esa API no toma pagos. La igualdad deja de
valer en el momento en que el hotel mete la habitación en un grupo y factura
parte en otro lado, cosa que puede hacer en cualquier momento después de la
creación.

sales_channel registra de dónde vino la venta. Es un hecho sobre la venta,
no un permiso que haya que volver a revisar después — hacerlo valer en el camino
de edición volvió, en su momento, ineditable toda reserva originada en un canal o
en la API.

Varias habitaciones a la vez

Dos cosas distintas se parecen de familia y no hay que confundirlas:

• quantity > 1 en un room type crea N reservas independientes que comparten
  un reservation_group_id. Cada una tiene su código, su habitación y su propio
  ciclo de pago; están agrupadas para mostrarse, no para facturarse.
• Un grupo de reservas es un bloque que un
  merchant armó deliberadamente, con su propio código, un titular comercial,
  acciones masivas y — opcionalmente — facturación a empresa.

Los dos recursos de reserva llevan group (anulable) junto al incondicional
reservation_group_id.

En la API

• Merchant: POST /api/merchant/bookings para crear,
  POST /bookings/quote para previsualizar precio y disponibilidad sin
  escribir, PATCH /bookings/{id}/status para las transiciones,
  /bookings/{id}/payments para el dinero, /bookings/{id}/activities para el
  historial de cambios.
• External: POST /bookings — una habitación por
  llamada, creada pending y sin pagar. Se requiere un Idempotency-Key;
  ver Idempotencia.
  GET /bookings devuelve los datos de contacto del
  huésped, así que la respuesta hay que tratarla como datos personales.

Relacionado

• Disponibilidad y overbooking — si la estadía cabe.
• Folios y cargos — lo que debe la estadía, línea por línea.
• Pagos y saldo — lo que ha pagado.