Estado de Tarea

GET/v1/tasks/{token}

Consulta cada 3–5 segundos hasta completed o failed.

Token con el que consultas y descargas. Este es el parámetro de ruta {token} de los endpoints de tarea.

Ejemplo de Respuesta

{
  "task_id": "xKj9aP3qLm7v",
  "status": "completed",
  "progress": 100,
  "product": "YOUR_PRODUCT_SLUG",
  "country": "CN",
  "submitted": 5000,
  "prefiltered": 0,
  "deduped": 0,
  "total": 5000,
  "processed": 5000,
  "valid": 3800,
  "invalid": 1200,
  "unknown": 0,
  "unknown_processed": 0,
  "unknown_unprocessed": 0,
  "stage": "completed",
  "stage_seconds": 12,
  "last_progress_at": "2026-09-05T10:00:12+00:00",
  "failure_message": null,
  "cost_deducted": "0.500000",
  "cost_refunded": "0.000000",
  "result_available": true,
  "result_expires_at": "2026-05-02T10:00:00+00:00",
  "created_at": "2026-05-01T10:00:00+00:00"
}

Estado de Tarea

status	Descripción
pending	En cola, esperando recursos.
processing	La detección está en curso.
completed	Completado. El resultado está listo para descargar.
failed	La ejecución falló.

Campos de la respuesta

Campo	Tipo	Descripción
task_id	string	Token con el que consultas y descargas. Este es el parámetro de ruta {token} de los endpoints de tarea.
progress	integer	Porcentaje completado, 0 a 100.
status	string	pending, processing, completed o failed.
product	string	Slug del producto con el que se envió la tarea — consulta la lista de productos masivos.
country	string | null	País con el que se envió la tarea, o null para productos de correo electrónico.
submitted	integer	Filas recibidas en el envío.
prefiltered	integer	Filas descartadas antes de la detección, por ejemplo líneas mal formadas.
deduped	integer	Filas duplicadas eliminadas.
total	integer	Filas realmente en cola para detección, después del prefiltrado y la deduplicación.
processed	integer	Filas que el canal de origen ya terminó.
valid	integer	Filas confirmadas como registradas.
invalid	integer	Filas confirmadas como no registradas.
unknown	integer	Filas que el proveedor no pudo resolver.
unknown_processed	integer	Filas desconocidas que se reintentaron y se liquidaron.
unknown_unprocessed	integer	Filas desconocidas aún sin resolver. Se reembolsan.
stage	string | null	Nombre de la etapa interna mientras la tarea se ejecuta. Solo diagnóstico: no ramifiques según él.
stage_seconds	integer | null	Segundos transcurridos en la etapa actual.
last_progress_at	string (ISO 8601) | null	Cuándo avanzó el progreso por última vez. Una marca de tiempo que deja de moverse significa que la tarea está atascada, no solo lenta.
failure_message	string | null	Por qué falló la tarea, o null.
cost_deducted	string	Monto deducido por la tarea, como cadena.
cost_refunded	string	Monto reembolsado por las filas que nunca se verificaron, como cadena.
result_available	boolean	true cuando el archivo de resultados se puede descargar.
result_expires_at	string (ISO 8601) | null	Cuándo el archivo de resultados deja de poder descargarse.
created_at	string (ISO 8601)	Cuándo se creó la tarea.

Cómo leer los conteos

submitted es lo que enviaste; total es lo que realmente se verificó. Difieren siempre que haya filas mal formadas o duplicadas, y la diferencia es exactamente prefiltered + deduped.

cost_deducted se cobra sobre total, y cost_refunded cubre las filas que nunca se resolvieron — el grupo unknown_unprocessed. Solo se facturan los veredictos valid e invalid.

Sondeo

# Poll until the task leaves pending/processing. `last_progress_at` going
# stale is the real failure signal, not elapsed time.
for i in $(seq 1 120); do
  body=$(curl -s -X GET "https://api.zelnum.com/api/v1/tasks/xKj9aP3qLm7v" \
    -H "X-API-Key: YOUR_KEY_HERE")
  status=$(printf '%s' "$body" | jq -r '.status')
  printf '%s %s%%\n' "$status" "$(printf '%s' "$body" | jq -r '.progress')"
  case "$status" in
    completed) printf '%s' "$body" | jq .; break ;;
    failed)    printf '%s' "$body" | jq .; exit 1 ;;
  esac
  sleep 5
done

Siguiente

• Descarga los resultados cuando result_available sea true