API REST

El middleware expone una API REST en el puerto 8080 para control y monitoreo.

Base URL

http://localhost:8080

Endpoints

Health Check

GET /health

Response:

{
  "status": "ok",
  "timestamp": "2025-01-08T10:30:00.000Z"
}

Estadísticas Generales

GET /stats

Response:

{
  "queue": {
    "waiting": 5,
    "active": 2,
    "completed": 1234,
    "failed": 3,
    "delayed": 0
  },
  "processed": 1234,
  "errors": 3
}

Métricas de Flows

GET /metrics

Response:

{
  "articulos": {
    "lastRun": "2025-01-08T10:30:00.000Z",
    "avgDuration": 1234,
    "p95Duration": 2100,
    "totalRuns": 500,
    "totalErrors": 2
  },
  "clientes": {
    "lastRun": "2025-01-08T10:28:00.000Z",
    "avgDuration": 456,
    "p95Duration": 800,
    "totalRuns": 100,
    "totalErrors": 0
  }
}

Errores Recientes

GET /errors

Response:

[
  {
    "id": "articulos-wms-ART001-1704710400000",
    "entity": "articulos",
    "adapter": "wms",
    "pk": "ART001",
    "error": "HTTP 400: Campo requerido",
    "timestamp": "2025-01-08T10:30:00.000Z",
    "attempts": 3
  }
]

Estado de Flows

GET /flows/status

Response:

{
  "articulos": {
    "paused": false,
    "runLimit": null,
    "runCount": 0
  },
  "clientes": {
    "paused": true,
    "runLimit": null,
    "runCount": 0
  },
  "pedidos": {
    "paused": false,
    "runLimit": 5,
    "runCount": 3
  }
}

Sync Endpoints

Forzar Sync de Flow

POST /sync/:name

Ejecuta polling del flow (sin limpiar cache).

Ejemplo:

curl -X POST http://localhost:8080/sync/articulos

Response:

{
  "name": "articulos",
  "changes": 15
}

Sync de Item Individual

POST /sync/:name/:pk

Sincroniza un solo item (ignora pause).

Ejemplo:

curl -X POST http://localhost:8080/sync/articulos/ART001

Response:

{
  "name": "articulos",
  "pk": "ART001",
  "found": true,
  "changed": true,
  "jobs": 2
}

Reset Hashes de Flow

DELETE /reset/:name

Borra todos los hashes del flow. El próximo poll re-sincroniza todo.

Ejemplo:

curl -X DELETE http://localhost:8080/reset/articulos

Response:

{
  "name": "articulos",
  "status": "reset"
}

Reset Hash de Item

DELETE /reset/:name/:pk

Borra hash de un item específico.

Ejemplo:

curl -X DELETE http://localhost:8080/reset/articulos/ART001

Resync de Flow

POST /resync/:name

Reset + Sync inmediato (re-sincroniza todo).

Ejemplo:

curl -X POST http://localhost:8080/resync/articulos

Resync de Item

POST /resync/:name/:pk

Reset hash de item + poll completo.

Ejemplo:

curl -X POST http://localhost:8080/resync/articulos/ART001

Control de Flows

Pausar Flow

POST /flow/:name/pause

Ejemplo:

curl -X POST http://localhost:8080/flow/articulos/pause

Response:

{
  "name": "articulos",
  "status": "paused"
}

Reanudar Flow

POST /flow/:name/resume

Ejemplo:

curl -X POST http://localhost:8080/flow/articulos/resume

Response:

{
  "name": "articulos",
  "status": "running"
}

Pausar Todos

POST /flows/pause

Reanudar Todos

POST /flows/resume

Establecer Límite de Ejecuciones

POST /flow/:name/limit/:count

El flow se auto-pausa después de N ejecuciones.

Ejemplo:

# Ejecutar solo 5 veces y pausar
curl -X POST http://localhost:8080/flow/articulos/limit/5

Response:

{
  "name": "articulos",
  "runLimit": 5,
  "status": "limited"
}

Quitar Límite

DELETE /flow/:name/limit

Ejemplo:

curl -X DELETE http://localhost:8080/flow/articulos/limit

Test de Alertas

POST /flow/:name/test-alerts

Dispara una notificación de prueba a todos los canales configurados en alerts.onJobFailed del flow (ignora el filtro destinations para permitir verificar conectividad de cada canal). Devuelve el resultado por canal.

Ejemplo:

curl -X POST http://localhost:8080/flow/clientes/test-alerts

Response 200 — todos los canales OK:

{
  "flow": "clientes",
  "results": [
    { "type": "email", "target": "ops@empresa.com", "ok": true },
    { "type": "slack", "target": "https://hooks.slack.com/...", "ok": true }
  ]
}

Response 207 — al menos un canal falló:

{
  "flow": "clientes",
  "results": [
    { "type": "email", "target": "ops@empresa.com", "ok": true },
    { "type": "webhook", "target": "https://hooks.miservicio.com/erp",
      "ok": false, "error": "HTTP 404" }
  ]
}

Response 400 — flow sin alertas configuradas:

{ "error": "El flow no tiene canales de alerta configurados (alerts.onJobFailed)" }

Ver detalles de configuración en Arquitectura · Alertas.

Códigos de Respuesta

Código	Significado
200	Éxito
207	Multi-Status — algunos canales OK, otros fallaron (solo `/test-alerts`)
400	Petición inválida (ej. flow sin alertas configuradas en `/test-alerts`)
404	Flow no encontrado
500	Error interno

Ejemplos de Uso

Workflow de Testing

# 1. Pausar flow de producción
curl -X POST http://localhost:8080/flow/articulos/pause

# 2. Probar con un solo item
curl -X POST http://localhost:8080/sync/articulos/ART001

# 3. Verificar resultado en logs

# 4. Si OK, habilitar con límite
curl -X POST http://localhost:8080/flow/articulos/limit/10

# 5. Monitorear 10 ejecuciones
# (se auto-pausa)

# 6. Si todo OK, quitar límite y reanudar
curl -X DELETE http://localhost:8080/flow/articulos/limit
curl -X POST http://localhost:8080/flow/articulos/resume

Reset Completo

# Re-sincronizar todo un flow
curl -X POST http://localhost:8080/resync/clientes

Monitoreo

# Ver estado general
curl http://localhost:8080/stats | jq

# Ver errores
curl http://localhost:8080/errors | jq

# Ver métricas
curl http://localhost:8080/metrics | jq