Come ottenere gli utenti in Zoho

Recuperare gli utenti in Zoho CRM tramite OAuth richiede un access token valido e una chiamata all'endpoint user-info di Zoho Accounts — ecco esattamente come funziona questo flusso, dalla configurazione delle credenziali fino al parsing della risposta.

Perché è importante

Quando si creano integrazioni o strumenti interni su Zoho CRM, è spesso necessario identificare *chi* è autenticato — il loro ID utente, indirizzo email e dettagli dell'organizzazione — prima di effettuare qualsiasi chiamata all'API CRM. Sbagliare questo passaggio porta a errori 401, org ID non corrispondenti e logica multi-tenant non funzionante. Comprendere l'intero flusso di callback OAuth e di recupero delle informazioni utente consente di risparmiare molto tempo in fase di debug.

> Beam Help è un servizio di supporto esperto indipendente per Zoho — non siamo il supporto ufficiale Zoho.

---

Passo dopo passo

Passaggio 1. Registra la tua applicazione nella Zoho API Console e raccogli le credenziali necessarie. Accedi alla API Console, crea una Server-based Application, imposta il tuo redirect URI (ad es. http://localhost:8080/api/auth_callback) e annota il Client ID e il Client Secret. Nella selezione degli scope OAuth, includi almeno ZohoCRM.users.ALL, ZohoCRM.modules.ALL e ZohoCRM.settings.ALL. ^[7]

Passaggio 2. Configura il tuo ambiente. Crea un file .env nella root del progetto e popolalo con ZOHOCLIENTID, ZOHOCLIENTSECRET e, facoltativamente, ZOHO_DC (valori accettati: com, eu, in, com.au, jp — il valore predefinito è com). Il valore del data centre determina quale endpoint regionale viene chiamato nei passaggi successivi. ^[7]

Passaggio 3. Gestisci il callback OAuth nel tuo server. Quando Zoho reindirizza alla tua route di callback, estrai il parametro code dalla query string. Passa quel codice al tuo handler OAuth (ZohoOAuth.handleoauthcallback(code)), che lo scambia con un access token e un refresh token. Se la risposta non contiene la chiave access_token, mostra immediatamente l'errore anziché procedere. ^[6]

Passaggio 4. Chiama l'endpoint user-info di Zoho Accounts per recuperare i dettagli dell'utente autenticato. Costruisci l'URL come segue:

https://accounts.zoho.<DC>/oauth/user/info

Invia una richiesta GET con un header Authorization: Bearer <access_token>. La risposta JSON contiene i campi necessari per identificare l'utente. ^[1]

Passaggio 5. Analizza la risposta con attenzione — i nomi dei campi variano in base al data centre. Estrai l'ID utente da ZUID e l'email da Email. Per l'ID organizzazione, prova prima orgid, poi organizationid, poi ZGID; se nessuno è presente (organizzazioni con un solo utente), usa come fallback il valore di ZUID stesso. Per il nome dell'organizzazione, controlla companyname, poi organizationname, poi Company_Name; se tutti sono assenti, ricava un fallback dalla parte del dominio dell'indirizzo email. ^[1]

Passaggio 6. Salva l'utente e l'organizzazione. Usa zohouserid per cercare un record utente esistente; creane uno se non esiste. Separatamente, chiama getorcreateorganization con i valori zohoorgid e orgname, quindi collega l'utente a quell'organizzazione tramite updateuserorg. Memorizza orgid nella sessione insieme a userid per supportare scenari multi-tenant. ^[6]

Passaggio 7. Salva i token di connessione. Memorizza accesstoken, refreshtoken, apidomain, tokenexpiresat e dc nella tua tabella zohoconnections, indicizzata per user_id. Se esiste già un record di connessione per quell'utente, aggiornalo; altrimenti inserisci una nuova riga. ^[8]

Passaggio 8. Nelle richieste successive, recupera la connessione memorizzata e aggiorna proattivamente l'access token se mancano meno di 120 secondi alla scadenza. Dopo un aggiornamento riuscito, aggiorna sia accesstoken che tokenexpires_at nel database prima di procedere con qualsiasi chiamata all'API di Zoho CRM. ^[2]

Passaggio 9. Per verificare in qualsiasi momento lo stato dell'utente attualmente autenticato, interroga la tua tabella users tramite session["userid"] e la tabella zohoconnections tramite user_id. Restituisci connected: true solo quando esiste una riga di connessione, insieme all'indirizzo email memorizzato. ^[4]

---

Errori comuni

• Data centre errato. Se ZOHODC è impostato su com ma i tuoi utenti si trovano sul data centre EU o IN, l'URL user-info restituirà un errore o una risposta vuota. Ricava sempre il DC dall'apidomain restituito nel callback OAuth (cerca il segmento dopo zohoapis.) e salvalo. ^[8]
• Campi org ID mancanti. Il nome del campo dell'ID organizzazione non è coerente tra i data centre di Zoho. Non provare tutte e tre le varianti (orgid, organizationid, ZGID) prima del fallback causerà l'utilizzo silenzioso dell'identificatore errato nella logica di creazione dell'organizzazione. ^[1]
• Scadenza del token durante una richiesta. Gli access token scadono dopo circa 3600 secondi. Senza un aggiornamento proattivo (il buffer di tolleranza di 120 secondi), le operazioni di lunga durata incontreranno errori 401 a metà esecuzione. ^[2]
• Caso limite: organizzazione con un solo utente. Per gli account senza un'organizzazione formale, nessuno dei campi org ID potrebbe essere popolato. Il fallback sicuro è utilizzare ZUID come identificatore dell'organizzazione, in modo che la logica di creazione dell'organizzazione a valle non fallisca. ^[1]

---

Cosa verificare

• Gli scope sono corretti: Verifica che ZohoCRM.users.ALL sia incluso nell'elenco degli scope dell'applicazione registrata; gli scope mancanti limitano silenziosamente ciò che l'endpoint user-info restituisce. ^[7]
• Il DC è salvato correttamente: Dopo il callback OAuth, verifica che la colonna dc in zoho_connections corrisponda al dominio regionale effettivo dell'account Zoho dell'utente autenticato. ^[8]
• Il refresh del token funziona: Dopo aver memorizzato una connessione, simula uno scenario di prossima scadenza e verifica che getzohoconnection restituisca un access_token valido e aggiornato anziché uno scaduto. ^[2]