Flujos de Trabajo

Endpoints para gestionar definiciones de workflows, instancias y ejecutar acciones en DPOLab.

Todos los endpoints requieren autenticación JWT y el feature flag WORKFLOWS (plan Growth+).

Definiciones

Listar workflows

GET /api/v1/workflows

Query params:

Param	Tipo	Descripción
`entityType`	string	Filtrar por módulo: `DSAR`, `BREACH`, `DPIA`, `CONTRACT`, `CUSTOM`
`page`	number	Página (default: 1)
`limit`	number	Registros por página (default: 20, max: 100)

Permisos: Todos los roles.

Ejemplo:

curl -X GET "https://api.dpolab.com/api/v1/workflows?entityType=DSAR" \
  -H "Authorization: Bearer {token}"

Respuesta (200):

{
  "success": true,
  "data": {
    "workflows": [
      {
        "id": "wf_abc123",
        "name": "Revisión ARCO estándar",
        "description": "Flujo de 3 etapas para solicitudes ARCO",
        "entityType": "DSAR",
        "version": 2,
        "isActive": true,
        "stageCount": 3,
        "stages": [...],
        "webhooks": [],
        "createdBy": "usr_xyz",
        "createdAt": "2026-03-20T10:00:00Z",
        "updatedAt": "2026-03-22T15:30:00Z"
      }
    ],
    "pagination": { "page": 1, "limit": 20, "total": 3, "totalPages": 1 }
  }
}

Crear workflow

POST /api/v1/workflows

Permisos: OWNER, ADMIN.

Body:

{
  "name": "Revisión ARCO con legal",
  "description": "Flujo de aprobación con paso legal obligatorio",
  "entityType": "DSAR",
  "stages": [
    {
      "id": "stage-1",
      "name": "Revisión legal",
      "description": "Verificar requisitos legales",
      "order": 0,
      "requiredRole": "ANALYST",
      "actions": [
        { "id": "a1", "type": "APPROVE", "label": "Conforme" },
        { "id": "a2", "type": "REJECT", "label": "Devolver" }
      ],
      "autoAdvance": false,
      "slaDays": 5,
      "slaWarningDays": 1,
      "fields": [
        {
          "id": "f1",
          "name": "motivo_aprobacion",
          "label": "Motivo de aprobación",
          "type": "TEXTAREA",
          "required": true
        }
      ],
      "conditions": [],
      "parallelStages": []
    }
  ],
  "webhooks": [
    {
      "url": "https://hooks.example.com/workflow",
      "events": ["workflow.completed"],
      "secret": "mi-secreto-hmac",
      "enabled": true
    }
  ]
}

Respuesta (201):

{
  "success": true,
  "data": {
    "id": "wf_new456",
    "name": "Revisión ARCO con legal",
    "entityType": "DSAR",
    "version": 1,
    "isActive": true,
    "stages": [...],
    "webhooks": [...],
    "createdBy": "usr_xyz",
    "createdAt": "2026-03-22T16:00:00Z"
  }
}

Obtener workflow

GET /api/v1/workflows/:id

Permisos: Todos los roles.

Actualizar workflow

PUT /api/v1/workflows/:id

Permisos: OWNER, ADMIN.

Si se modifican las etapas (stages), la versión se incrementa automáticamente. Las instancias en curso mantienen el snapshot de la versión anterior.

Eliminar workflow (soft-delete)

DELETE /api/v1/workflows/:id

Permisos: OWNER, ADMIN.

Marca el workflow como inactivo (is_active = false). Retorna 409 si hay instancias activas usando esta definición.

Instancias

Iniciar instancia

POST /api/v1/workflows/:definitionId/start

Permisos: OWNER, ADMIN, DPO, ANALYST.

Body:

{
  "entityType": "DSAR",
  "entityId": "req_abc123"
}

💡

En la mayoría de los casos no necesitas llamar este endpoint manualmente. Los workflows se inician automáticamente cuando una entidad cambia de estado (ej: DSAR pasa a IN_PROGRESS).

Respuesta (201):

