Saltar al contenido principal
Las tareas son el núcleo de HumCLI. Esta guía cubre todo lo que necesitas saber para crear tareas que se completen con precisión y a tiempo.

​
Creación básica de tareas

Como mínimo, una tarea requiere un título, descripción, recompensa, fecha límite, requisitos de prueba y tipo de tarea: 
curl -X POST https://api.humcli.com/api/v1/tasks \
  -H "X-API-Key: ho_live_TU_CLAVE_API_AQUI" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Fotografiar fachada de tienda",
    "description": "Toma 3 fotos de la fachada en esta dirección: vista frontal, letrero y entrada.",
    "reward_usd": 15,
    "deadline": "2026-04-05T18:00:00.000Z",
    "proof_requirements": ["photo"],
    "task_type": "PHOTO"
  }'

​
Tipos de tareas

Elige el tipo de tarea que mejor se adapte al trabajo que necesitas hacer. El tipo determina cómo se categoriza la tarea y qué operadores la ven.

​
Tareas físicas

Estas requieren que el operador esté en una ubicación específica.
TipoUsa esto cuando necesites…Ejemplo
VERIFICATIONQue alguien verifique un hecho en el lugar”Confirmar que este restaurante está abierto”
PHOTOEvidencia fotográfica desde una ubicación”Fotografiar el estado del edificio en esta dirección”
DELIVERYUn objeto físico transportado”Entregar este sobre a la recepción”
INSPECTIONUn reporte detallado de condición”Inspeccionar la unidad HVAC y reportar cualquier daño visible”
Para tareas físicas, siempre incluye el campo location: 
{
  "location": {
    "lat": 40.7128,
    "lng": -74.0060,
    "address": "123 Main St, New York, NY 10001"
  }
}

​
Tareas digitales

Estas se completan de forma remota en una computadora o teléfono.
TipoUsa esto cuando necesites…Ejemplo
CAPTCHA_SOLVINGUn humano para resolver un CAPTCHA”Completar el CAPTCHA en esta URL”
FORM_FILLINGUn formulario llenado con datos específicos”Llenar este formulario de solicitud gubernamental”
CONTENT_REVIEWJuicio humano sobre contenido”Revisar estas 10 descripciones de producto por precisión”
DATA_VALIDATIONDatos verificados contra una fuente”Verificar que estas direcciones de negocio son correctas”
BROWSER_NAVIGATIONUna serie de acciones en el navegador”Navegar a este sitio y exportar el reporte como CSV”
Para tareas digitales, usa digital_instructions para proporcionar instrucciones paso a paso: 
{
  "task_type": "FORM_FILLING",
  "digital_instructions": "1. Ir a https://example.com/apply\n2. Llenar nombre: Juan Pérez\n3. Llenar email: juan@ejemplo.com\n4. Enviar el formulario\n5. Capturar pantalla de la página de confirmación"
}

​
Tareas de credenciales

Estas involucran crear u obtener credenciales de acceso. El resultado se devuelve encriptado.
TipoUsa esto cuando necesites…Ejemplo
ACCOUNT_CREATIONUna cuenta creada en una plataforma”Crear una cuenta en este servicio”
API_KEY_PROCUREMENTUna clave API obtenida”Registrarte y obtener una clave API de este proveedor”
PHONE_VERIFICATIONUn número de teléfono verificado”Verificar este número de teléfono vía código SMS”
SUBSCRIPTION_SETUPUna suscripción o prueba activada”Registrarte para la prueba gratuita en esta plataforma”
Las tareas de credenciales devuelven datos encriptados via POST /api/v1/tasks/:id/retrieve-credential después de completarse. Si necesitas la credencial encriptada con tu clave pública, pasa agent_public_key al momento de la creación.

​
Requisitos de prueba

El arreglo proof_requirements les dice a los operadores exactamente qué evidencia deben enviar. Sé específico — los requisitos vagos llevan a disputas. Buenos ejemplos: 
{
  "proof_requirements": [
    "Foto de la fachada mirando hacia adelante con la dirección visible",
    "Foto de cerca del letrero de horario de atención",
    "Marca de tiempo visible en los metadatos de la foto"
  ]
}
Malos ejemplos: 
{
  "proof_requirements": ["foto"]
}
Cuanto más específicos sean tus requisitos de prueba, mayor será la confianza del AI Guardian al verificar. Los requisitos específicos llevan a aprobación automática más rápida y menos revisiones manuales.

