Endpoints de reservas

Referencia de la superficie de reservas de vivla-api. Las rutas incluyen su versión (/v1/..., /v2/...); no hay prefijo global. Las rutas de calendario comparten prefijo con reservas (bookings y admin/bookings).

La columna Acceso distingue endpoints de la app del copropietario (usuario autenticado) de los de panel (protegidos por PermissionGuard + @RequirePermission(...)). El permiso exacto se indica entre paréntesis.

Público v1 — app del copropietario

src/bookings/v1/bookings.controller.ts · path bookings, versión 1.

Método	Ruta	Qué hace
GET	`/v1/bookings/mine`	Reservas del usuario autenticado (filtro `status` por query).
GET	`/v1/bookings/to-rent`	Reservas publicadas para alquilar dentro de la red.
GET	`/v1/bookings/to-exchange`	Reservas publicadas para intercambio.
GET	`/v1/bookings/:id`	Detalle de una reserva.
PUT	`/v1/bookings/update-info/:id`	Actualiza información de la reserva (huéspedes, notas, extras).
PUT	`/v1/bookings/update/:id`	Cambia el tipo de reserva (disfrute / intercambio / alquiler).
DELETE	`/v1/bookings/cancel/:id`	Cancela la reserva (o anula la invitación si eres invitado).
GET	`/v1/bookings/available-stays/:id`	Estancias disponibles del usuario en esa casa, por temporada.
POST	`/v1/bookings/book/:id`	Crea una reserva de disfrute.
POST	`/v1/bookings/rent/:id`	Solicita el alquiler de una reserva publicada.
POST	`/v1/bookings/exchange/:id`	Solicita el intercambio de una reserva publicada (gasta llaves).
POST	`/v1/bookings/exchange-last-hour`	Intercambio de última hora sobre un slot disponible (`home`, `stay`, `info`).
POST	`/v1/bookings/:id/stay-review`	Registra el NPS de la estancia.
POST	`/v1/bookings/:id/arrival-review`	Registra el NPS de calidad a la llegada.

Público v2 — experiencias y wallet de llaves

src/bookings/v2/bookings.controller.ts · path bookings, versión 2.

Método	Ruta	Qué hace
GET	`/v2/bookings/experiences/:location`	Experiencias por ubicación (localizadas por idioma).
GET	`/v2/bookings/:booking/experiences`	Experiencias asociadas a una reserva.
POST	`/v2/bookings/register-experience`	Registra (selecciona) una experiencia.
DELETE	`/v2/bookings/remove-experience`	Deselecciona una experiencia.
GET	`/v2/bookings/keys/my-wallet`	Monedero de llaves propio (saldo).
GET	`/v2/bookings/keys/my-movements`	Movimientos de llaves propios (paginado por `page`).
GET	`/v2/bookings/available-stays/:id`	Estancias disponibles (versión v2).

Admin v1 — panel CX

src/bookings/v1/bookings-admin.controller.ts · path admin/bookings, versión 1. Todos bajo PermissionGuard.

Método	Ruta	Acceso	Qué hace
GET	`/v1/admin/bookings/pending-exchanges`	`read:exchanges`	Reservas pendientes de intercambio.
DELETE	`/v1/admin/bookings/delete-test-bookings`	`admin`	Borra reservas de prueba.
POST	`/v1/admin/bookings/transfer/:homeId`	`admin`	Ejecuta la transferencia de reservas de una casa.
GET	`/v1/admin/bookings`	`read:bookings`	Listado con filtros (`status`, `type`, `home`, `from`, `to`, `user`, `gm`, `location`, paginado).
GET	`/v1/admin/bookings/:id`	`read:bookings`	Detalle de una reserva.
PUT	`/v1/admin/bookings/:id`	`edit:bookings`	Modifica una reserva.
POST	`/v1/admin/bookings/:id/publish-third-home`	`edit:bookings`	Publica la reserva en ThirdHome.
PUT	`/v1/admin/bookings/:id/unpublish-third-home`	`edit:bookings`	Retira la publicación de ThirdHome.
PUT	`/v1/admin/bookings/:id/exchange-third-home`	`edit:bookings`	Marca la reserva como intercambiada en ThirdHome (requiere asistente).
PUT	`/v1/admin/bookings/:id/change-type`	`edit:bookings`	Cambia el tipo de reserva.
DELETE	`/v1/admin/bookings/:id/liberate`	`edit:bookings`	Retira asistentes y libera la reserva.
POST	`/v1/admin/bookings/:id/rent`	`edit:bookings`	Alquila la reserva con precio manual (`price`, `assistant`).
PUT	`/v1/admin/bookings/:id/rent/approve`	`edit:bookings`	Aprueba o rechaza el alquiler (`approve` por query).
POST	`/v1/admin/bookings/:id/exchange`	`edit:bookings`	Intercambia la reserva a nombre de un usuario.
DELETE	`/v1/admin/bookings/:id/cancel`	`edit:bookings`	Cancela la reserva.
POST	`/v1/admin/bookings/register`	`edit:bookings`	Registra una reserva manualmente.

