Come recuperare le notifiche in Zoho

Recuperare le notifiche in Zoho CRM tramite API richiede gli scope OAuth corretti e un token di accesso valido e aggiornato — se questi due elementi sono a posto, il resto viene da sé.

Perché è importante

Quando hai bisogno di leggere, creare, aggiornare o eliminare notifiche CRM in modo programmatico — ad esempio per costruire una dashboard di avvisi personalizzata o sincronizzare i dati delle notifiche con uno strumento di terze parti — devi assicurarti che il tuo client OAuth sia autorizzato con gli scope di autorizzazione corretti e che la tua pipeline di token gestisca la scadenza in modo appropriato. Senza questa base, ogni richiesta di notifica restituirà un errore 401 o un errore di autorizzazione prima ancora di raggiungere i dati.

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

---

Procedura passo dopo passo

Passaggio 1. Verifica che il tuo client OAuth includa gli scope specifici per le notifiche prima di generare o aggiornare qualsiasi token. I quattro scope necessari sono ZohoCRM.notifications.READ, ZohoCRM.notifications.CREATE, ZohoCRM.notifications.UPDATE e ZohoCRM.notifications.DELETE. Se vuoi solo recuperare (leggere) le notifiche, ZohoCRM.notifications.READ è lo scope minimo richiesto. ^[1]

Passaggio 2. Assicurati che sia presente anche il bundle di scope CRM più ampio. Gli scope per le notifiche si affiancano ad altri scope CRM come ZohoCRM.modules.ALL, ZohoCRM.org.ALL e ZohoCRM.coql.READ. Tutti questi devono essere dichiarati insieme quando registri o aggiorni il tuo client OAuth, in modo che un singolo token copra tutte le operazioni necessarie alla tua integrazione. ^[1]

Passaggio 3. Stabilisci una connessione valida per l'utente prima di effettuare qualsiasi chiamata relativa alle notifiche. Il tuo backend deve cercare il record di connessione memorizzato (token di accesso, token di aggiornamento, timestamp di scadenza) per l'utente in questione. Se non esiste alcun record, l'utente deve autenticarsi nuovamente tramite il flusso OAuth prima che qualsiasi chiamata API possa procedere. ^[3]

Passaggio 4. Implementa un aggiornamento proattivo del token in modo che il token di accesso sia sempre valido al momento della richiesta. Un pattern affidabile consiste nel verificare se il momento attuale è entro 120 secondi dal timestamp di scadenza del token — in tal caso, chiama immediatamente l'endpoint di aggiornamento, salva il nuovo accesstoken e il valore aggiornato di tokenexpires_at nel database, quindi procedi con la richiesta di notifica utilizzando il token aggiornato. ^[3]

Passaggio 5. Se è necessario un aggiornamento durante una richiesta (ad esempio, in un processo di lunga durata in cui il token scade a metà esecuzione), la logica di aggiornamento deve recuperare il refreshtoken più recente dal database, chiamare ZohoOAuth.refreshtokens(), verificare che accesstoken sia presente nella risposta e salvare i valori aggiornati prima di restituire il nuovo token al chiamante. Se accesstoken è assente dalla risposta di aggiornamento, considera l'aggiornamento come fallito e restituisci un errore anziché procedere con un token non aggiornato. ^[2]

Passaggio 6. Istanzia il client API di Zoho CRM utilizzando il token di accesso risolto e il dominio API corretto memorizzato nel record di connessione. Passa il callback di aggiornamento del token al client in modo che possa gestire automaticamente la scadenza durante operazioni di recupero notifiche paginate o multi-step. ^[2]

Passaggio 7. Con un client valido a disposizione, chiama lo strumento o l'endpoint appropriato per le notifiche. In un contesto di chat/agente, il livello di esecuzione degli strumenti lo gestisce come una chiamata a uno strumento con nome (ad es. uno strumento di tipo get_notifications), passa i parametri rilevanti e trasmette aggiornamenti di stato al chiamante mentre la richiesta è in corso. ^[6]

Passaggio 8. Gestisci il caso in cui l'oggetto API non possa essere inizializzato — ad esempio, se l'account Zoho dell'utente non è connesso o l'aggiornamento è fallito. In questo scenario, mostra un messaggio chiaro come "Zoho is not connected for this app. Please reconnect." anziché fallire silenziosamente o restituire dati vuoti. ^[4]

---

Errori comuni

• Scope delle notifiche mancanti al momento della registrazione. Se aggiungi ZohoCRM.notifications.READ alla tua configurazione ma il client OAuth era stato originariamente registrato senza di esso, i token di aggiornamento esistenti non includeranno il nuovo scope. Devi ri-autorizzare (ri-eseguire il flusso di consenso OAuth) per ottenere un token che includa il set di scope aggiornato. ^[1]

• Token non aggiornati che causano errori 401 silenziosi. Se la logica di aggiornamento si attiva solo *dopo* una richiesta fallita anziché *prima*, si verificheranno errori 401 intermittenti alla prima chiamata di una sessione. La finestra di aggiornamento preventivo di 120 secondi è progettata appositamente per prevenire questa race condition. ^[3]

• Token di aggiornamento non salvato nel database. Dopo un aggiornamento del token riuscito, sia accesstoken che tokenexpiresat devono essere riscritti nella tabella zohoconnections. Non salvare questi valori significa che la richiesta successiva tenterà di aggiornarsi nuovamente con lo stesso token di aggiornamento (possibilmente già consumato), il che può invalidare completamente la sessione. [^2, ^3]

• Utilizzo del valore errato per apptype. La funzione getzohoapi accetta un parametro apptype ("crm" o "desk"). Il recupero delle notifiche per Zoho CRM richiede app_type="crm". Passare "desk" instraderà la richiesta al client Zoho Desk, che utilizza un set di scope completamente diverso e un percorso di risoluzione dell'org-ID differente. ^[2]

---

Cosa verificare

• Gli scope sono presenti e attivi: Verifica che ZohoCRM.notifications.READ (e qualsiasi scope di scrittura necessario) compaia nel tuo client OAuth registrato *e* nel token attualmente utilizzato dalla tua applicazione — non solo nel file di configurazione. ^[1]
• L'aggiornamento del token viene salvato correttamente: Dopo qualsiasi evento di aggiornamento, interroga la tabella zohoconnections e conferma che accesstoken e tokenexpiresat riflettano i valori appena emessi, non quelli precedenti. ^[3]
• Il record di connessione esiste per l'utente: Prima di eseguire qualsiasi recupero di notifiche, verifica che esista una riga in zohoconnections per il userid di destinazione; se manca, il client API sarà None e tutte le chiamate successive falliranno silenziosamente. [^2, ^4]