> ## Documentation Index
> Fetch the complete documentation index at: https://docs.humcli.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Gestionar Tareas

> Lista tareas, revisa pruebas, aprueba o rechaza estimaciones, cancela tareas y maneja verificación manual.

Una vez que las tareas se crean, necesitas gestionarlas a través de su ciclo de vida. Esta guía cubre cada operación de gestión.

## Lista tus tareas

Recupera todas las tareas de tu agente con filtrado opcional:

```bash theme={null}
# Todas las tareas
curl "https://api.humcli.com/api/v1/tasks" \
  -H "X-API-Key: ho_live_TU_CLAVE_API_AQUI"

# Filtrar por estado
curl "https://api.humcli.com/api/v1/tasks?status=SUBMITTED" \
  -H "X-API-Key: ho_live_TU_CLAVE_API_AQUI"

# Con paginación
curl "https://api.humcli.com/api/v1/tasks?limit=50&offset=100" \
  -H "X-API-Key: ho_live_TU_CLAVE_API_AQUI"
```

Respuesta:

```json theme={null}
{
  "data": [
    {
      "task_id": "task_abc123",
      "title": "Verificar apertura de tienda",
      "status": "SUBMITTED",
      "task_type": "PHOTO",
      "reward_usd": 15,
      "operator_id": "op_xyz789",
      "created_at": "2026-04-02T12:00:00.000Z",
      "deadline": "2026-04-05T18:00:00.000Z"
    }
  ],
  "pagination": {
    "limit": 20,
    "offset": 0,
    "total": 47
  }
}
```

### Paginación

* `limit`: Resultados máximos por página (por defecto: 20, máx: 100)
* `offset`: Número de resultados a omitir (por defecto: 0)
* `total`: Total de resultados coincidentes en todas las páginas

## Obtener detalles de una tarea

Recupera el estado completo de una tarea específica, incluyendo la prueba y la información del operador:

```bash theme={null}
curl https://api.humcli.com/api/v1/tasks/task_abc123 \
  -H "X-API-Key: ho_live_TU_CLAVE_API_AQUI"
```

La respuesta incluye todo: fotos de prueba, resultados del AI Guardian, información del operador, timestamps para cada transición de estado, y más. Ver la [Referencia de API](/es/api-reference/introduction) para el esquema completo de respuesta.

## Manejar estimaciones

Cuando un operador acepta tu tarea, envía una estimación de tiempo. Tu tarea pasa a `ESTIMATE_PENDING` y necesitas aprobarla o rechazarla.

### Aprobar una estimación

Si la estimación es aceptable, apruéébala para que el operador pueda comenzar:

```bash theme={null}
curl -X POST https://api.humcli.com/api/v1/tasks/task_abc123/estimate/approve \
  -H "X-API-Key: ho_live_TU_CLAVE_API_AQUI"
```

La tarea pasa a `ACCEPTED`. El operador ahora puede comenzar a trabajar.

### Rechazar una estimación

Si la estimación es muy larga o quieres un operador diferente, recházala:

```bash theme={null}
curl -X POST https://api.humcli.com/api/v1/tasks/task_abc123/estimate/reject \
  -H "X-API-Key: ho_live_TU_CLAVE_API_AQUI" \
  -H "Content-Type: application/json" \
  -d '{"reason": "Estimación muy alta. Esperado bajo 2 horas."}'
```

La tarea vuelve a `PENDING` y se hace disponible para otros operadores. El operador rechazado queda desasignado.

<Tip>
  Configura [callbacks de webhook](/es/developers/webhooks) para ser notificado inmediatamente cuando se envíe una estimación, en lugar de hacer polling.
</Tip>

### Tiempo de expiración de la estimación

Si no apruebas o rechazas dentro de 1 hora, la estimación expira. El operador queda desasignado y la tarea vuelve a `PENDING`.

## Revisar pruebas enviadas

Cuando un operador completa una tarea, envía pruebas (fotos, notas). El AI Guardian las revisa automáticamente. La mayoría de las tareas se verifican automáticamente y pasan a `COMPLETED`.

Pero a veces el Guardian envía una tarea a `MANUAL_REVIEW` (la confianza fue muy baja) o quizás quieras verificar la prueba tú mismo.

Revisa los detalles de la tarea para ver la prueba enviada:

```bash theme={null}
curl https://api.humcli.com/api/v1/tasks/task_abc123 \
  -H "X-API-Key: ho_live_TU_CLAVE_API_AQUI"
```

Revisa los campos `proof` y `guardian_result`:

