API REST

Cómo está organizada la API de Valwisp, su autenticación Bearer JWT, versión, servidores y la documentación OpenAPI interactiva (Scalar).

El backend de Valwisp es una API REST construida con NestJS 10, Prisma ORM sobre PostgreSQL. Todo el ensamblado del servidor (interceptores globales, guards, Scalar) vive en apps/valwisp-api/src/main.ts.

Organización

La API sigue un patrón modular por dominio — 49 módulos en apps/valwisp-api/src/modules/<dominio>/, cada uno con controller/service/dto/module (ver Convenciones).

Versión y prefijo

Versionado por URI: todas las rutas cuelgan de /api/v1/... (app.enableVersioning(VersioningType.URI) + app.setGlobalPrefix('api') en main.ts). La spec OpenAPI reporta versión 1.0.

Autenticación: Bearer JWT

Authorization: Bearer <access-token>

Declarado en la spec OpenAPI como bearerAuth (type: http, scheme: bearer, bearerFormat: JWT). El detalle completo del flujo de login/refresh y los 3 guards globales está en Autenticación.

Servidores

Entorno	URL base
Producción	`https://api.valwisp.com`
Desarrollo	`http://localhost:3000` (puerto vía `PORT`)

Documentación OpenAPI interactiva (Scalar)

@nestjs/swagger genera la spec OpenAPI escaneando todos los controllers registrados; Scalar la sirve como UI interactiva en /docs — disponible en todos los entornos, no solo desarrollo:

Entorno	Playground
Producción	`https://api.valwisp.com/docs`
Desarrollo	`http://localhost:3000/docs`

El tema de Scalar usa el acento teal de marca (#33B4A8) — el mismo que este sitio de documentación.

Exportar la especificación a un archivo

GET /openapi.json

Fuera del prefijo /api (registrado directo en la instancia Express). Útil para Postman, Insomnia o generadores de clientes sin levantar el playground.

Siguiente: Endpoints.