Tareas de Workflow

Gestioná las tareas humanas generadas por los workflows en ejecución. Listá las tareas pendientes en tu bandeja de entrada, consultá el detalle de una tarea con sus resultados disponibles y campos de formulario, completá tareas con datos capturados y reasigná tareas a otros usuarios o grupos.

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 tareas

Recuperá una lista paginada de tareas de workflow.

GET/apidev/v1/workflow/tasks

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:

Header	Required	Description
`Authorization`	Yes	Bearer token obtained from the Login endpoint. Format: `Bearer <token>`
`X-API-Key`	Yes	Company integration key provided during onboarding. Format: `gtk_xxx...`
`tenant`	Yes	Your assigned tenant domain (default: `geotareas.com`) — always send your assigned tenant
`Content-Type`	Conditional	`application/json` — required for `POST` and `PUT` requests

Parámetros de consulta

Parámetro	Tipo	Obligatorio	Por defecto	Descripción
`limit`	integer	No	`25`	Cantidad de registros por página. Mín: `1`, Máx: `100`
`offset`	integer	No	`0`	Cantidad de registros a omitir para la paginación
`status`	string	No	—	Filtrar por estado: `PENDING`, `IN_PROGRESS`, `COMPLETED`
`definition_id`	string	No	—	Filtrar por ID de definición de workflow. Longitud máxima: 30
`entity_type`	string	No	—	Filtrar por tipo de entidad
`overdue_only`	boolean	No	`false`	Devolver solo las tareas vencidas

Respuesta

Campo	Tipo	Descripción
`id`	string	Identificador único de la tarea (BigInt)
`instance_id`	string	ID de la instancia de workflow padre (BigInt)
`workflow_name`	string	Nombre de la definición de workflow
`step_name`	string	Nombre visible del paso
`status`	string	`"PENDING"`, `"IN_PROGRESS"` o `"COMPLETED"`
`assigned_to_user`	object \| null	Usuario asignado `{id, name}`
`assigned_to_group`	object \| null	Grupo asignado `{id, name}`
`entity`	object	Entidad asociada `{type, id, label}`
`due_date`	string \| null	Fecha de vencimiento de la tarea (ISO 8601, sin zona horaria)
`escalated`	boolean	Si la tarea fue escalada
`created_at`	string	Marca de tiempo de creación de la tarea (ISO 8601, sin zona horaria)

Ejemplos de código

cURL
JavaScript
Python

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

const response = await fetch(
  `https://${TENANT_HOST}/apidev/v1/workflow/tasks?limit=10&status=PENDING`,
  {
    headers: {
      "Authorization": `Bearer ${TOKEN}`,
      "X-API-Key": APIKEY,
      "tenant": TENANT,
    },
  }
);

const { data, meta } = await response.json();
console.log(`Fetched ${data.length} of ${meta.total} tasks`);

import requests

response = requests.get(
    f"https://{TENANT_HOST}/apidev/v1/workflow/tasks",
    headers={
        "Authorization": f"Bearer {TOKEN}",
        "X-API-Key": APIKEY,
        "tenant": TENANT,
    },
    params={"limit": 10, "status": "PENDING"},
)

result = response.json()
for task in result["data"]:
    print(f"{task['id']}: {task['step_name']} ({task['status']})")

Ejemplo de respuesta

{
  "success": true,
  "data": [
    {
      "id": "674839201748392018",
      "instance_id": "591847302948571634",
      "workflow_name": "New Account Onboarding",
      "step_name": "Send Welcome Email",
      "status": "PENDING",
      "assigned_to_user": null,
      "assigned_to_group": {"id": "293847102938471029", "name": "Sales Team"},
      "entity": {"type": "CUENTA", "id": "738291047382910473", "label": "Acme Corp"},
      "due_date": "2026-03-17T11:30:00",
      "escalated": false,
      "created_at": "2026-03-15T11:30:01"
    }
  ],
  "meta": {
    "total": 8,
    "limit": 10,
    "offset": 0
  }
}

