Saltar al contenido principal

Instancias de Workflow

Iniciá, cancelá y monitoreá ejecuciones de workflow. Recuperá los detalles de una instancia con sus tareas, líneas de tiempo de eventos y datos de formulario capturados en todos los pasos completados.

Requisitos previos

Todos los endpoints de esta página requieren un token JWT válido, una clave de API y el encabezado tenant. Consultá Autenticación para más detalles.

Listar instancias​

Recuperá una lista paginada de instancias de workflow.

GET/apidev/v1/workflow/instances
PermisoAPICLI_WORKFLOW_READ
Límite de solicitudes30 req/min (ventana deslizante)
Caché15s

Encabezados de la solicitud​

Every request to a protected endpoint requires these headers:

HeaderRequiredDescription
AuthorizationYesBearer token obtained from the Login endpoint. Format: Bearer <token>
X-API-KeyYesCompany integration key provided during onboarding. Format: gtk_xxx...
tenantYesYour assigned tenant domain (default: geotareas.com) — always send your assigned tenant
Content-TypeConditionalapplication/json — required for POST and PUT requests

Parámetros de consulta​

ParámetroTipoObligatorioPor defectoDescripción
limitintegerNo25Cantidad de registros por página. Mín: 1, Máx: 100
offsetintegerNo0Cantidad de registros a omitir para la paginación
statusstringNo—Filtrar por estado: RUNNING, COMPLETED, CANCELLED, ERROR
definition_idstringNo—Filtrar por ID de definición de workflow. Longitud máxima: 30
entity_typestringNo—Filtrar por tipo de entidad
entity_idstringNo—Filtrar por ID de la entidad asociada. Longitud máxima: 30
startdatestringNo—Límite inferior de la fecha de inicio (ISO 8601). Longitud máxima: 30
enddatestringNo—Límite superior de la fecha de inicio (ISO 8601). Longitud máxima: 30

Respuesta​

CampoTipoDescripción
idstringIdentificador único de la instancia (BigInt)
definition_idstringID de la definición de workflow (BigInt)
definition_namestringNombre de la definición de workflow
statusstring"RUNNING", "COMPLETED", "CANCELLED" o "ERROR"
entity_typestringTipo de entidad con la que está asociada esta instancia
entity_idstring | nullID de la entidad asociada (BigInt)
entity_labelstring | nullEtiqueta visible de la entidad asociada
current_stepstring | nullNombre del paso actual (null si está completada/cancelada)
started_atstringMarca de tiempo de inicio (ISO 8601, sin zona horaria)
ended_atstring | nullMarca de tiempo de fin (ISO 8601, sin zona horaria)
cancelled_atstring | nullMarca de tiempo de cancelación (ISO 8601, sin zona horaria)
pending_tasks_countintegerCantidad de tareas humanas pendientes

Ejemplos de código​

curl -s -X GET "https://$TENANT_HOST/apidev/v1/workflow/instances?limit=10&status=RUNNING" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-API-Key: $APIKEY" \
  -H "tenant: $TENANT"

Ejemplo de respuesta​

{
  "success": true,
  "data": [
    {
      "id": "591847302948571634",
      "definition_id": "482938470192837465",
      "definition_name": "New Account Onboarding",
      "status": "RUNNING",
      "entity_type": "CUENTA",
      "entity_id": "738291047382910473",
      "entity_label": "Acme Corp",
      "current_step": "Send Welcome Email",
      "started_at": "2026-03-15T10:00:00",
      "ended_at": null,
      "cancelled_at": null,
      "pending_tasks_count": 1
    }
  ],
  "meta": {
    "total": 34,
    "limit": 10,
    "offset": 0
  }
}

Encabezados del límite de solicitudes​

Every response includes rate limit information in the headers:

HeaderDescription
X-RateLimit-LimitMaximum number of requests allowed in the current window
X-RateLimit-RemainingNumber of requests remaining in the current window
X-RateLimit-ResetUnix timestamp (seconds) when the current window resets
Retry-AfterSeconds to wait before retrying (only present on 429 responses)
X-Request-IdUnique request identifier for debugging and support tickets

Detalle de la instancia​

Recuperá el perfil completo de una única instancia de workflow, incluyendo sus tareas asociadas.

GET/apidev/v1/workflow/instances/{id}
PermisoAPICLI_WORKFLOW_READ
Límite de solicitudes30 req/min (ventana deslizante)
Caché15s

Parámetros de ruta​

ParámetroTipoObligatorioDescripción
idstringSíEl identificador único de la instancia de workflow (BigInt)

Respuesta​

