Referencia API REST

Convenciones

Seguridad y llamadas desde el frontend

El SPA (src/Web) nunca almacena credenciales de base de datos ni claves de mapas. Toda operación protegida pasa por la API con JWT emitido tras login exitoso.

Flujo de autenticación

1. POST /api/auth/login con usuario y clave → respuesta incluye token (JWT firmado en servidor).
2. El cliente guarda el token en localStorage bajo la clave gotruck_token (auth.ts).
3. Las funciones fetchJson y sendJson añaden automáticamente Authorization: Bearer … si hay token.
4. Ante 401, el cliente borra el token y lanza SessionExpiredError para redirigir al login.
5. POST /api/auth/register crea cuenta en estado Pendiente sin devolver JWT; un administrador debe habilitarla.

JWT (servidor)

El frontend decodifica el payload solo para UI (p. ej. readIsAdminFromToken()); la autorización real la valida la API en cada request.

Buenas prácticas implementadas

• Mismo origen en producción: nginx sirve el SPA y hace proxy de /api/* al contenedor API (el navegador no expone otro host).
• CORS restrictivo en API: orígenes explícitos (localhost Vite/nginx) en desarrollo.
• Login genérico: credenciales inválidas → 401 con mensaje único (Credenciales inválidas.).
• BCrypt para hash de contraseñas en dbo.Usuarios.
• [AdminOnly] en UsuariosController: exige claim admin=true.
• Health anónimo solo para probes; no expone datos sensibles.

Ejemplo (cliente)

// auth.ts — petición autenticada
const token = localStorage.getItem("gotruck_token");
const res = await fetch("/api/catalogs/customers", {
  headers: {
    Accept: "application/json",
    ...(token ? { Authorization: `Bearer ${token}` } : {}),
  },
});

Parámetros de consulta compartidos

Usados en reportes, tableros y mapas (ReporteFiltrosQuery):

Mapas adicionales:

Autenticación — /api/auth

Salud — /api/health

Dashboard — /api/dashboard

Catálogos — /api/catalogs

Lectura de maestros I_* y catálogos dinámicos para filtros. Todos requieren JWT.

Repartidores (drivers)

Hojas para filtros de reportes

Canales y categorías

GET /api/catalogs/channels · GET /api/catalogs/customer-categories → CatalogoItemDto[]

Productos (artículos)

Hojas de ruta

Clientes

Reportes — /api/reports

Todos usan ReporteFiltrosQuery y devuelven ReporteFilaDto[].

• GET /api/reports/delivery-by-sheet
• GET /api/reports/returns-by-sheet
• GET /api/reports/collections-by-sheet
• GET /api/reports/collections-summary
• GET /api/reports/performance
• GET /api/reports/delivery-statistics (acepta canalId)

Tableros — /api/boards

Mapas — /api/maps

GET /api/maps/delivery/activities → MapaActividadDetalleDto[] (metadatos por visita para leyenda y orden)

GET /api/maps/delivery/visit/{visitId} → MapaVisitaDetalleDto (entrega, cobranza, ítems, pagos)

Configuración — /api/settings

Usuarios — /api/users Admin

Requiere JWT con claim admin=true.

• GET /api/users → UsuarioListItemDto[]
• GET /api/users/{id} → UsuarioDetalleDto
• POST /api/users — cuerpo CrearUsuarioRequest → CrearUsuarioResponse (puede incluir claveGenerada)
• PUT /api/users/{id} — ActualizarUsuarioRequest
• POST /api/users/{id}/enable · POST /api/users/{id}/disable
• DELETE /api/users/{id} → 204

Endpoints legacy (alias)

Misma implementación que catálogos, rutas alternativas:

• GET /api/customers
• GET /api/drivers
• GET /api/delivery-sheets → HojaRepartoDto[] (métricas agregadas por hoja)

Errores