Cómo recuperar trabajos de lectura masiva en Zoho

Recuperar un trabajo de lectura masiva en Zoho CRM te permite comprobar el estado y los resultados de una exportación masiva de datos enviada previamente, consultando el trabajo mediante su ID único.

Por qué es importante

Cuando exportas grandes volúmenes de registros de CRM usando la API de lectura masiva, el trabajo se ejecuta de forma asíncrona — es decir, lo envías y luego necesitas consultar periódicamente su finalización. Saber cómo recuperar un trabajo de lectura masiva específico te permite monitorizar el progreso, confirmar el éxito y obtener los datos resultantes. Esto es esencial para cualquier integración o automatización que dependa de exportaciones masivas de CRM.

> Nota: Beam Help es un recurso de soporte experto independiente — no es el soporte oficial de Zoho.

---

Paso a paso

Paso 1. Asegúrate de que tu token OAuth incluye el scope de lectura masiva correcto.

Antes de realizar cualquier llamada a la API masiva, confirma que tus credenciales OAuth de Zoho CRM incluyen el scope ZohoCRM.bulk.ALL. Sin este permiso, las solicitudes a los endpoints masivos serán rechazadas. ^[2]

Paso 2. Obtén el ID del trabajo a partir de un trabajo de lectura masiva creado previamente.

Un trabajo de lectura masiva se crea enviando una solicitud POST a /bulk/v1/read con el payload de configuración adecuado. La respuesta de esa llamada de creación incluirá un ID de trabajo (jid) que necesitarás para la recuperación. ^[5]

Paso 3. Llama al endpoint GET con el ID del trabajo.

Para recuperar el estado y los detalles de un trabajo de lectura masiva específico, envía una solicitud GET al siguiente endpoint:

GET /bulk/v1/read/{jid}

Reemplaza {jid} con el ID de trabajo real devuelto cuando se creó el trabajo. ^[1]

Paso 4. Usa el método getbulkread_job en tu integración.

Si trabajas con un cliente de Zoho CRM basado en Python, la llamada de recuperación está encapsulada en un método dedicado. Pasa el ID del trabajo como parámetro de cadena — el método construye internamente la ruta del endpoint correcta y ejecuta la solicitud: ^[1]

def get_bulk_read_job(self, jid: str):
    return self.c.request("GET", f"/bulk/v1/read/{jid}")

Paso 5. Gestiona la llamada a la herramienta mediante el tool getbulkread_job (si usas un flujo de trabajo asistido por IA).

Si utilizas una capa de integración de Zoho asistida por IA, el nombre de la herramienta a invocar es getbulkreadjob, que pertenece al servicio crm. Pasa el ID del trabajo usando la clave de parámetro jobid en el payload de tu llamada a la herramienta. ^[3]

Paso 6. Asegúrate de que tu token de acceso es válido antes de realizar la solicitud.

La API de Zoho CRM devolverá un error 401 si tu token de acceso ha expirado. Un cliente bien implementado debería refrescar automáticamente el token usando el refresh token almacenado antes de realizar la solicitud — normalmente con un margen de unos 120 segundos antes de la expiración para evitar fallos durante la solicitud. ^[8]

---

Errores comunes

• Scope ZohoCRM.bulk.ALL ausente: Si este scope no se incluyó cuando se autorizó por primera vez la conexión OAuth, las llamadas a los endpoints masivos fallarán con un error de permisos. Deberás volver a autorizar la conexión con los scopes correctos incluidos. ^[2]

• Uso de un ID de trabajo inválido o caducado: El parámetro de ruta {jid} debe coincidir exactamente con el ID devuelto en la llamada original de creación del trabajo. Pasar un ID de trabajo incorrecto o expirado resultará en un error de no encontrado. [^1, ^5]

• Tokens de acceso expirados: Si tu integración no gestiona la renovación del token automáticamente, las llamadas a /bulk/v1/read/{jid} pueden fallar con errores de autenticación. Implementa lógica de renovación proactiva del token para evitarlo. ^[8]

---

Qué verificar

• Confirmación del scope: Verifica que ZohoCRM.bulk.ALL esté presente en la lista de scopes de tu token OAuth activo antes de realizar la llamada de recuperación. ^[2]
• Exactitud del ID del trabajo: Compara el jid que estás pasando con la respuesta de tu llamada original de creación del trabajo POST /bulk/v1/read para asegurarte de que coinciden. ^[5]
• Validez del token: Confirma que tu token de acceso está vigente y que tu cliente está configurado para renovarlo automáticamente cuando se aproxime a su expiración. ^[8]