Referencia de API REST

Referencia completa de la API REST de Certexi incluyendo autenticación, endpoints WHMS, operaciones de flujo de trabajo, integraciones IoT y rutas de gobernanza.

Última actualización: 2025-02-18

Referencia de API REST

Certexi expone una API REST integral a través de rutas API de Next.js. Todos los endpoints retornan JSON y siguen patrones de manejo de errores consistentes.

ℹ️

Especificación OpenAPI

La referencia canónica legible por máquina es GET /api/openapi. Úsala para generación de código, Swagger UI o Postman. Para regenerar la lista completa de rutas API desde el código fuente, ejecuta npm run docs:generate-api-list.

Autenticación

Todas las solicitudes API (excepto /api/health y /api/ping) requieren autenticación vía headers:

Authorization: Bearer <token> | Basic <credentials>
X-NextCloud-Instance: <nextcloud_url>
X-NextCloud-Username: <username>

La API soporta tanto tokens OAuth Bearer como autenticación por App Password de Nextcloud con fallback automático.

⚠️

Límites de Tasa

Los endpoints API tienen límite de tasa por usuario/IP. Los límites por defecto son 100 solicitudes por minuto. Exceder el límite retorna 429 Too Many Requests con un header Retry-After.

Salud y Monitoreo

GET/api/health

Verificación de salud del sistema (sin autenticación)

Retorna el estado de salud de todos los componentes del sistema.

{
  "status": "healthy",
  "timestamp": "2025-01-15T10:00:00Z",
  "uptime": 86400,
  "version": "2.0.0",
  "checks": {
    "database": { "status": "healthy", "responseTime": 5 },
    "redis": { "status": "healthy", "responseTime": 2 }
  }
}
GET/api/metrics

Métricas Prometheus (solo admin)

Retorna métricas de la aplicación en formato de exposición Prometheus. Requiere permiso metrics:read.

Gestión de Almacén (WHMS)

Almacenes

GET/api/whms/warehouses

Listar todos los almacenes

Retorna todos los almacenes accesibles al usuario autenticado.

POST/api/whms/warehouses

Crear un almacén

{
  "name": "Main Warehouse",
  "location": { "lat": 19.43, "lng": -99.13 },
  "timezone": "America/Mexico_City"
}
GET/api/whms/warehouses/:id

Obtener detalles del almacén

Retorna metadatos del almacén, resumen de zonas y estadísticas de utilización.

Zonas

GET/api/whms/zones

Listar todas las zonas

Retorna zonas con conteo de slots y datos de ocupación.

POST/api/whms/zones

Crear una zona

{
  "name": "Zone A",
  "zone_type": "storage",
  "color": "#3b82f6",
  "warehouseId": 1
}
GET/api/whms/zones/:id/slots

Listar slots en una zona

Retorna todos los slots dentro de una zona con estado de ocupación actual.

Slots

GET/api/whms/slots

Listar todos los slots

Retorna todos los slots con ocupación calculada desde el registro de eventos.

GET/api/whms/slots/:id

Obtener slot con estado de ocupación

Retorna metadatos del slot y estado actual calculado: isOccupied, assetBarcode, isVerified.

POST/api/whms/slots

Crear un slot

{
  "slot_id": "A-01-01",
  "zone": "A",
  "floor_plan_polygon": [
    { "x": 10, "y": 20 },
    { "x": 50, "y": 20 },
    { "x": 50, "y": 60 },
    { "x": 10, "y": 60 }
  ]
}

Unidades de Transporte

GET/api/whms/transport-units

Listar unidades de transporte

Retorna todas las unidades de transporte con etapa y estado actual.

GET/api/whms/transport-units/:id

Obtener detalles de unidad de transporte

Retorna el registro completo de la unidad de transporte incluyendo historial de flujo de trabajo y evidencias.

Eventos

GET/api/whms/events

Consultar historial de eventos

Soporta filtrado por slot_id, asset_barcode, event_type y paginación vía limit/offset.

POST/api/whms/events

Crear un evento de colocación

{
  "event_type": "PLACED",
  "slot_id": 5,
  "asset_barcode": "PLT-2024-00001",
  "operator": "op-123",
  "photo_url": "https://cloud.example.com/evidence/photo.jpg",
  "scale_weight_kg": 1250
}

Activos

GET/api/whms/assets

Listar activos

Retorna todos los activos registrados con tipo y metadatos.

GET/api/whms/assets/:barcode/location

Obtener ubicación del activo

Retorna la ubicación actual (slot) de un activo derivada del registro de eventos.

Dashboard

GET/api/whms/dashboard/utilization

Estadísticas de utilización por zona

{
  "totalSlots": 200,
  "occupiedSlots": 142,
  "utilizationPercent": 71,
  "pendingVerifications": 8,
  "byZone": [
    { "zone": "A", "occupied": 45, "total": 60 },
    { "zone": "B", "occupied": 38, "total": 50 }
  ]
}

IoT y Vigilancia

GET/api/iot/cctv

Listar cámaras (filtrado por propiedad)

Retorna cámaras accesibles al usuario autenticado. Las URLs RTSP y credenciales nunca se exponen.

POST/api/iot/detection/motion-stream

Iniciar/detener detección de movimiento

Controla la detección de movimiento FFmpeg del lado del servidor por cámara. Ver Detección de Movimiento.

GET/api/iot/detection-events

Consultar eventos de detección

Retorna eventos de detección de movimiento con URLs de clips y metadatos.

Gobernanza

GET/api/governance/audit

Consultar registro de auditoría

Retorna entradas de la pista de auditoría con filtrado por entidad, operador y rango temporal.

POST/api/governance/incidents

Crear un reporte de incidente

Registrar un incidente de cumplimiento con severidad, categoría y referencias de evidencia.

Manejo de Errores

Todos los endpoints retornan respuestas de error estandarizadas:

{
  "success": false,
  "error": {
    "message": "Error description",
    "code": "ERROR_CODE",
    "details": "Additional context"
  }
}

Códigos de estado HTTP comunes: 400 (validación), 401 (no autorizado), 403 (prohibido), 404 (no encontrado), 429 (límite de tasa), 500 (error del servidor).

Relacionado