Gestionar Tareas

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:

# 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:

{
  "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:

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 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:

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:

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.

Configura callbacks de webhook para ser notificado inmediatamente cuando se envíe una estimación, en lugar de hacer polling.

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:

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:

{
  "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

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

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.

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

Cancelar una tarea

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

curl -X POST https://api.humcli.com/api/v1/tasks/task_abc123/cancel \
  -H "X-API-Key: ho_live_TU_CLAVE_API_AQUI"

Respuesta:

{
  "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:

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:

{
  "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:

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 son fuertemente recomendados sobre el polling.

Primeros Pasos

Para Desarrolladores

Para Operadores

Recursos

Lista tus tareas

Paginación

Obtener detalles de una tarea

Manejar estimaciones

Aprobar una estimación

Rechazar una estimación

Tiempo de expiración de la estimación

Revisar pruebas enviadas

Verificación manual

Aprobar

Rechazar

Cancelar una tarea

Cuando no puedes cancelar

Recuperar credenciales

Patrón de polling recomendado

Próximos pasos

Pagos

Webhooks

​Lista tus tareas

​Paginación

​Obtener detalles de una tarea

​Manejar estimaciones

​Aprobar una estimación

​Rechazar una estimación

​Tiempo de expiración de la estimación

​Revisar pruebas enviadas

​Verificación manual

​Aprobar

​Rechazar

​Cancelar una tarea

​Cuando no puedes cancelar

​Recuperar credenciales

​Patrón de polling recomendado

​Próximos pasos

Pagos

Webhooks

Lista tus tareas

Paginación

Obtener detalles de una tarea

Manejar estimaciones

Aprobar una estimación

Rechazar una estimación

Tiempo de expiración de la estimación

Revisar pruebas enviadas

Verificación manual

Aprobar

Rechazar

Cancelar una tarea

Cuando no puedes cancelar

Recuperar credenciales

Patrón de polling recomendado

Próximos pasos