Come recuperare i casi in Zoho

Il recupero dei casi in Zoho Desk richiede una connessione OAuth valida, un ID organizzazione risolto e il client API corretto inizializzato per il tipo di app desk — tutto ciò viene gestito automaticamente dalla nostra integrazione una volta stabilita la connessione.

Perché è importante

I casi di Zoho Desk (ticket di supporto) risiedono in un contesto organizzativo specifico, quindi qualsiasi chiamata di recupero deve includere il corretto org_id insieme a un token di accesso attivo. Se il token è scaduto o l'ID organizzazione non è mai stato memorizzato, la chiamata API fallirà silenziosamente o restituirà un errore di autorizzazione. Comprendere l'intero flusso aiuta a diagnosticare i problemi rapidamente — e come Beam Help (supporto esperto indipendente per Zoho, non supporto ufficiale Zoho), vogliamo rendere questo flusso trasparente.

Procedura passo dopo passo

Passaggio 1. Verifica che esista un record di connessione Zoho per il tuo account utente. Il sistema cerca le tue credenziali nella tabella zohoconnections utilizzando il tuo userid. Se non viene trovato alcun record, il processo di recupero non può iniziare e viene restituito immediatamente None — sarà necessario riconnettersi tramite OAuth prima di procedere. ^[2]

Passaggio 2. Assicurati che il tuo token di accesso sia ancora valido. Il livello di connessione verifica se il tempo corrente è entro 120 secondi dal valore tokenexpiresat memorizzato. In caso affermativo, viene attivato un aggiornamento proattivo utilizzando il tuo refreshtoken prima che vengano richiesti i dati dei casi, riducendo la possibilità di un errore 401 a metà richiesta. Il accesstoken aggiornato e la nuova scadenza vengono riscritti automaticamente nel database. ^[2]

Passaggio 3. Inizializza il client API con apptype impostato su "desk". Questo indica al sistema di istanziare un ZohoDeskClient anziché la variante CRM. Il client viene costruito utilizzando il tuo apidomain memorizzato, il accesstoken corrente, il tuo deskorgid e un callback tokenrefresher che può ottenere silenziosamente un nuovo token durante la sessione se necessario. ^[1]

Passaggio 4. Consenti al sistema di rilevare automaticamente il tuo ID organizzazione se non è già memorizzato. Quando deskorgid è vuoto, l'integrazione chiama getallorganizations e legge il campo id dal primo elemento nella lista data restituita. Questo valore rilevato viene quindi salvato in modo che le chiamate future saltino completamente il passaggio di rilevamento. ^[1]

Passaggio 5. Con il client pronto, esegui la chiamata allo strumento di recupero dei casi. Nel flusso di chat o di pianificazione, il nome dello strumento appropriato (ad esempio getrecords che punta al modulo Cases) viene passato a executetoolwithrepair, che esegue la query e restituisce risultati strutturati. Il sistema emette inoltre un messaggio di stato come "Calling Zoho tool: <toolname>..." in modo da poter confermare che la chiamata è in corso. [^3,5]

Passaggio 6. Esamina il payload restituito. I risultati positivi vengono restituiti come dizionario contenente i record dei casi. Il sistema costruisce inoltre link contestuali utilizzando i valori dc (data center), deskorgid e desk_portal in modo da poter navigare direttamente ai record corrispondenti nell'interfaccia di Zoho Desk. ^[3]

Passaggio 7. Se stai testando il flusso di recupero direttamente (bypassando l'interfaccia di chat), il percorso di chiamata diretta recupera il record di connessione creato più di recente dal database e costruisce la propria closure token_refresher prima di invocare lo strumento. Verifica che esista almeno una riga di connessione prima di eseguire test diretti. ^[4]

Problemi comuni

• orgid mancante: Se deskorg_id è una stringa vuota e anche la chiamata di rilevamento automatico fallisce (ad esempio, a causa di scope OAuth insufficienti), ogni successiva chiamata all'API Desk verrà rifiutata. Verifica che i tuoi scope OAuth includano l'accesso all'endpoint delle organizzazioni Desk. ^[1]
• Refresh token scaduto: Il metodo refreshtokens si aspetta un refreshtoken valido nel corpo della richiesta insieme al tuo clientid e clientsecret. Se il refresh token è stato revocato (ad esempio, l'utente ha ri-autorizzato da una sessione diversa), la risposta conterrà una chiave error anziché access_token, e la connessione verrà contrassegnata come inutilizzabile. ^[6]
• apptype errato: Passare apptype="crm" quando si intende recuperare i casi Desk istanzierà il client CRM, e gli endpoint specifici per i casi non saranno disponibili. Verifica sempre che il parametro app_type corrisponda al prodotto che stai interrogando. ^[1]
• Nessuna riga di connessione nei test diretti: Il test harness a chiamata diretta seleziona la riga di connessione inserita più di recente. Se il database è vuoto o la riga è stata eliminata, la chiamata restituisce immediatamente {"error": "No Zoho connection found"}. ^[4]

Cosa verificare

• Verifica che zohoconnections contenga una riga per il tuo utente con un deskorgid non vuoto e un valore tokenexpires_at nel futuro. [^1,2]
• Conferma che i tuoi scope OAuth siano stati concessi con accesstype=offline e prompt=consent in modo che un refreshtoken sia incluso nella risposta iniziale di scambio del token. ^[6]
• Dopo un recupero riuscito, verifica che il payload restituito contenga una lista data con almeno un oggetto caso, e che i link Desk generati facciano riferimento al sottodominio desk_portal corretto per il tuo account. ^[3]