Come aggiornare i record in Zoho

L'aggiornamento dei record in Zoho richiede una connessione OAuth valida e attiva con gli scope corretti — una volta configurati, il flusso di aggiornamento gestisce automaticamente il rinnovo del token e scrive le modifiche in CRM o Desk.

Perché è importante

Che tu stia sincronizzando i dettagli dei contatti, chiudendo ticket o modificando i dati dei lead, gli aggiornamenti programmatici dei record dipendono da un token OAuth attivo e dagli scope di autorizzazione corretti. Se il token è scaduto o gli scope sono troppo limitati, le chiamate di aggiornamento falliranno silenziosamente o restituiranno errori 401. Comprendere il funzionamento del livello di connessione ti aiuta a diagnosticare e risolvere questi problemi rapidamente.

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

---

Procedura passo dopo passo

Passaggio 1. Verifica che la connessione OAuth esista e contenga un token valido.

Prima che qualsiasi aggiornamento di record possa avere successo, il sistema deve trovare una connessione memorizzata per il tuo utente. La connessione viene cercata in una tabella locale zohoconnections utilizzando il tuo userid. Se non viene trovata alcuna riga, il client API non può essere inizializzato e tutte le chiamate successive falliranno.^[3]

Passaggio 2. Consenti l'esecuzione del ciclo di rinnovo del token.

I token vengono rinnovati in modo proattivo quando il momento attuale è entro 120 secondi dal valore tokenexpiresat memorizzato. Un rinnovo riuscito scrive il nuovo accesstoken e il tokenexpiresat aggiornato nella riga zohoconnections, in modo che la chiamata successiva utilizzi sempre una credenziale aggiornata.^[3] Se il rinnovo stesso fallisce (ad esempio, il refresh_token è mancante o revocato), la funzione restituisce None e nessun aggiornamento verrà eseguito.^[1]

Passaggio 3. Verifica che gli scope OAuth corretti siano stati concessi.

Per gli aggiornamenti dei record di Zoho CRM, la concessione OAuth deve includere ZohoCRM.modules.ALL o lo scope UPDATE equivalente a livello di modulo. Per Zoho Desk, gli scope rilevanti includono Desk.tickets.UPDATE, Desk.contacts.UPDATE, Desk.tasks.UPDATE e autorizzazioni UPDATE simili per ogni oggetto.^[5] Se questi scope non sono stati richiesti durante l'autorizzazione OAuth originale, sarà necessario ri-autorizzare e includerli esplicitamente.

Passaggio 4. Inizializza il client API corretto per il tuo prodotto.

Passa apptype="crm" per puntare a Zoho CRM, oppure apptype="desk" per puntare a Zoho Desk. Per Desk, è richiesto anche un orgid — se non è già memorizzato, il sistema chiamerà getallorganizations per individuarlo e salvarlo automaticamente.^[1] Per CRM, viene costruito un ZohoCrmClient utilizzando l'apidomain e l'access_token memorizzati, con il callback di rinnovo del token collegato.^[4]

Passaggio 5. Esegui lo strumento di aggiornamento con l'ID del record di destinazione e i campi modificati.

Once il client API è pronto, chiama execute_tool con il nome dello strumento di aggiornamento appropriato e un oggetto params che include l'id del record e i campi che desideri modificare. Il livello di esecuzione tenterà la chiamata e, se nel risultato viene restituita una domanda di chiarimento o un errore, quel messaggio viene mostrato direttamente in modo che tu possa correggere il payload e riprovare.^[8]

Passaggio 6. Verifica che i metadati della connessione siano aggiornati dopo un callback di autenticazione.

Se hai ri-autorizzato di recente, controlla che il callback di autenticazione abbia scritto correttamente l'accesstoken, il refreshtoken, l'apidomain e il tokenexpiresat più recenti in zohoconnections. Il callback esegue un upsert — aggiornando la riga esistente se ne viene trovata una, oppure inserendone una nuova — e memorizza anche crmorgid per la tenancy CRM.^[2]

---

Errori comuni

• orgid mancante per le chiamate Desk. Se deskorg_id è vuoto o contiene solo spazi, il client viene comunque costruito, ma la prima chiamata API attiva una ricerca automatica. Se anche quella ricerca fallisce (ad esempio, a causa di un gap di scope su Desk.basic.READ), tutti i successivi aggiornamenti Desk restituiranno errori.^[1]
• Il rinnovo del token non restituisce alcun accesstoken. Se ZohoOAuth.refreshtokens risponde senza una chiave access_token, il refresher restituisce None e il token obsoleto rimane in uso, causando errori 401 nelle chiamate di aggiornamento.^[1][3]
• Gap di scope dalla concessione originale. Gli scope vengono impostati al momento dell'autorizzazione. Aggiungere scope UPDATE al file di configurazione non aggiorna retroattivamente una concessione esistente — l'utente deve completare un nuovo flusso OAuth.^[5]
• Blocco SQLite durante aggiornamenti concorrenti. Le operazioni di backfill o migrazione che aggiornano zoho_connections devono utilizzare una singola connessione/transazione per evitare conflitti di blocco.^[6]

---

Cosa verificare

• Controlla che la riga zohoconnections per il tuo userid abbia un refreshtoken non nullo e che tokenexpires_at sia un timestamp Unix valido.^[3]
• Verifica che la tua concessione OAuth includa lo scope UPDATE rilevante per il modulo che stai puntando (ad esempio, ZohoCRM.modules.ALL per CRM, Desk.tickets.UPDATE per i ticket Desk).^[5]
• Dopo qualsiasi ri-autorizzazione, controlla che l'apidomain memorizzato in zohoconnections contenga zohoapis. in modo che il data center venga correttamente dedotto per le successive chiamate API.^[2]