CampoTipoDescripción
idstringIdentificador único de la instancia (BigInt)
definition_idstringID de la definición de workflow (BigInt)
definition_namestringNombre de la definición de workflow
statusstring"RUNNING", "COMPLETED", "CANCELLED" o "ERROR"
entity_typestringTipo de entidad
entity_idstring | nullID de la entidad asociada (BigInt)
entity_labelstring | nullEtiqueta visible de la entidad asociada
current_stepobject | nullInformación del paso actual (ver abajo)
trigger_typestringCómo se inició la instancia: manual, event, schedule
started_atstringMarca de tiempo de inicio
ended_atstring | nullMarca de tiempo de fin
cancelled_atstring | nullMarca de tiempo de cancelación
cancelled_bystring | nullUsuario que canceló la instancia
cancel_reasonstring | nullMotivo de la cancelación
tasksarrayLista de tareas creadas para esta instancia (ver abajo)

Objeto current_step:

CampoTipoDescripción
node_idstringIdentificador del nodo
namestringNombre visible del paso

Elementos del arreglo tasks:

CampoTipoDescripción
idstringIdentificador único de la tarea (BigInt)
step_namestringNombre visible del paso
statusstring"PENDING", "IN_PROGRESS", "COMPLETED"
assigned_tostring | nullNombre del usuario o grupo asignado
resultstring | nullCódigo de resultado de finalización
completed_atstring | nullMarca de tiempo de finalización

Ejemplo de respuesta​

{
  "success": true,
  "data": {
    "id": "591847302948571634",
    "definition_id": "482938470192837465",
    "definition_name": "New Account Onboarding",
    "status": "RUNNING",
    "entity_type": "CUENTA",
    "entity_id": "738291047382910473",
    "entity_label": "Acme Corp",
    "current_step": {
      "node_id": "node_d4e5f6",
      "name": "Send Welcome Email"
    },
    "trigger_type": "manual",
    "started_at": "2026-03-15T10:00:00",
    "ended_at": null,
    "cancelled_at": null,
    "cancelled_by": null,
    "cancel_reason": null,
    "tasks": [
      {
        "id": "674839201748392017",
        "step_name": "Verify Contact Information",
        "status": "COMPLETED",
        "assigned_to": "jdoe",
        "result": "approved",
        "completed_at": "2026-03-15T11:30:00"
      },
      {
        "id": "674839201748392018",
        "step_name": "Send Welcome Email",
        "status": "IN_PROGRESS",
        "assigned_to": "Sales Team",
        "result": null,
        "completed_at": null
      }
    ]
  },
  "meta": {}
}

Línea de tiempo de la instancia​

Recuperá el registro cronológico de eventos de una instancia de workflow.

GET/apidev/v1/workflow/instances/{id}/timeline
PermisoAPICLI_WORKFLOW_READ
Límite de solicitudes30 req/min (ventana deslizante)
Caché15s

Parámetros de ruta​

ParámetroTipoObligatorioDescripción
idstringSíEl identificador único de la instancia de workflow (BigInt)

Respuesta​

Devuelve un arreglo de objetos de evento de la línea de tiempo dentro del campo data.

CampoTipoDescripción
eventstringTipo de evento: started, step_completed, step_started, reassigned, cancelled, completed, error
datetimestringMarca de tiempo del evento (ISO 8601, sin zona horaria)
actorstringUsuario o sistema que disparó el evento
detailsobject | nullDatos adicionales específicos del evento

Ejemplo de respuesta​

{
  "success": true,
  "data": [
    {
      "event": "started",
      "datetime": "2026-03-15T10:00:00",
      "actor": "jdoe",
      "details": null
    },
    {
      "event": "step_started",
      "datetime": "2026-03-15T10:00:01",
      "actor": "system",
      "details": {"step_name": "Verify Contact Information", "assigned_to": "jdoe"}
    },
    {
      "event": "step_completed",
      "datetime": "2026-03-15T11:30:00",
      "actor": "jdoe",
      "details": {"step_name": "Verify Contact Information", "result_code": "approved"}
    }
  ],
  "meta": {}
}

Datos capturados de la instancia​

Recuperá todos los datos de formulario capturados durante la ejecución de una instancia de workflow en todos los pasos completados.

GET/apidev/v1/workflow/instances/{id}/captured-data
PermisoAPICLI_WORKFLOW_READ
Límite de solicitudes30 req/min (ventana deslizante)
Caché15s

Parámetros de ruta​

ParámetroTipoObligatorioDescripción
idstringSíEl identificador único de la instancia de workflow (BigInt)

Respuesta​

Devuelve un arreglo de entradas de datos capturados agrupados por paso dentro del campo data.

CampoTipoDescripción
step_namestringNombre visible del paso
completed_bystringUsuario que completó el paso
completed_atstringMarca de tiempo de finalización (ISO 8601, sin zona horaria)
result_codestringCódigo de resultado de finalización
result_labelstringEtiqueta legible del resultado
fieldsarrayLista de valores de campos capturados (ver abajo)