Encabezados del límite de solicitudes

Every response includes rate limit information in the headers:

Header	Description
`X-RateLimit-Limit`	Maximum number of requests allowed in the current window
`X-RateLimit-Remaining`	Number of requests remaining in the current window
`X-RateLimit-Reset`	Unix timestamp (seconds) when the current window resets
`Retry-After`	Seconds to wait before retrying (only present on `429` responses)
`X-Request-Id`	Unique request identifier for debugging and support tickets

Detalle de la tarea

Recuperá el detalle completo de una única tarea de workflow, incluyendo los resultados disponibles, los campos de formulario y los datos capturados en pasos anteriores.

GET/apidev/v1/workflow/tasks/{id}

PermisoAPICLI_WORKFLOW_READ

Límite de solicitudes30 req/min (ventana deslizante)

Caché15s

Parámetros de ruta

Parámetro	Tipo	Obligatorio	Descripción
`id`	string	Sí	El identificador único de la tarea (BigInt)

Respuesta

Campo	Tipo	Descripción
`id`	string	Identificador único de la tarea (BigInt)
`instance_id`	string	ID de la instancia de workflow padre (BigInt)
`workflow_name`	string	Nombre de la definición de workflow
`step_name`	string	Nombre visible del paso
`step_description`	string \| null	Descripción del paso
`status`	string	`"PENDING"`, `"IN_PROGRESS"` o `"COMPLETED"`
`assigned_to_user`	object \| null	Usuario asignado `{id, name}`
`assigned_to_group`	object \| null	Grupo asignado `{id, name}`
`due_date`	string \| null	Fecha de vencimiento de la tarea
`escalated`	boolean	Si la tarea fue escalada
`entity`	object	Entidad asociada `{type, id, label}`
`available_results`	array	Resultados de finalización posibles (ver abajo)
`fields`	array	Campos de formulario a capturar (ver abajo)
`previous_steps_data`	array	Datos capturados en pasos anteriores (ver abajo)
`created_at`	string	Marca de tiempo de creación de la tarea

Elementos del arreglo available_results:

Campo	Tipo	Descripción
`code`	string	Código de resultado a enviar al completar la tarea
`label`	string	Etiqueta visible del resultado

Elementos del arreglo fields:

Campo	Tipo	Descripción
`id`	string	Identificador del campo
`name`	string	Nombre del campo a usar en `captured_data`
`type`	string	Tipo de campo: `text`, `number`, `date`, `boolean`, `select`, `file`
`required`	boolean	Si este campo es obligatorio
`value`	any \| null	Valor actual (precargado o null)

Elementos del arreglo previous_steps_data:

Campo	Tipo	Descripción
`step_name`	string	Nombre visible del paso
`completed_by`	string	Usuario que completó el paso
`completed_at`	string	Marca de tiempo de finalización
`result`	string	Código de resultado
`captured_data`	object	Pares clave-valor de los datos de campo capturados

Ejemplo de respuesta

{
  "success": true,
  "data": {
    "id": "674839201748392018",
    "instance_id": "591847302948571634",
    "workflow_name": "New Account Onboarding",
    "step_name": "Send Welcome Email",
    "step_description": "Send the welcome email to the new account contact.",
    "status": "PENDING",
    "assigned_to_user": null,
    "assigned_to_group": {"id": "293847102938471029", "name": "Sales Team"},
    "due_date": "2026-03-17T11:30:00",
    "escalated": false,
    "entity": {"type": "CUENTA", "id": "738291047382910473", "label": "Acme Corp"},
    "available_results": [
      {"code": "sent", "label": "Email Sent"},
      {"code": "failed", "label": "Email Failed"}
    ],
    "fields": [
      {"id": "f_email", "name": "email_address", "type": "text", "required": true, "value": null},
      {"id": "f_template", "name": "template", "type": "select", "required": true, "value": null}
    ],
    "previous_steps_data": [
      {
        "step_name": "Verify Contact Information",
        "completed_by": "jdoe",
        "completed_at": "2026-03-15T11:30:00",
        "result": "approved",
        "captured_data": {
          "contact_verified": true,
          "phone_confirmed": true
        }
      }
    ],
    "created_at": "2026-03-15T11:30:01"
  },
  "meta": {}
}