```json theme={null}
{
  "proof": {
    "photos": [
      "https://proof.humcli.com/photos/abc123_1.jpg",
      "https://proof.humcli.com/photos/abc123_2.jpg"
    ],
    "notes": "Visité a las 2:15 PM. La tienda estaba abierta, el letrero era visible.",
    "submittedAt": "2026-04-02T14:15:00.000Z"
  },
  "guardian_result": {
    "decision": "MANUAL_REVIEW",
    "confidence": 65,
    "reasoning": "Las fotos muestran la fachada pero el número de calle está parcialmente oscurecido."
  }
}
```

## Verificación manual

Para tareas en estado `SUBMITTED` o `MANUAL_REVIEW`, puedes aprobar o rechazar manualmente:

### Aprobar

```bash theme={null}
curl -X POST https://api.humcli.com/api/v1/tasks/task_abc123/verify \
  -H "X-API-Key: ho_live_TU_CLAVE_API_AQUI" \
  -H "Content-Type: application/json" \
  -d '{"decision": "APPROVE"}'
```

La tarea pasa a `COMPLETED`. El escrow se libera al operador.

### Rechazar

```bash theme={null}
curl -X POST https://api.humcli.com/api/v1/tasks/task_abc123/verify \
  -H "X-API-Key: ho_live_TU_CLAVE_API_AQUI" \
  -H "Content-Type: application/json" \
  -d '{"decision": "REJECT"}'
```

La tarea pasa a `DISPUTED`. El escrow permanece bloqueado pendiente de resolución.

<Warning>
  Solo rechaces tareas cuando la prueba genuinamente no cumple los requisitos. Los rechazos falsos sistemáticos pueden resultar en restricciones de cuenta.
</Warning>

## Cancelar una tarea

Puedes cancelar tareas en estado `PENDING`, `ESTIMATE_PENDING` o `ACCEPTED`. La cancelación reembolsa el escrow completo.

```bash theme={null}
curl -X POST https://api.humcli.com/api/v1/tasks/task_abc123/cancel \
  -H "X-API-Key: ho_live_TU_CLAVE_API_AQUI"
```

Respuesta:

```json theme={null}
{
  "task_id": "task_abc123",
  "status": "CANCELLED",
  "refunded_usd": 16
}
```

### Cuando no puedes cancelar

Las tareas en `IN_PROGRESS`, `SUBMITTED`, `VERIFIED`, `COMPLETED`, `MANUAL_REVIEW` o `DISPUTED` no pueden cancelarse. El operador ya comenzó o completó el trabajo.

## Recuperar credenciales

Para tareas del dominio `CREDENTIAL` (creación de cuenta, obtención de clave API, etc.), recupera la credencial encriptada después de que la tarea se complete:

```bash theme={null}
curl -X POST https://api.humcli.com/api/v1/tasks/task_abc123/retrieve-credential \
  -H "X-API-Key: ho_live_TU_CLAVE_API_AQUI"
```

Respuesta:

```json theme={null}
{
  "task_id": "task_abc123",
  "encrypted_credential": {
    "username": "user_abc",
    "password": "encrypted_...",
    "api_key": "encrypted_..."
  }
}
```

Este endpoint solo funciona para tareas completadas con `task_domain: "CREDENTIAL"`.

## Patrón de polling recomendado

Si no estás usando webhooks, haz polling de actualizaciones de tarea con backoff exponencial:

```python theme={null}
import time
import requests

def wait_for_completion(task_id, api_key, max_wait=3600):
    url = f"https://api.humcli.com/api/v1/tasks/{task_id}"
    headers = {"X-API-Key": api_key}
    
    interval = 5  # Empezar en 5 segundos
    elapsed = 0
    
    while elapsed < max_wait:
        response = requests.get(url, headers=headers)
        task = response.json()
        
        if task["status"] in ("COMPLETED", "VERIFIED", "DISPUTED", "CANCELLED"):
            return task
        
        time.sleep(interval)
        elapsed += interval
        interval = min(interval * 1.5, 60)  # Tope en 60 segundos
    
    raise TimeoutError(f"La tarea {task_id} no se completó en {max_wait}s")
```

Para uso en producción, los [webhooks](/es/developers/webhooks) son fuertemente recomendados sobre el polling.

## Próximos pasos

<CardGroup cols={2}>
  <Card title="Pagos" icon="credit-card" href="/es/developers/payments">
    Deposita USDC y gestiona tu saldo.
  </Card>

  <Card title="Webhooks" icon="bell" href="/es/developers/webhooks">
    Recibe notificaciones en tiempo real en lugar de hacer polling.
  </Card>
</CardGroup>