Come recuperare i job di lettura massiva in Zoho

Recuperare un job di lettura massiva in Zoho CRM ti consente di verificare lo stato e i risultati di un'esportazione dati massiva precedentemente inviata, interrogando il job tramite il suo ID univoco.

Perché è importante

Quando esporti grandi volumi di record CRM utilizzando l'API di lettura massiva, il job viene eseguito in modo asincrono — il che significa che lo invii e poi devi eseguire il polling per verificarne il completamento. Sapere come recuperare uno specifico job di lettura massiva ti permette di monitorare l'avanzamento, confermare il successo e ottenere i dati risultanti. Questo è essenziale per qualsiasi integrazione o automazione che dipende dalle esportazioni CRM massive.

> Nota: Beam Help è una risorsa di supporto esperto indipendente — non è il supporto ufficiale di Zoho.

---

Passo dopo passo

Passo 1. Assicurati che il tuo token OAuth includa lo scope bulk corretto.

Prima di effettuare qualsiasi chiamata all'API bulk, verifica che le credenziali OAuth di Zoho CRM includano lo scope ZohoCRM.bulk.ALL. Senza questo permesso, le richieste agli endpoint bulk verranno rifiutate. ^[2]

Passo 2. Ottieni l'ID del job da un job di lettura massiva creato in precedenza.

Un job di lettura massiva viene creato inviando una richiesta POST a /bulk/v1/read con il payload di configurazione appropriato. La risposta a quella chiamata di creazione includerà un ID job (jid) necessario per il recupero. ^[5]

Passo 3. Chiama l'endpoint GET con l'ID del job.

Per recuperare lo stato e i dettagli di uno specifico job di lettura massiva, invia una richiesta GET al seguente endpoint:

GET /bulk/v1/read/{jid}

Sostituisci {jid} con l'ID job effettivo restituito al momento della creazione del job. ^[1]

Passo 4. Utilizza il metodo getbulkread_job nella tua integrazione.

Se stai lavorando con un client Zoho CRM basato su Python, la chiamata di recupero è racchiusa in un metodo dedicato. Passa l'ID job come parametro stringa — il metodo costruisce internamente il percorso endpoint corretto ed esegue la richiesta: ^[1]

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

Passo 5. Gestisci la chiamata tramite lo strumento getbulkread_job (se utilizzi un flusso di lavoro assistito da AI).

Se stai utilizzando un livello di integrazione Zoho assistito da AI, il nome dello strumento da invocare è getbulkreadjob, che appartiene al servizio crm. Passa l'ID job utilizzando la chiave parametro jobid nel payload della chiamata allo strumento. ^[3]

Passo 6. Assicurati che il tuo token di accesso sia valido prima di effettuare la richiesta.

L'API di Zoho CRM restituirà un errore 401 se il tuo token di accesso è scaduto. Un client ben implementato dovrebbe aggiornare automaticamente il token utilizzando il refresh token memorizzato prima che la richiesta venga effettuata — tipicamente con un margine di circa 120 secondi prima della scadenza per evitare errori a metà richiesta. ^[8]

---

Errori comuni

• Scope ZohoCRM.bulk.ALL mancante: Se questo scope non è stato incluso al momento della prima autorizzazione della connessione OAuth, le chiamate agli endpoint bulk falliranno con un errore di permessi. Sarà necessario ri-autorizzare la connessione includendo gli scope corretti. ^[2]

• Utilizzo di un ID job non valido o obsoleto: Il parametro di percorso {jid} deve corrispondere esattamente all'ID restituito dalla chiamata di creazione del job originale. Passare un ID job errato o scaduto risulterà in un errore di risorsa non trovata. [^1, ^5]

• Token di accesso scaduti: Se la tua integrazione non gestisce automaticamente il rinnovo del token, le chiamate a /bulk/v1/read/{jid} potrebbero fallire con errori di autenticazione. Implementa una logica di rinnovo proattivo del token per evitare questo problema. ^[8]

---

Cosa verificare

• Conferma dello scope: Verifica che ZohoCRM.bulk.ALL sia presente nell'elenco degli scope del tuo token OAuth attivo prima di effettuare la chiamata di recupero. ^[2]
• Accuratezza dell'ID job: Confronta il jid che stai passando con la risposta della tua chiamata originale di creazione job POST /bulk/v1/read per assicurarti che corrispondano. ^[5]
• Validità del token: Conferma che il tuo token di accesso sia aggiornato e che il tuo client sia configurato per rinnovarlo automaticamente quando si avvicina alla scadenza. ^[8]