Completar tarea

Completá una tarea de workflow proporcionando un código de resultado y datos capturados opcionales. El workflow avanza al siguiente paso.

POST/apidev/v1/workflow/tasks/{id}/complete

PermisoAPICLI_WORKFLOW_EXECUTE

Límite de solicitudes10 req/min (ventana deslizante)

Parámetros de ruta

Parámetro	Tipo	Obligatorio	Descripción
`id`	string	Sí	El identificador único de la tarea (BigInt)

Cuerpo de la solicitud

Campo	Tipo	Obligatorio	Descripción
`result_code`	string	Sí	Uno de los códigos de `available_results`. Longitud máxima: 80
`captured_data`	object	No	Pares clave-valor que coinciden con los `fields` de la tarea
`comment`	string	No	Comentario opcional. Longitud máxima: 2000

Ejemplos de código

cURL
JavaScript
Python

curl -s -X POST "https://$TENANT_HOST/apidev/v1/workflow/tasks/674839201748392018/complete" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-API-Key: $APIKEY" \
  -H "tenant: $TENANT" \
  -H "Content-Type: application/json" \
  -d '{
    "result_code": "sent",
    "captured_data": {
      "email_address": "contact@acme.com",
      "template": "Premium Welcome"
    },
    "comment": "Welcome email sent successfully."
  }'

