Per recuperare una timeline in Zoho è necessario un token di accesso OAuth valido e una connessione correttamente configurata all'API di Zoho — una volta che questi elementi sono in ordine, la tua integrazione può chiamare gli strumenti pertinenti per ottenere i dati della timeline per qualsiasi modulo supportato.
Perché è importante
I dati della timeline offrono una visione cronologica delle attività relative a un record — utile per verificare le modifiche, esaminare la cronologia delle comunicazioni o creare report. Se il token di accesso è scaduto o la connessione è configurata in modo errato, qualsiasi tentativo di recuperare informazioni sulla timeline fallirà silenziosamente o restituirà un errore 401. Comprendere il funzionamento del livello di autenticazione è quindi un prerequisito prima di effettuare qualsiasi chiamata di recupero dati.
> Nota: Beam Help è un servizio di supporto esperto indipendente per Zoho — non siamo il supporto ufficiale di Zoho.
---
Procedura passo dopo passo
Passaggio 1. Stabilisci la connessione OAuth.
Prima di tutto, la tua applicazione deve completare il flusso OAuth. L'URL di autorizzazione viene costruito utilizzando il tuo clientid, redirecturi, gli scope configurati e i parametri responsetype=code, accesstype=offline e prompt=consent. Una volta che l'utente approva, Zoho reindirizza con un codice di autorizzazione. [7]
Passaggio 2. Scambia il codice di autorizzazione con i token.
Invia una richiesta POST del codice di autorizzazione all'endpoint token di Zoho utilizzando granttype=authorizationcode insieme al tuo clientid, clientsecret e redirecturi. Una risposta positiva restituisce un accesstoken, un refreshtoken, un apidomain e un valore expires_in. Salva tutti questi dati — ti serviranno per ogni richiesta successiva. [7]
Passaggio 3. Mantieni la connessione e tieni traccia della scadenza.
Salva accesstoken, refreshtoken, tokenexpiresat (calcolato come tempo Unix corrente più expiresin) e apidomain nel tuo archivio dati. Il timestamp di scadenza è fondamentale: indica al sistema quando il token deve essere aggiornato prima di effettuare chiamate API. [1]
Passaggio 4. Aggiorna il token prima che scada.
Quando recuperi la connessione salvata, verifica se il tempo corrente è entro 120 secondi da tokenexpiresat. In tal caso, invia una richiesta POST all'endpoint token con granttype=refreshtoken, il tuo clientid, clientsecret e il refreshtoken salvato. In caso di successo, aggiorna accesstoken e tokenexpiresat salvati con i nuovi valori. Questo buffer di 120 secondi riduce il rischio di scadenza del token durante una richiesta. [2] [3]
Passaggio 5. Verifica che la connessione sia attiva prima di chiamare qualsiasi strumento.
Dopo l'esecuzione della logica di aggiornamento, verifica che esista un oggetto di connessione valido per l'utente. Se non viene trovata alcuna connessione — ad esempio perché l'utente non ha mai autorizzato o l'aggiornamento è fallito — mostra un prompt di riconnessione anziché procedere. Tentare di chiamare gli strumenti Zoho senza un token attivo produrrà una risposta di errore. [6]
Passaggio 6. Identifica lo strumento e il modulo corretti per il recupero della timeline.
Con una connessione valida a disposizione, determina quale strumento Zoho corrisponde ai dati della timeline per il modulo di destinazione (ad esempio, Contatti, Lead o Trattative in Zoho CRM). L'api_domain restituito durante lo scambio del token è l'URL base per tutte le chiamate API — utilizzalo quando costruisci il tuo ZohoCrmClient. Passa il nome dello strumento e i parametri richiesti (come module) al livello di esecuzione. [4]
Passaggio 7. Esegui la chiamata allo strumento.
Richiama lo strumento tramite il tuo livello di esecuzione API, fornendo il nome dello strumento e un dizionario di parametri. Il sistema chiamerà l'API di Zoho utilizzando il token di accesso corrente e restituirà il payload della timeline. Se il token è stato rinnovato durante la sessione, il callback di aggiornamento del token otterrà automaticamente uno nuovo e riproverà. [4] [5]
Passaggio 8. Gestisci la risposta.
Una chiamata riuscita restituisce i record della timeline come dati strutturati. Se la risposta contiene una chiave error, esamina il messaggio — le cause più comuni includono un token scaduto che non è stato aggiornato, un nome di modulo non valido o scope OAuth insufficienti. [3] [4]
---
Errori comuni
refreshtokenmancante negli scambi successivi. Zoho restituisce unrefreshtokensolo alla prima autorizzazione. Se lo perdi, l'utente deve autorizzare nuovamente dall'inizio. Salvalo sempre immediatamente dopo il primo scambio del codice. [7]- Scadenza del token non tracciata correttamente.
tokenexpiresatdeve essere impostato comeint(time.time()) + int(expires_in)nel momento in cui il token viene ricevuto — non nel momento in cui viene salvato. Qualsiasi ritardo tra la ricezione e il salvataggio causerà calcoli di scadenza prematuri. [1] [3] apidomainerrato utilizzato. L'apidomainnella risposta del token può variare in base al data center (ad es.,.com,.eu,.in). Usa sempre il dominio restituito nello scambio del token anziché codificare un URL in modo fisso. [7]- Incoerenza nel campo Org ID. Quando si recuperano le informazioni utente da
https://accounts.zoho.<DC>/oauth/user/info, l'ID organizzazione può comparire comeorgid,organizationidoZGIDa seconda del data center. Implementa una logica di fallback per gestire tutte le varianti. [1]
---
Cosa verificare
- Il token è valido e non è entro 120 secondi dalla scadenza prima di effettuare qualsiasi chiamata di recupero della timeline — verifica che la logica di aggiornamento sia stata eseguita correttamente e che il nuovo
access_tokensia stato salvato. [2] api_domaincorrisponde al data center dell'utente — verifica che il dominio salvato durante lo scambio del token venga utilizzato come URL base per tutte le richieste API di Zoho. [4] [7]- Gli scope OAuth richiesti sono inclusi — assicurati che gli scope configurati nell'URL di autorizzazione coprano l'accesso in lettura al modulo di cui stai interrogando la timeline. [7]