{
  "success": true,
  "data": {
    "id": "wfi_inst789",
    "definitionId": "wf_abc123",
    "definitionVersion": 2,
    "entityType": "DSAR",
    "entityId": "req_abc123",
    "currentStageId": "stage-1",
    "status": "ACTIVE",
    "startedBy": "usr_xyz",
    "startedAt": "2026-03-22T16:00:00Z"
  }
}

Obtener instancia

GET /api/v1/workflow-instances/:id

Retorna la instancia con el snapshot de la definición, SLA actual, completions de sub-etapas paralelas, y todos los eventos.

Buscar instancia por entidad

GET /api/v1/workflow-instances/entity/:entityType/:entityId

Retorna la instancia más reciente para una entidad. Retorna { data: null } si no hay instancia.

Ejemplo:

curl -X GET "https://api.dpolab.com/api/v1/workflow-instances/entity/DSAR/req_abc123" \
  -H "Authorization: Bearer {token}"

Ejecutar acción

POST /api/v1/workflow-instances/:id/action

Permisos: OWNER, ADMIN, DPO, ANALYST.

Body:

{
  "stageId": "stage-1",
  "actionType": "APPROVE",
  "notes": "Revisión legal conforme",
  "fieldValues": {
    "motivo_aprobacion": "Cumple con todos los requisitos del Art. 11"
  }
}

Campo	Tipo	Requerido	Descripción
`stageId`	string	Sí	ID de la etapa actual
`subStageId`	string	No	ID de sub-etapa paralela (si aplica)
`actionType`	string	Sí	`APPROVE`, `REJECT`, `REQUEST_INFO`, `REASSIGN`
`notes`	string	No	Notas del actor (max 2000 chars)
`reassignTo`	string	No	ID del usuario destino (solo con `REASSIGN`)
`fieldValues`	object	No	Valores de campos personalizados

Validaciones:

La instancia debe estar en estado ACTIVE
El stageId debe coincidir con current_stage_id
El rol del actor debe ser >= al requiredRole de la etapa
Si hay campos required, deben estar presentes en fieldValues
Campos DATE validan formato YYYY-MM-DD
Campos SELECT validan que el valor esté en las opciones definidas
Si hay sub-etapas paralelas, APPROVE está bloqueado hasta completar todas

Respuesta (200):

{
  "success": true,
  "data": {
    "id": "wfi_inst789",
    "definitionId": "wf_abc123",
    "entityType": "DSAR",
    "entityId": "req_abc123",
    "currentStageId": "stage-2",
    "status": "ACTIVE",
    "completedAt": null
  }
}

Ejecutar acción en sub-etapa paralela

Para completar una sub-etapa paralela, incluye subStageId:

{
  "stageId": "stage-2",
  "subStageId": "parallel-legal",
  "actionType": "APPROVE",
  "notes": "Revisión legal completada"
}

La sub-etapa se marca como completada. Cuando todas las sub-etapas estén completadas, la etapa principal podrá aprobarse.

Eventos de webhook

Los webhooks reciben un POST con:

{
  "event": "stage.approve",
  "timestamp": "2026-03-22T16:05:00Z",
  "instanceId": "wfi_inst789",
  "entityType": "DSAR",
  "entityId": "req_abc123",
  "stageId": "stage-1",
  "actionType": "APPROVE",
  "newStageId": "stage-2",
  "status": "ACTIVE"
}

Header de firma: X-Workflow-Signature: sha256={hmac}

Eventos disponibles: workflow.started, workflow.completed, stage.approve, stage.reject, stage.request_info, stage.reassign.

Códigos de error

Código	HTTP	Descripción
`VALIDATION_ERROR`	400	Body inválido o campo requerido faltante
`WORKFLOW_ERROR`	400	Workflow no activo, etapa incorrecta, sub-etapas pendientes
`FORBIDDEN`	403	Rol insuficiente para la etapa
`NOT_FOUND`	404	Definición o instancia no encontrada
`HAS_ACTIVE_INSTANCES`	409	No se puede eliminar workflow con instancias activas
`PLAN_REQUIRED`	402	Plan no incluye feature WORKFLOWS

Ver también

Módulo Flujos de Trabajo — Guía funcional completa

Contratos Governance