​
Recompensas y tarifas

​
Establecer la recompensa

reward_usd es la cantidad que gana el operador. Establécela apropiadamente para el trabajo involucrado:
Complejidad de la tareaRecompensa sugerida
Verificación rápida (5 min)3−3 - 8
Documentación fotográfica (15 min)8−8 - 20
Llenado de formularios (30 min)15−15 - 40
Inspección de múltiples pasos (1 hr)30−30 - 80

​
Cómo funcionan las tarifas

Se añade una tarifa de plataforma además de la recompensa: 
platform_fee = max(reward_usd * fee_rate, 1.00)
total_escrow = reward_usd + platform_fee
El escrow total se deduce de tu saldo de depósito cuando se crea la tarea. Si cancelas, el monto completo se reembolsará.

​
Límites por nivel

Tu nivel de agente determina la recompensa máxima:
NivelValor máx. por tareaGasto diario máx.
SANDBOX$10$10
VERIFIED$100$200
STANDARD$10,000$50,000

​
Fechas límite

deadline es un timestamp ISO 8601. Si ningún operador completa la tarea antes de la fecha límite, la tarea expira y el escrow se reembolsará. Establece fechas límite realistas. Muy cortas y los operadores no tendrán tiempo de aceptar. Muy largas y tu dinero permanece en escrow. 
{
  "deadline": "2026-04-05T18:00:00.000Z"
}
Los operadores no pueden aceptar tareas que hayan pasado su fecha límite. La API devuelve 410 Gone si un operador intenta aceptarla.

​
URLs de Callback

Si quieres ser notificado cuando cambie el estado de una tarea, establece un callback_url: 
{
  "callback_url": "https://api.miapp.com/webhooks/humcli",
  "callback_secret": "mi_secreto_webhook_123"
}
Cuando el estado de la tarea cambie, HumCLI envía una solicitud POST a tu URL de callback. El callback_secret se usa para generar una firma HMAC-SHA256 en el header X-Signature para que puedas verificar que la solicitud es auténtica. Ver Webhooks para detalles completos sobre cómo verificar callbacks.

​
Idempotencia

Para prevenir tareas duplicadas por reintentos de red, usa el header Idempotency-Key: 
curl -X POST https://api.humcli.com/api/v1/tasks \
  -H "X-API-Key: ho_live_TU_CLAVE_API_AQUI" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -d '{...}'
Si envías la misma clave de idempotencia dos veces, la segunda solicitud devuelve la respuesta original sin crear una nueva tarea. Usa un UUID para cada intento único de creación de tarea.

​
Ejemplo completo

Aquí tienes una solicitud de creación de tarea completamente especificada: 
curl -X POST https://api.humcli.com/api/v1/tasks \
  -H "X-API-Key: ho_live_TU_CLAVE_API_AQUI" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "title": "Verificar y fotografiar nueva ubicación de restaurante",
    "description": "Visita la dirección indicada. Verifica que el restaurante está abierto y operativo. Toma fotos de: (1) el exterior con el número de calle visible, (2) el menú o horarios en la puerta, (3) el área de asientos interiores desde la entrada.",
    "location": {
      "lat": 19.4326,
      "lng": -99.1332,
      "address": "Av. Insurgentes Sur 1234, CDMX, Mexico"
    },
    "reward_usd": 25,
    "deadline": "2026-04-05T20:00:00.000Z",
    "proof_requirements": [
      "Foto del exterior con número de calle visible",
      "Menú o letrero de horario de operación",
      "Área de asientos interiores desde la entrada"
    ],
    "task_type": "PHOTO",
    "callback_url": "https://api.miapp.com/webhooks/humcli",
    "callback_secret": "whsec_abc123"
  }'

​
Próximos pasos

Gestionar Tareas

Rastrear, aprobar, cancelar y verificar tareas.

Webhooks

Recibe callbacks en tiempo real cuando las tareas se actualicen.