Skip to main content

​
Vivla API

vivla-api es la API REST principal de VIVLA. Está construida con NestJS 11 (Node.js 22+) y sirve a la app móvil de copropietarios, al panel de CX y a calendar-manager. Aquí vive la lógica de negocio del producto: reservas, calendario, temporadas, llaves de intercambio y alquiler de semanas. Esta documentación describe el estado actual del código. Cada regla apunta a su archivo:línea en el repositorio para que puedas verificarla.
Este tab se escribe de forma nativa en el repo docs, no en vivla-api. El repositorio de la API no aloja su propia carpeta de documentación, así que la wiki la mantiene aparte.

​
Versionado por URI

La API versiona por URI. Cada ruta empieza por su versión: /v1/... o /v2/.... No hay prefijo global de API. El versionado se activa en src/main.ts:39 con VersioningType.URI.
No hay OpenAPI ni Swagger. El proyecto no expone ningún esquema autogenerado (no usa @nestjs/swagger). La única “spec” por endpoint son comentarios @reference que enlazan a páginas de Notion en las cabeceras de los controllers. No son navegables desde aquí y requieren acceso al workspace de Notion de VIVLA.

​
La dualidad v1 / v2

vivla-api convive con dos bases de datos a la vez. Entender cuál manda en cada dato es lo más importante de este backend.
Fuente de verdad de reservas y calendario. Las reservas, los slots del calendario, las temporadas por casa y los estados de las estancias viven en Firestore (Firebase). Los endpoints /v1/... leen y escriben aquí.El calendario de cada casa se guarda en config/{año}/{calendar_ref} con subcolecciones por temporada (src/bookings/calendars/v1/calendars.repository.ts:69).
v2 todavía depende de v1. Las tablas Postgres referencian las casas y usuarios de Firestore por sus IDs antiguos (oldHid, oldUid). Muchas operaciones de v2 (por ejemplo el coste en llaves de una casa) resuelven primero la casa en Firestore para encontrar su equivalente en Postgres. No es una migración cerrada: es una capa nueva montada sobre la vieja.

​
Módulos

La API se organiza en módulos NestJS (src/app.module.ts).
MóduloQué contiene
BookingsReservas: crear, cancelar, alquilar, intercambiar. v1 (Firestore) y v2 (experiencias + llaves).
CalendarsCalendario de cada casa, slots, temporadas, disponibilidad. Vive dentro de bookings/calendars.
HomesCasas y propiedades. Controllers v1/v2 + variantes admin y tools.
UsersUsuarios y perfiles. Controllers v1/v2 + variantes admin y tools.
AuthAutenticación y guard de permisos (PermissionGuard + @RequirePermission).
NotificationsEnvío de notificaciones (push / buzón Firestore).
InvitationsInvitaciones de asistentes a reservas.
ConfigurationTabla configurations (parámetros clave/valor).
ScheduledJobsCrons: caducidad de llaves, bono anual, refresco de caché, transfers.
Firestore / DatabaseConexión a Firestore (v1) y a Postgres/TypeORM (v2).
CommonFiltros de error, i18n, utilidades, entidades compartidas.

​
Por dónde seguir

Endpoints de reservas

Referencia de endpoints público/admin de v1 y v2, más los de calendario.

Reglas de reserva

Cada validación que impone el código, con su archivo:línea.

Calendario y temporadas

Enum de temporadas, fechas por casa, coste en llaves y check-in/out.

Llaves e intercambio

Wallet, caducidad, los dos motores de intercambio y ThirdHome.

Alquiler

Flujo de alquiler, estados, precio manual y Hostaway.

Crons y configuración

Tareas programadas, tabla configurations y variables de entorno.