Fijar o editar fechas y notas de un alquiler o intercambio. Tanto al registrar una estancia (addStay) como al modificar su check-in/check-out o sus notas en una reserva de tipo alquiler (RENT) o intercambio (EXCHANGE), la estancia no vive solo en la reserva origen sino también en su reserva contraparte (el booking del inquilino/huésped, referencia rent_book / stayBook), que es de donde el cron de importación (bookings:import) vuelve a leer los datos. En concreto, el import lee las notas de la estancia de alquiler/intercambio desde book_notes del contraparte, no desde guest_notes del origen. Por eso el código escribe las fechas de entrada/salida y las notas en ambos documentos de Firestore; si las fechas o las notas solo se guardaran en la reserva origen, la siguiente importación no las encontraría, las sustituiría por sus valores previos (o, en las fechas, por la hora por defecto default_check_in_<HomeType> / default_check_out_<HomeType>) y revertiría el cambio (src/bookings/v2/bookings.common.repository.ts:724, método addStay; :1876, método editStay).

Admin v2 — llaves

src/bookings/v2/bookings-admin.controller.ts · path admin/bookings, versión 2. Todos bajo PermissionGuard.

Método	Ruta	Acceso	Qué hace
POST	`/v2/admin/bookings/keys/:userId/add-referral-bonus`	`edit:exchanges`	Añade el bono de referido (+2 llaves).
POST	`/v2/admin/bookings/keys/:userId/register-movement`	`edit:exchanges`	Registra un movimiento manual de llaves.
PUT	`/v2/admin/bookings/keys/transfer`	`edit:exchanges`	Traspasa llaves entre usuarios (`from`, `to`, `amount`).
GET	`/v2/admin/bookings/keys/movements`	`read:exchanges`	Listado de movimientos (filtros y paginación).
GET	`/v2/admin/bookings/keys/wallets`	`read:exchanges`	Listado de monederos.
GET	`/v2/admin/bookings/keys/user-wallet/:userId`	`read:exchanges`	Monedero de un usuario.
GET	`/v2/admin/bookings/keys/charts`	`read:exchanges`	Datos para gráficas (`period`).
GET	`/v2/admin/bookings/keys/metrics`	`read:exchanges`	Métricas de llaves (`from`, `to`).
GET	`/v2/admin/bookings/keys/homes`	`read:exchanges`	Coste en llaves de las casas (filtros).
GET	`/v2/admin/bookings/keys/home/:homeId`	`read:exchanges`	Fechas con coste en llaves de una casa.
POST	`/v2/admin/bookings/keys/home/:homeId/set`	`edit:exchanges`	Fija el coste en llaves de una casa+temporada (`season`, `keys`).

Calendario

Público en src/bookings/calendars/v1/calendars.controller.ts; admin en calendars-admin.controller.ts. Comparten prefijo con reservas.

Método	Ruta	Acceso	Qué hace
GET	`/v1/bookings/home-calendar/:id`	App	Calendario de una casa (slots con disponibilidad, temporada y coste).
PUT	`/v1/admin/bookings/slots/update`	`edit:calendars`	Modifica un slot.
DELETE	`/v1/admin/bookings/slots/delete`	`edit:calendars`	Elimina un slot.
POST	`/v1/admin/bookings/slots/create`	`edit:calendars`	Crea un slot.
POST	`/v1/admin/bookings/slots/duplicate-year`	`edit:calendars`	Duplica los slots de un año a otro (`year`, `calendarRef`).
GET	`/v1/admin/bookings/calendars`	`read:bookings`	Calendarios de reservas con filtros (`homes`, `from`, `to`, `location`, paginado).

Overview

Reservas

Llaves y alquiler

Operación

Endpoints de reservas

Endpoints de reservas

Público v1 — app del copropietario

Público v2 — experiencias y wallet de llaves

Admin v1 — panel CX

Admin v2 — llaves

Calendario

​Endpoints de reservas

​Público v1 — app del copropietario

​Público v2 — experiencias y wallet de llaves

​Admin v1 — panel CX

​Admin v2 — llaves

​Calendario

Endpoints de reservas

Público v1 — app del copropietario

Público v2 — experiencias y wallet de llaves

Admin v1 — panel CX

Admin v2 — llaves

Calendario