Comment récupérer des tâches de lecture en masse dans Zoho

La récupération d'une tâche de lecture en masse dans Zoho CRM vous permet de vérifier le statut et les résultats d'un export de données en masse précédemment soumis, en interrogeant la tâche à l'aide de son identifiant unique.

Pourquoi c'est important

Lorsque vous exportez de grands volumes d'enregistrements CRM via l'API de lecture en masse, la tâche s'exécute de manière asynchrone — ce qui signifie que vous la soumettez, puis devez interroger l'API pour en connaître l'avancement. Savoir comment récupérer une tâche de lecture en masse spécifique vous permet de surveiller sa progression, de confirmer son succès et de récupérer les données résultantes. Cela est indispensable pour toute intégration ou automatisation qui dépend des exports CRM en masse.

> Remarque : Beam Help est une ressource d'assistance experte indépendante — et non le support officiel de Zoho.

---

Étape par étape

Étape 1. Assurez-vous que votre jeton OAuth inclut le scope bulk approprié.

Avant d'effectuer tout appel à l'API bulk, vérifiez que vos identifiants OAuth Zoho CRM incluent le scope ZohoCRM.bulk.ALL. Sans cette permission, les requêtes vers les endpoints bulk seront rejetées. ^[2]

Étape 2. Obtenez l'identifiant de tâche à partir d'une tâche de lecture en masse précédemment créée.

Une tâche de lecture en masse est créée en envoyant une requête POST vers /bulk/v1/read avec le payload de configuration approprié. La réponse de cet appel de création inclura un identifiant de tâche (jid) dont vous aurez besoin pour la récupération. ^[5]

Étape 3. Appelez l'endpoint GET avec l'identifiant de tâche.

Pour récupérer le statut et les détails d'une tâche de lecture en masse spécifique, envoyez une requête GET vers l'endpoint suivant :

GET /bulk/v1/read/{jid}

Remplacez {jid} par l'identifiant de tâche réel retourné lors de la création de la tâche. ^[1]

Étape 4. Utilisez la méthode getbulkread_job dans votre intégration.

Si vous travaillez avec un client Zoho CRM basé sur Python, l'appel de récupération est encapsulé dans une méthode dédiée. Passez l'identifiant de tâche en tant que paramètre de type chaîne — la méthode construit en interne le chemin d'endpoint correct et exécute la requête : ^[1]

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

Étape 5. Gérez l'appel d'outil via l'outil getbulkread_job (si vous utilisez un workflow assisté par IA).

Si vous utilisez une couche d'intégration Zoho assistée par IA, le nom de l'outil à invoquer est getbulkreadjob, qui appartient au service crm. Passez l'identifiant de tâche en utilisant la clé de paramètre jobid dans le payload de votre appel d'outil. ^[3]

Étape 6. Assurez-vous que votre jeton d'accès est valide avant d'effectuer la requête.

L'API Zoho CRM retournera une erreur 401 si votre jeton d'accès a expiré. Un client bien implémenté devrait automatiquement renouveler le jeton en utilisant le jeton de rafraîchissement stocké avant que la requête ne soit effectuée — généralement avec une marge d'environ 120 secondes avant l'expiration, afin d'éviter les échecs en cours de requête. ^[8]

---

Erreurs courantes

• Scope ZohoCRM.bulk.ALL manquant : Si ce scope n'a pas été inclus lors de la première autorisation de la connexion OAuth, les appels aux endpoints bulk échoueront avec une erreur de permissions. Vous devrez réautoriser la connexion en incluant les scopes corrects. ^[2]

• Utilisation d'un identifiant de tâche invalide ou obsolète : Le paramètre de chemin {jid} doit correspondre exactement à l'identifiant retourné lors de l'appel de création de tâche d'origine. Passer un identifiant de tâche incorrect ou expiré entraînera une erreur de type « non trouvé ». [^1, ^5]

• Jetons d'accès expirés : Si votre intégration ne gère pas le renouvellement automatique des jetons, les appels vers /bulk/v1/read/{jid} peuvent échouer avec des erreurs d'authentification. Implémentez une logique de renouvellement proactif des jetons pour éviter ce problème. ^[8]

---

Ce qu'il faut vérifier

• Confirmation du scope : Vérifiez que ZohoCRM.bulk.ALL est présent dans la liste des scopes de votre jeton OAuth actif avant d'effectuer l'appel de récupération. ^[2]
• Exactitude de l'identifiant de tâche : Comparez le jid que vous transmettez avec la réponse de votre appel de création de tâche POST /bulk/v1/read d'origine pour vous assurer qu'ils correspondent. ^[5]
• Validité du jeton : Confirmez que votre jeton d'accès est à jour et que votre client est configuré pour le renouveler automatiquement lorsqu'il approche de son expiration. ^[8]