Guía de integración de la API de consulta de tareas de WebExtrator

POST https://api.acedata.cloud/webextrator/tasks La API de consulta de tareas de WebExtrator se utiliza para consultar los resultados de tareas históricas de render / extract. Usos comunes:

Consulta del sobre completo después de que la tarea asíncrona se haya completado (además de la notificación a través de callback_url o sondeo activo).
Auditar lo que se ha enviado — el registro de tareas almacena tanto la request original como la response final.
Relleno por lotes — recuperar múltiples registros a la vez por id o trace_id.

Los registros de tareas se mantienen en Redis durante 7 días. La interfaz de consulta de tareas es gratuita (no se contabiliza en el uso de créditos).

Autenticación

Authorization: Bearer YOUR_API_KEY
Content-Type:  application/json

Solo se pueden consultar las tareas bajo la cuenta de AceDataCloud del usuario.

Parámetros de solicitud

El cuerpo de la solicitud se distingue por action, con dos tipos de acciones:

`action: "retrieve"` — Consulta individual

Campo	Tipo	Requerido	Descripción
`action`	const	✅	Fijo `"retrieve"`.
`id`	string	Opcional	ID de la tarea (aparece en el campo `task_id` de cada sobre de render/extract).
`trace_id`	string	Opcional	ID de la cadena de llamadas (campo `trace_id` del sobre).

Se debe proporcionar id o trace_id.

`action: "retrieve_batch"` — Consulta por lotes

Campo	Tipo	Requerido	Descripción
`action`	const	✅	Fijo `"retrieve_batch"`.
`ids`	string[]	Opcional	Lista de IDs de tareas.
`trace_ids`	string[]	Opcional	Lista de IDs de cadenas de llamadas.
`offset`	number	❌	Desplazamiento de paginación (por defecto 0).
`limit`	number	❌	Tamaño de página, 1–100 (por defecto 50).

Se debe proporcionar ids o trace_ids.

Respuesta individual

{
  "task": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "trace_id": "550e8400-e29b-41d4-a716-446655440001",
    "type": "extract",
    "created_at": 1777717800.05,
    "started_at": 1777717800.123,
    "finished_at": 1777717802.535,
    "elapsed": 2.412,
    "request": {
      "url": "https://en.wikipedia.org/wiki/Diffbot",
      "expected_type": "article"
    },
    "response": {
      "success": true,
      "data": { /* sobre completo de extract */ }
    }
  }
}

Si no se encuentra, se devuelve { "task": null } (HTTP 200, no 404). Los campos de tiempo del objeto task se describen a continuación.

created_at, hora de creación de la tarea, marca de tiempo Unix (segundos, flotante).
started_at, hora de inicio de ejecución de la tarea, marca de tiempo Unix (segundos, flotante). Será null si la tarea aún no ha comenzado.
finished_at, hora de finalización de la tarea, marca de tiempo Unix (segundos, flotante). Será null si la tarea no ha finalizado.
elapsed, tiempo de ejecución de la tarea, en segundos (flotante, con 3 decimales). Será null si la tarea no ha finalizado.

Respuesta por lotes

{
  "tasks": [
    { /* misma estructura que .task */ },
    { /* ... */ }
  ],
  "offset": 0,
  "limit":  50
}

Los IDs inexistentes no generarán errores, simplemente estarán ausentes en tasks.

Ejemplo

Consulta individual por task_id

curl -X POST https://api.acedata.cloud/webextrator/tasks \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "retrieve",
    "id": "550e8400-e29b-41d4-a716-446655440000"
  }'

Consulta individual por trace_id

curl -X POST https://api.acedata.cloud/webextrator/tasks \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "retrieve",
    "trace_id": "550e8400-e29b-41d4-a716-446655440001"
  }'

Consulta por lotes

curl -X POST https://api.acedata.cloud/webextrator/tasks \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "retrieve_batch",
    "ids": [
      "550e8400-e29b-41d4-a716-446655440000",
      "550e8400-e29b-41d4-a716-446655440002"
    ],
    "limit": 50
  }'

Python (requests) — Sondeo hasta completar

import os, time, requests

