Disponibilidad y calendario

Cómo decide el producto qué noches están libres, cómo las muestran el calendario del sitio web y el del panel, las fechas bloqueadas, las retenciones y la zona horaria de la empresa.

Para el paquete Full Stack

Noches, no días

Cada reserva y cada rango bloqueado ocupa el intervalo semiabierto [check-in, check-out): el día de check-in está ocupado, el día de check-out está libre. Un huésped que se va el día 10 libera el 10 para la siguiente llegada, y una reserva de tres noches cubre tres noches.

Un único servicio de la API responde qué noches están libres, a partir de las reservas que retienen noches más los rangos bloqueados. El calendario del sitio web, la tarjeta de reserva, el pago, el calendario del panel y el asistente de IA lo consultan, así que no pueden discrepar.
Las reservas pendientes, confirmadas, con check-in realizado y completadas retienen sus noches. Una reserva cancelada no retiene nada, así que nunca se interpone en una nueva.
Cada fecha es un día de calendario en la zona horaria de la empresa, el ajuste timezone (America/New_York), escrito YYYY-MM-DD, nunca un instante. Eso es lo que significa "hoy" para las llegadas, el calendario, el plazo de cancelación y las retenciones, a ambos lados de un cambio de horario de verano.

Lo que acepta un alojamiento

Rechazo	Cuándo	La API dice
`past`	El día de check-in ya pasó	"Elige una fecha de check-in que no haya pasado."
`min_nights`	Menos noches que el mínimo del alojamiento	"Este alojamiento tiene un número mínimo de noches."
`capacity`	Más huéspedes de los que aloja el alojamiento	"Este alojamiento no aloja a tantos huéspedes."
`taken`	Una reserva o un bloqueo ya retiene una de las noches	"Esas noches ya están ocupadas."

La cotización y el pago comprueban las mismas cuatro, y el pago las comprueba de nuevo cuando se escribe la reserva, así que dos huéspedes nunca pueden pagar la misma noche.

Retenciones

Una reserva con tarjeta o PayPal retiene sus noches desde el momento en que se hace, antes de enviar al huésped al procesador, durante 30 minutos. Si el pago no se ha liquidado para entonces, un barrido que se ejecuta cada minuto cancela la reserva y libera las noches.
Una reserva con pago a la llegada que espera al anfitrión no tiene retención: conserva sus noches hasta que el anfitrión la confirme o la cancele.
Una reserva pagada retiene sus noches hasta que se cancela.

El calendario del sitio web

La página del alojamiento muestra dos meses y marca cinco estados, cada uno con su propia muestra en la leyenda:

Estado	Significado
Disponible	Libre para elegir
No disponible	En el pasado, o un check-out que caería dentro del mínimo del alojamiento
Ocupado	Retenido por una reserva o un bloqueo, tachado
Seleccionado	El check-in y el check-out elegidos
En el rango	Las noches entre ellos, con un relleno más claro que una noche ocupada

La tarjeta de reserva junto a él calcula el precio de las noches elegidas en cuanto se escogen los dos días.

El calendario del panel

/en/dashboard/calendar muestra un mes de noches, una fila por alojamiento. La barra de una reserva cubre sus noches, se detiene antes del día de check-out y abre los detalles de la reserva.
El diálogo de fechas bloqueadas retira las noches de un alojamiento del calendario, desde una primera noche hasta un día de check-out, con un motivo (Mantenimiento, Uso de la empresa u Otro) y una nota opcional. Se rechaza cuando una reserva u otro bloqueo ya retiene una de esas noches, y el diálogo la nombra: "La reserva B0021 ya retiene algunas de estas noches. Elige otras fechas.", o lo mismo para un bloqueo como K003.
Los campos de fecha conservan el día que eliges sea cual sea la zona horaria del equipo, así que un bloqueo o un filtro nunca cae en el día anterior.
Cada bloqueo aparece listado bajo el calendario, el más próximo primero, para editarlo o quitarlo.
Si un alojamiento también está publicado en otro sitio, bloquea a mano las noches reservadas allí: el producto no tiene gestor de canales ni importación o exportación de iCal.

Quién puede hacer qué

Permiso	Permite
`calendar.view`	Ver el mes y los bloqueos
`calendar.block`	Añadir, cambiar y quitar bloqueos

Los dos roles de la carga inicial, Super Admin y Manager, tienen ambos.

Las rutas que hay detrás

GET /api/stays/:slug/availability?from=&to= responde las noches ocupadas de un alojamiento publicado durante 92 días como máximo cada vez, y GET /api/stays/:slug/quote?checkIn=&checkOut=&guests= sus noches, subtotal, tarifa de limpieza y total, con available y el motivo del rechazo.
GET /api/calendar?month=YYYY-MM&stay= es la vista mensual del panel.
/api/availability/blocks lista, añade (stay_id, from, to, reason y note opcionales), cambia y quita bloqueos. Un conflicto responde 409 con code: "dates_taken", details: { "held_by": "booking", "reference": "B0021" } (o "block" y una referencia K) y el message traducido "La reserva B0021 ya retiene algunas de estas noches."

Referencia de la API