Elementos del arreglo fields:

CampoTipoDescripción
namestringIdentificador del campo
typestringTipo de campo: text, number, date, boolean, select, file
valueanyValor capturado

Ejemplo de respuesta​

{
  "success": true,
  "data": [
    {
      "step_name": "Verify Contact Information",
      "completed_by": "jdoe",
      "completed_at": "2026-03-15T11:30:00",
      "result_code": "approved",
      "result_label": "Approved",
      "fields": [
        {
          "name": "contact_verified",
          "type": "boolean",
          "value": true
        },
        {
          "name": "phone_confirmed",
          "type": "boolean",
          "value": true
        },
        {
          "name": "verification_notes",
          "type": "text",
          "value": "Confirmed via phone call."
        }
      ]
    }
  ],
  "meta": {}
}

Iniciar instancia​

Iniciá una nueva instancia de workflow a partir de una definición dada.

POST/apidev/v1/workflow/instances
PermisoAPICLI_WORKFLOW_EXECUTE
Límite de solicitudes30 req/min (ventana deslizante)
nota

Iniciar una instancia comparte el mismo cupo de límite de solicitudes que los endpoints de lectura (30 solicitudes por minuto), aunque requiere el permiso de ejecución.

Encabezados de la solicitud​

Every request to a protected endpoint requires these headers:

HeaderRequiredDescription
AuthorizationYesBearer token obtained from the Login endpoint. Format: Bearer <token>
X-API-KeyYesCompany integration key provided during onboarding. Format: gtk_xxx...
tenantYesYour assigned tenant domain (default: geotareas.com) — always send your assigned tenant
Content-TypeConditionalapplication/json — required for POST and PUT requests

Cuerpo de la solicitud​

CampoTipoObligatorioDescripción
definition_idstringSíEl ID de la definición de workflow a instanciar. Longitud máxima: 30
entity_typestringSíTipo de entidad: TAREA, CUENTA, CLIENTE, PERSONAL, DISPOSITIVO, NINGUNA
entity_idstringNoEl ID de la entidad a asociar con esta instancia. Longitud máxima: 30
nota

entity_id es obligatorio siempre que entity_type sea cualquier valor distinto de NINGUNA. Enviar una instancia con un tipo de entidad pero sin ID de entidad devuelve un 400 VALIDATION_ERROR.

Ejemplos de código​

curl -s -X POST "https://$TENANT_HOST/apidev/v1/workflow/instances" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-API-Key: $APIKEY" \
  -H "tenant: $TENANT" \
  -H "Content-Type: application/json" \
  -d '{
    "definition_id": "482938470192837465",
    "entity_type": "CUENTA",
    "entity_id": "738291047382910473"
  }'

Ejemplo de respuesta (201 Created)​

{
  "success": true,
  "data": {
    "instance_id": "591847302948571635",
    "status": "RUNNING",
    "current_step": "Verify Contact Information"
  },
  "meta": {}
}

Cancelar instancia​

Cancelá una instancia de workflow en ejecución. El estado de la instancia cambia a CANCELLED y todas las tareas pendientes se cierran.

POST/apidev/v1/workflow/instances/{id}/cancel
PermisoAPICLI_WORKFLOW_EXECUTE
Límite de solicitudes10 req/min (ventana deslizante)

Parámetros de ruta​

ParámetroTipoObligatorioDescripción
idstringSíEl identificador único de la instancia de workflow (BigInt)

Cuerpo de la solicitud​

CampoTipoObligatorioDescripción
reasonstringSíMotivo para cancelar la instancia de workflow. Longitud máxima: 500

Ejemplos de código​

curl -s -X POST "https://$TENANT_HOST/apidev/v1/workflow/instances/591847302948571634/cancel" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-API-Key: $APIKEY" \
  -H "tenant: $TENANT" \
  -H "Content-Type: application/json" \
  -d '{"reason": "Account onboarding no longer needed — duplicate."}'

Ejemplo de respuesta​

{
  "success": true,
  "data": {
    "instance_id": "591847302948571634",
    "status": "CANCELLED",
    "cancelled_at": "2026-03-19T14:05:00"
  },
  "meta": {}
}

Errores​

Todos los endpoints de esta página pueden devolver los siguientes errores. Para la referencia completa de errores, consultá Manejo de errores.

CódigoHTTPDescripción
VALIDATION_ERROR400Parámetros inválidos
UNAUTHORIZED401tenant / Authorization / X-API-Key ausente, inválido o expirado
FORBIDDEN403El usuario no tiene el permiso requerido
NOT_FOUND404Recurso no encontrado
RATE_LIMITED429Se superó el límite de solicitudes
INTERNAL_ERROR500Error inesperado del servidor