API_KEY = os.environ["ACEDATA_API_KEY"]
BASE = "https://api.acedata.cloud"

# 1) Enviar extracción asíncrona
queue = requests.post(
    f"{BASE}/webextrator/extract",
    headers={"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"},
    json={"url": "https://example.com", "mode": "async"},
).json()

job_id = queue["jobId"]

# 2) Usar la API de Tasks para sondear hasta que la tarea esté completa
while True:
    r = requests.post(
        f"{BASE}/webextrator/tasks",
        headers={"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"},
        json={"action": "retrieve", "id": job_id},
    ).json()
    task = r.get("task")
    if task and task.get("finished_at"):
        print("Tiempo transcurrido", task["elapsed"], "segundos")
        print(task["response"]["data"]["title"])
        break
    time.sleep(2)

Node.js (fetch) — Obtener el sobre completo después de recibir la notificación

// En tu función de manejo de callback_url:
app.post('/hooks/webextrator', async (req, res) => {
  res.status(200).end();              // Acknowledge rápidamente

  const taskId = req.body?.task_id;
  if (!taskId) return;

  const fetchRes = await fetch('https://api.acedata.cloud/webextrator/tasks', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.ACEDATA_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ action: 'retrieve', id: taskId }),
  });
  const { task } = await fetchRes.json();
  console.log('Sobre completo:', task.response.data);
});

Respuestas de error

HTTP	`error.code`	Significado
400	`bad_request`	Fallo de validación (falta `action`, se envían `id` y `trace_id` al mismo tiempo, etc.).
401	`unauthorized`	Falta o es inválido `Authorization: Bearer …`.

{ "error": { "code": "bad_request", "message": "..." } }

Consejos y advertencias

Puedes personalizar trace_id, así que hazlo. En la solicitud original de render/extract, sube ?trace_id=… (QueryString), alinéalo con tu propio ID de negocio (como el ID de ejecución del flujo de trabajo, etc.), y luego podrás consultar la tarea usando el ID de negocio. Si no se proporciona, el servidor generará automáticamente un UUID.
Período de retención de 7 días. Las tareas más antiguas devolverán task: null — si necesitas archivar a largo plazo, por favor almacénalo tú mismo.
La consulta de tareas es gratuita. Puedes consultar tantas veces como desees, el costo de la llamada original de render/extract ya ha sido pagado.
Prioriza el uso de asincronía + callbacks, en lugar de polling. Si el negocio lo permite, en la solicitud original incluye callback_url, para que la plataforma te envíe el envelope, lo cual es más eficiente que hacer polling cada 2 segundos.

Primeros pasos

Chat de IA

Imagen de IA

Video de IA

Audio de IA

Web y datos

CAPTCHA

Identidad

Proxy

Avanzado

Guía de integración de la API de consulta de tareas de WebExtrator

Autenticación

Parámetros de solicitud

`action: "retrieve"` — Consulta individual

`action: "retrieve_batch"` — Consulta por lotes

Respuesta individual

Respuesta por lotes

Ejemplo

Consulta individual por task_id

Consulta individual por trace_id

Consulta por lotes

Python (requests) — Sondeo hasta completar

Node.js (fetch) — Obtener el sobre completo después de recibir la notificación

Respuestas de error

Consejos y advertencias

​Autenticación

​Parámetros de solicitud

​action: "retrieve" — Consulta individual

​action: "retrieve_batch" — Consulta por lotes

​Respuesta individual

​Respuesta por lotes

​Ejemplo

​Consulta individual por task_id

​Consulta individual por trace_id

​Consulta por lotes

​Python (requests) — Sondeo hasta completar

​Node.js (fetch) — Obtener el sobre completo después de recibir la notificación

​Respuestas de error

​Consejos y advertencias

Autenticación

Parámetros de solicitud

`action: "retrieve"` — Consulta individual

`action: "retrieve_batch"` — Consulta por lotes

Respuesta individual

Respuesta por lotes

Ejemplo

Consulta individual por task_id

Consulta individual por trace_id

Consulta por lotes

Python (requests) — Sondeo hasta completar

Node.js (fetch) — Obtener el sobre completo después de recibir la notificación

Respuestas de error

Consejos y advertencias