Referencia de API
Cómo está organizada la API REST de ixiclinic, su autenticación por Bearer JWT, los servidores y dónde vive la documentación OpenAPI interactiva (Scalar).
El backend de ixiclinic es una API REST construida con Fastify 5,
Drizzle ORM sobre PostgreSQL y validación con Zod 4.
Todo el ensamblado del servidor (plugins, seguridad y registro de rutas) vive en
apps/api/src/app.ts.
Organización de la API
La API sigue un patrón modular por dominio. Cada módulo en apps/api/src/modules/<dominio>/
agrupa cuatro archivos:
| Archivo | Responsabilidad |
|---|---|
routes.ts | Registro de rutas en Fastify (define el prefijo /api/... y los guards) |
handlers.ts | Manejo de la petición, validación de entrada y formato de respuesta |
service.ts | Lógica de negocio y consultas a la base de datos |
schemas.ts | Esquemas de validación Zod |
Cada routes.ts se registra como un plugin de Fastify en buildApp()
(apps/api/src/app.ts). El orden de plugins de la app es:
swagger → multipart → cors → helmet → rateLimit → errorHandler → auth → tenantScope → scalar → scheduler → rutas.
Nota: La taxonomía completa de módulos y los flujos de cada uno se documentan en Arquitectura. Para el listado de familias de rutas, ve a Endpoints.
Autenticación: Bearer JWT
Las rutas protegidas esperan un JWT de acceso en la cabecera estándar:
Authorization: Bearer <access-token>La especificación OpenAPI declara este esquema como bearerAuth
(type: http, scheme: bearer, bearerFormat: JWT) en la config de
@fastify/swagger dentro de apps/api/src/app.ts.
En las aplicaciones web (admin, console, portal) el token no se manipula desde el
navegador: se guarda en cookies httpOnly y las peticiones salen desde server actions
de Next.js que inyectan la cabecera Authorization del lado del servidor. El refresco
automático ante un 401 también ocurre en el servidor. Los detalles de los tres flujos de
auth (staff, superadmin SaaS y cliente del portal), las cookies con prefijo y el RBAC por
módulo están en Autenticación.
Servidores
La especificación OpenAPI declara dos servidores (apps/api/src/app.ts):
| Entorno | URL base |
|---|---|
| Producción | https://api.ixiclinic.com |
| Desarrollo | http://localhost:5000 (puerto configurable vía PORT) |
Documentación OpenAPI interactiva (Scalar)
@fastify/swagger genera la especificación OpenAPI a partir de los esquemas de cada ruta, y
Scalar la sirve como UI interactiva (playground para probar
endpoints) bajo la ruta /docs del API:
| Entorno | URL del playground |
|---|---|
| Producción | https://api.ixiclinic.com/docs |
| Desarrollo | http://localhost:5000/docs |
La ruta /docs es pública (no requiere token), igual que /api/health. El resto de
endpoints aplica el flujo de autenticación descrito arriba.
Siguiente: Endpoints.
Dominios del esquema
Recorrido por los 25 archivos de apps/api/src/db/schema, con las tablas clave de cada dominio y los detalles de catalog, billing, saas y tenants.
Endpoints
Página puente a la referencia OpenAPI del API. El playground interactivo Scalar y un resumen de las grandes familias de rutas REST.