const response = await fetch(
  `https://${TENANT_HOST}/apidev/v1/workflow/tasks/674839201748392018/complete`,
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${TOKEN}`,
      "X-API-Key": APIKEY,
      "tenant": TENANT,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      result_code: "sent",
      captured_data: {
        email_address: "contact@acme.com",
        template: "Premium Welcome",
      },
      comment: "Welcome email sent successfully.",
    }),
  }
);

const { data } = await response.json();
console.log(`Task ${data.task_id} completed — next step: ${data.next_step}`);

import requests

response = requests.post(
    f"https://{TENANT_HOST}/apidev/v1/workflow/tasks/674839201748392018/complete",
    headers={
        "Authorization": f"Bearer {TOKEN}",
        "X-API-Key": APIKEY,
        "tenant": TENANT,
        "Content-Type": "application/json",
    },
    json={
        "result_code": "sent",
        "captured_data": {
            "email_address": "contact@acme.com",
            "template": "Premium Welcome",
        },
        "comment": "Welcome email sent successfully.",
    },
)

result = response.json()
print(f"Task {result['data']['task_id']} completed")

Ejemplo de respuesta

{
  "success": true,
  "data": {
    "task_id": "674839201748392018",
    "status": "COMPLETED",
    "result": "sent",
    "completed_at": "2026-03-19T14:10:00",
    "instance_status": "RUNNING",
    "next_step": "Review Welcome Package"
  },
  "meta": {}
}

Reasignar tarea

Reasigná una tarea pendiente o en progreso a un usuario o grupo diferente. Se requiere uno de assign_to_user_id o assign_to_group_id.

POST/apidev/v1/workflow/tasks/{id}/reassign

PermisoAPICLI_WORKFLOW_EXECUTE

Límite de solicitudes10 req/min (ventana deslizante)

Parámetros de ruta

Parámetro	Tipo	Obligatorio	Descripción
`id`	string	Sí	El identificador único de la tarea (BigInt)

Cuerpo de la solicitud

Campo	Tipo	Obligatorio	Descripción
`assign_to_user_id`	string	Condicional	ID del usuario al que asignar la tarea. Longitud máxima: 30
`assign_to_group_id`	string	Condicional	ID del grupo al que asignar la tarea. Longitud máxima: 30
`comment`	string	No	Comentario opcional que explica la reasignación. Longitud máxima: 500

Ejemplos de código

cURL
JavaScript
Python

curl -s -X POST "https://$TENANT_HOST/apidev/v1/workflow/tasks/674839201748392018/reassign" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-API-Key: $APIKEY" \
  -H "tenant: $TENANT" \
  -H "Content-Type: application/json" \
  -d '{
    "assign_to_user_id": "182736450918273645",
    "comment": "Reassigning to specialist."
  }'

const response = await fetch(
  `https://${TENANT_HOST}/apidev/v1/workflow/tasks/674839201748392018/reassign`,
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${TOKEN}`,
      "X-API-Key": APIKEY,
      "tenant": TENANT,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      assign_to_user_id: "182736450918273645",
      comment: "Reassigning to specialist.",
    }),
  }
);

const { data } = await response.json();
console.log(`Task ${data.task_id} reassigned to ${data.assigned_to_user.name}`);

import requests

response = requests.post(
    f"https://{TENANT_HOST}/apidev/v1/workflow/tasks/674839201748392018/reassign",
    headers={
        "Authorization": f"Bearer {TOKEN}",
        "X-API-Key": APIKEY,
        "tenant": TENANT,
        "Content-Type": "application/json",
    },
    json={
        "assign_to_user_id": "182736450918273645",
        "comment": "Reassigning to specialist.",
    },
)

result = response.json()
print(f"Task {result['data']['task_id']} reassigned")

Ejemplo de respuesta

{
  "success": true,
  "data": {
    "task_id": "674839201748392018",
    "assigned_to_user": {"id": "182736450918273645", "name": "Maria Garcia"},
    "assigned_to_group": null,
    "reassigned_at": "2026-03-19T14:15: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ódigo	HTTP	Descripción
`VALIDATION_ERROR`	400	Parámetros inválidos
`UNAUTHORIZED`	401	tenant / Authorization / X-API-Key ausente, inválido o expirado
`FORBIDDEN`	403	El usuario no tiene el permiso requerido
`NOT_FOUND`	404	Recurso no encontrado
`RATE_LIMITED`	429	Se superó el límite de solicitudes
`INTERNAL_ERROR`	500	Error inesperado del servidor

Autenticación -- Cómo obtener y usar tokens JWT y claves de API
Definiciones de Workflow -- Explorá las configuraciones base de workflow disponibles
Instancias de Workflow -- Iniciá, hacé seguimiento y cancelá instancias de workflow
Paginación -- Parámetros y metadatos de paginación estándar
Límites de solicitudes -- Ventanas de límite de solicitudes y estrategias de reintento
Manejo de errores -- Referencia completa de códigos de error

Listar tareas​

Encabezados de la solicitud​

Parámetros de consulta​

Respuesta​

Ejemplos de código​

Ejemplo de respuesta​

Encabezados del límite de solicitudes​

Detalle de la tarea​

Parámetros de ruta​

Respuesta​

Ejemplo de respuesta​

Completar tarea​

Parámetros de ruta​

Cuerpo de la solicitud​

Ejemplos de código​

Ejemplo de respuesta​

Reasignar tarea​

Parámetros de ruta​

Cuerpo de la solicitud​

Ejemplos de código​

Ejemplo de respuesta​

Errores​

Recursos relacionados​

Listar tareas

Encabezados de la solicitud

Parámetros de consulta

Respuesta

Ejemplos de código

Ejemplo de respuesta

Encabezados del límite de solicitudes

Detalle de la tarea

Parámetros de ruta

Respuesta

Ejemplo de respuesta

Completar tarea

Parámetros de ruta

Cuerpo de la solicitud

Ejemplos de código

Ejemplo de respuesta

Reasignar tarea

Parámetros de ruta

Cuerpo de la solicitud

Ejemplos de código

Ejemplo de respuesta

Errores

Recursos relacionados