API REST CECOM BRYSA

Esta sección documenta la API REST del sistema CECOM BRYSA. La API es mantenida por NFR Innovaciones Web SpA como parte del sistema desarrollado para BRYSA S.A.

Información General

Atributo	Valor
Base URL	https://api.cecom-brysa.cl/api
Versión	1.1.0
Formato	JSON
Autenticación	JWT Bearer Token
Multi-tenancy	Filtros por tenant y contrato según el rol autenticado

Arquitectura

graph LR
  subgraph Cliente["Clientes autorizados"]
      A[Frontend Web]
      B[Scripts internos]
      C[Integraciones externas]
  end

  subgraph API["Backend Express"]
      D[API REST]
      E[Rate Limiter]
      F[JWT + RBAC]
      G[Controladores]
  end

  subgraph Backend
      H[(PostgreSQL)]
      I[Redis Cache]
      J[WebSocket]
  end

  A --> D
  B --> D
  C --> D
  D --> E --> F --> G
  G --> H
  G --> I
  G --> J

Endpoints Principales

Módulo	Base Path	Descripción
Autenticación	/api/auth	Login, recuperación/cambio de contraseña, perfil y contexto
Usuarios	/api/users	Gestión de usuarios
Brigadistas	/api/brigadista	Personal y asistencia
Emergencias	/api/emergencies	Bitácora de emergencias
Recursos	/api/resource-panel	Vehículos y equipos
Dotación Manual	/api/manual-dotation	Dotación operativa de carros por turno
Combustible	/api/fuel	Registro de cargas
Inventario	/api/inventory	Control de materiales
Entrega Turno	/api/shift-handovers	Cambio de guardia
Pruebas de Comunicación	/api/communication-tests	Verificación de radios/estaciones
Ubicaciones	/api/locations	Puntos georreferenciados
SamTech	/api/samtech	Integración GPS/ubicaciones externas
Despacho	/api/dispatch-alerts	Alertas de emergencia
Datos Maestros	/api/master-data	Catálogos del sistema
Contratos	/api/contracts/:id/daytime	Corte horario Día/Noche del contrato
Tenants/Contratos	/api/tenants	Administración global de empresas y contratos

Formato de Respuestas

La API mantiene respuestas legacy y respuestas nuevas. Antes de integrar un endpoint, revise la referencia OpenAPI interna o la ruta específica. Los patrones más comunes son:

Respuesta Exitosa con status

{
  "status": "success",
  "message": "Operación exitosa",
  "data": {}
}

Respuesta Exitosa con success

{
  "success": true,
  "message": "Operación exitosa",
  "data": {
    // Datos de la respuesta
  }
}

Respuesta Paginada

{
  "success": true,
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 100,
    "totalPages": 5
  }
}

Respuesta de Error Legacy

{
  "success": false,
  "message": "Descripción del error",
  "errors": [
    {
      "field": "email",
      "message": "El email es requerido"
    }
  ]
}

Respuesta de Error por Código de Dominio

Algunos módulos nuevos, como manual-dotation, retornan errores con código estable:

{
  "error": {
    "code": "BRIGADISTA_ALREADY_ASSIGNED",
    "message": "El brigadista ya está asignado en la dotación abierta"
  }
}

Rate Limiting

La API implementa límites de tasa para proteger el servicio:

Endpoint	Límite	Ventana
General	1000 requests	15 minutos
Autenticación	100 requests	15 minutos
Login	5 intentos	5 minutos

Cuando excede el límite, recibirá:

HTTP/1.1 429 Too Many Requests

{
  "success": false,
  "message": "Demasiadas solicitudes. Intente en 15 minutos.",
  "retryAfter": 900
}

Headers Requeridos

Content-Type: application/json
Authorization: Bearer <token>

Seguridad

No guarde tokens JWT, secretos de integración ni credenciales en repositorios, tickets o capturas compartidas. Las integraciones deben usar variables de entorno y rotación de credenciales.

Referencia OpenAPI

La referencia oficial para producción está dentro de esta documentación:

• Producción: Referencia OpenAPI
• Desarrollo local: http://localhost:3001/api-docs

El endpoint público https://api.cecom-brysa.cl/api-docs no se usa como fuente documental en producción. El backend solo monta Swagger UI cuando ENABLE_SWAGGER_IN_PRODUCTION=true; por seguridad, el flujo normal es consultar esta documentación y usar Swagger en local o en un entorno interno controlado.

Siguientes Pasos

• Autenticación - Cómo obtener y usar tokens
• Errores - Códigos y manejo de errores
• Ejemplos - Ejemplos de código

---

Acceso a la API

Para obtener credenciales de API para integraciones, contacte a contacto@nfr-innovacionesweb.cl