API di Zoho CRM: OAuth e limiti, come gestire token e chiamate nelle integrazioni

Il tema API di Zoho CRM: OAuth e limiti si riduce a due compiti. Il primo è registrare un client nella Zoho API console e ottenere token validi. Il secondo è progettare le chiamate in modo che restino entro i crediti della licenza e il numero di chiamate simultanee consentite.

OAuth 2.0 è il protocollo con cui un'applicazione, dopo il consenso dell'utente, ottiene un token di accesso e lo usa per chiamare le API. La panoramica OAuth 2.0 di Zoho descrive il percorso in tre passaggi. Si registra l'applicazione nella API console, si ottiene il consenso e un token, poi si chiamano le API con quel token.

I limiti agiscono su due piani distinti. Il volume complessivo di chiamate dipende dai crediti della licenza. La concorrenza, cioè il numero di chiamate eseguite nello stesso istante, ha un tetto per ogni applicazione registrata. Un'integrazione può fallire per l'uno o per l'altro motivo, anche quando l'autenticazione funziona perfettamente.

Questa guida spiega i termini, la registrazione del client, gli scope, la gestione dei token e il data center europeo. Segue un esempio completo, una tabella degli errori più frequenti e le indicazioni per un'azienda italiana. Al termine Lei saprà registrare un client OAuth, ottenere i token e pianificare le chiamate entro i limiti della Sua edizione.

Un'integrazione con Zoho CRM usa sempre gli stessi cinque elementi OAuth. Conoscerli evita la maggior parte dei malintesi tra chi commissiona il progetto e chi lo sviluppa.

Questi sono i termini usati nel resto della guida:

• Client: l'applicazione registrata nella Zoho API console, identificata da un client ID e da un client secret.
• Access token: la credenziale temporanea inviata a ogni chiamata API. La durata in secondi arriva nel campo expires_in della risposta.
• Refresh token: un token opzionale, da richiedere e conservare, che serve a generare nuovi access token quando i precedenti scadono.
• Scope: la dichiarazione che limita il livello di accesso dell'applicazione alle risorse protette.
• Data center: la regione Zoho in cui risiede l'account. Zoho gestisce data center in più regioni, con endpoint distinti.

Il rapporto tra questi elementi è lineare. Il client chiede il consenso per determinati scope. L'utente lo concede e il client riceve un access token, più un refresh token se lo ha richiesto. Da quel momento il client chiama le API sull'endpoint del data center corretto e rinnova l'access token quando scade.

Anche il termine "applicazione" merita attenzione. Nel contesto dei limiti di concorrenza, applicazione indica un client creato nella API console, non un prodotto come Zoho CRM o Zoho Creator. Lo chiarisce una discussione sulla concorrenza delle API Zoho nella community ufficiale.

La registrazione del client OAuth avviene nella Zoho API console, all'indirizzo api-console.zoho.com. È il primo passo obbligatorio per qualsiasi integrazione con le API di Zoho CRM. Al termine della registrazione si ottengono il client ID e il client secret.

Zoho supporta flussi OAuth diversi a seconda del tipo di applicazione. La panoramica OAuth elenca questi tipi:

• applicazione server-based;
• applicazione client-based;
• applicazione mobile e desktop;
• dispositivi con input limitato;
• self client.

Per un'applicazione web che gira su un server dell'azienda, il tipo usato più spesso è il server-based. Un utente della community, per esempio, crea un client "Server-based Application" per ogni applicazione web che legge i dati del suo Zoho CRM. Per gli altri tipi conviene verificare il flusso previsto nella documentazione OAuth del prodotto prima di scegliere.

Un client per ogni integrazione

Registrare un client separato per ogni integrazione è una scelta di progetto con vantaggi concreti. Secondo la discussione della community sulla concorrenza, ogni applicazione della API console ha un proprio limite di chiamate simultanee. Inoltre un client dedicato rende evidente quale sistema genera le chiamate. Il sito, il gestionale e lo strumento di reportistica non si contendono così la stessa capacità.

Lo scope OAuth di Zoho stabilisce a quali moduli e a quali operazioni il client può accedere. Il server delle risorse concede solo ciò che lo scope dichiara. La documentazione Zoho sugli scope OAuth porta l'esempio di Zoho Books: un client limitato al modulo Fatture riceve accesso solo a quel modulo.

Uno scope Zoho ha tre parti e segue la sintassi service_name.scope_name.OPERATION_TYPE. Il nome del servizio identifica il prodotto, per esempio ZohoCRM. Il nome dello scope indica il modulo del servizio. Il tipo di operazione può essere ALL, READ, UPDATE o DELETE, dove ALL consente tutte le operazioni.

Tra gli esempi ufficiali figurano ZohoCRM.users.CREATE e ZohoCRM.modules.contacts.ALL. Un access token può contenere più scope, separati da virgole. Durante il consenso l'utente vede gli scope richiesti, quindi un elenco ordinato e ristretto è anche più facile da approvare.

Scope e utente: due livelli da considerare insieme

Lo scope limita il client, ma il token nasce sempre dal consenso di un utente. Nella community un utente voleva un token capace solo di aggiungere lead, con lettura e modifica negate. La sua conclusione era creare un utente dedicato con permessi limitati e generare il token da quell'utente. Lo svantaggio da lui segnalato era il costo di una licenza utente completa per inserire pochi lead al giorno. Conviene quindi valutare entrambi i livelli prima di registrare il client.

L'access token di Zoho scade periodicamente, mentre il refresh token serve a ottenerne di nuovi senza ripetere il consenso. La durata dell'access token arriva in secondi nel campo expires_in. Il refresh token va richiesto, conservato e usato per generare nuovi access token quando servono.

In pratica il passaggio con l'interfaccia grafica avviene una sola volta, durante la configurazione. Un utente della community lamentava che generare il token richiede un processo in due passaggi via interfaccia. Lo riteneva impraticabile per mostrare i ticket di Zoho Desk in un pannello di amministrazione. Il flusso con refresh token risolve proprio questo: dopo il consenso iniziale, il codice rinnova l'accesso da solo.

La logica corretta nel codice segue tre regole:

• conservare il refresh token in un archivio protetto sul server, mai nel browser o nel codice sorgente;
• riutilizzare l'access token finché è valido, calcolando la scadenza da expires_in;
• chiedere un nuovo access token solo quando il precedente è scaduto o sta per scadere.

Sul forum circola anche l'idea che un refresh token si possa usare solo dieci volte. L'autore stesso la presentava come ipotesi, con un punto interrogativo. La panoramica OAuth di Zoho parla invece di usare il refresh token per generare nuovi access token secondo necessità. Prima di progettare attorno a un limite simile, è bene verificarlo nella documentazione ufficiale.

Un'integrazione con Zoho CRM deve chiamare gli endpoint del data center in cui risiede l'account. Zoho gestisce data center in più regioni, ciascuno con i propri indirizzi. Per un'azienda italiana con l'account sul data center europeo, sia il rilascio dei token sia le chiamate API devono puntare agli endpoint europei.

La regola vale per entrambi i tipi di chiamata. La panoramica OAuth di Zoho è esplicita sulle applicazioni che servono utenti in regioni diverse. Queste devono attivare il supporto Multi DC nella API console e usare endpoint specifici per regione. Ciò vale per le chiamate OAuth e per quelle alle API del prodotto.

L'errore tipico è un'integrazione scritta con indirizzi copiati da un esempio pensato per un'altra regione. In quel caso l'autenticazione o le chiamate successive falliscono, anche con client ID e secret corretti. Il problema si nota soprattutto quando un fornitore riusa un connettore già sviluppato per clienti di altri paesi.

Quando attivare Multi DC

Il supporto Multi DC serve quando lo stesso client deve lavorare con account Zoho in regioni diverse. È il caso di un gruppo con società in più paesi o di un software venduto a clienti di aree diverse. Un'integrazione interna di un'azienda con un solo account europeo deve semplicemente usare in modo coerente gli endpoint europei, dal primo token all'ultima chiamata.

Le API di Zoho CRM hanno due limiti che un'integrazione deve rispettare: il volume di chiamate e la concorrenza. Il volume dipende dai crediti della licenza. La concorrenza riguarda quante chiamate sono in corso nello stesso istante. Le informazioni che seguono provengono da discussioni nella community Zoho; per i valori della Sua edizione faccia riferimento alla documentazione ufficiale.

Crediti e limite giornaliero

Il volume di chiamate API è legato alla licenza. Un utente della community parla di crediti limitati per la propria licenza. Un altro, che integrava WordPress tramite un cron job, ha ricevuto l'errore 4421 in una discussione sul limite API superato. Lo stesso utente scriveva di non poter aumentare il limite giornaliero perché era già in edizione Professional.

Concorrenza per applicazione

La concorrenza ha un tetto per organizzazione e per applicazione. La discussione sulla concorrenza riporta un limite di 15, 20 o 25 chiamate simultanee, secondo la documentazione citata. Un intervento precisa 20 chiamate per applicazione della API console: con tre applicazioni, ciascuna avrebbe il proprio limite di 20. Lo stesso intervento suggerisce di dividere le chiamate tra due applicazioni quando si rischia di raggiungere il tetto.

Un utente ha chiesto se si possa fissare un limite di richieste per ogni client server-based. Nella discussione disponibile non compare una risposta. Conviene quindi misurare e regolare il consumo dal lato dell'integrazione, con un registro delle chiamate e una coda.

Prendiamo un'azienda con un sito o un negozio online che deve creare e aggiornare contatti in Zoho CRM. L'esempio usa solo elementi documentati: il client server-based, lo scope ZohoCRM.modules.contacts.ALL, il refresh token e gli endpoint regionali. Lo stesso schema vale per un'integrazione tra PrestaShop e Zoho CRM o per altri canali di vendita.

1. In api-console.zoho.com registri un client di tipo Server-based Application, dedicato al sito.
2. Definisca lo scope. ZohoCRM.modules.contacts.ALL consente tutte le operazioni sui contatti, cancellazione compresa. Se il sito deve solo creare e aggiornare, cerchi nella documentazione delle API di Zoho CRM uno scope più ristretto.
3. Usi gli endpoint del data center europeo per il token e per le API. Attivi Multi DC solo se il client serve account di più regioni.
4. Esegua il consenso con l'utente scelto per l'integrazione e richieda il refresh token. Lo conservi sul server, in un archivio protetto.
5. Nel codice riutilizzi l'access token fino alla scadenza indicata da expires_in, poi lo rinnovi con il refresh token.
6. Metta le richieste del sito in una coda. Mantenga le chiamate simultanee sotto 15, il valore più basso citato per la concorrenza.
7. Registri ogni chiamata con data e ora, così da conoscere il consumo giornaliero e confrontarlo con i crediti della licenza.

Con questa impostazione un picco di ordini non blocca il CRM. Le richieste si accodano invece di superare il tetto di concorrenza. Il registro, inoltre, risponde alla domanda posta da molti utenti della community: quante chiamate consuma davvero l'integrazione ogni giorno.

Gli errori più frequenti nelle integrazioni con Zoho CRM riguardano token, endpoint, scope e numero di chiamate. La tabella riassume i casi ricorrenti, la loro conseguenza e la correzione.

Errore	Conseguenza	Correzione
Nuovo access token a ogni chiamata	Chiamate in più e più punti di errore	Riutilizzare il token fino alla scadenza di expires_in
Endpoint di un'altra regione	Autenticazione o chiamate che falliscono	Endpoint regionali per OAuth e API, Multi DC se servono più regioni
Scope ALL su tutti i moduli	Accesso più ampio del necessario	Scope per singolo modulo e operazione
Chiamata al CRM a ogni caricamento di pagina	Crediti esauriti e aumenti a pagamento	Leggere i dati una volta e riutilizzarli
Cron che sincronizza tutto a intervalli fissi	Errore 4421 per limite superato	Sincronizzare solo i record modificati
Tutte le integrazioni su un solo client	Concorrenza condivisa tra sistemi	Un client della API console per integrazione

Il caso della chiamata a ogni pagina viene da un utente di Zoho Creator. Il suo script in Deluge cercava il contatto CRM dell'utente collegato e poi l'account collegato, in ogni modulo e in ogni pagina. Con molti clienti sullo stesso sistema, raggiungeva spesso il limite e aveva già pagato più volte per aumentarlo.

Nei progetti di integrazione che seguiamo in Svennis questo è l'errore che incontriamo più spesso: una funzione che interroga il CRM a ogni apertura di pagina invece di leggere i dati una volta. Per questo contiamo le chiamate di ogni flusso già in fase di test, prima del rilascio. Un dubbio da chiarire con la documentazione riguarda i workflow: un utente ha chiesto se consumano i limiti API, senza risposta nella discussione.

Per un'azienda italiana, OAuth e limiti delle API di Zoho CRM si traducono in tre decisioni pratiche: data center, licenze e volumi. Ognuna va presa prima di affidare lo sviluppo, perché cambia il costo e la stabilità dell'integrazione.

La prima decisione riguarda il data center. Se l'account Zoho è sul data center europeo, il fornitore deve usare gli endpoint europei per i token e per le API. Conviene chiederlo per iscritto, soprattutto quando il connettore proposto nasce per clienti di altre regioni.

La seconda decisione riguarda l'utente da cui nasce il token. Un utente dedicato con permessi limitati riduce il rischio, ma può richiedere una licenza completa. È un costo ricorrente da mettere a budget, come segnalava l'utente della community che voleva solo inserire pochi lead al giorno.

La terza decisione riguarda i volumi. Il collegamento con un gestionale, per esempio un'integrazione tra SAP Business One e Zoho CRM, può muovere molti record ogni giorno. Un utente in edizione Professional non poteva più aumentare il limite giornaliero. Stimi quindi il consumo prima di scegliere l'edizione, e valuti l'implementazione di Zoho CRM e le integrazioni come un unico progetto.

Il primo passo concreto è una mappa delle chiamate, prima di qualsiasi riga di codice. Per ogni integrazione annoti quali moduli legge o scrive, quante volte al giorno e con quali picchi. Questa mappa decide lo scope, il numero di client e la necessità di una coda.

Questa è la sequenza consigliata per partire:

1. Elenchi le integrazioni previste e assegni a ciascuna un client separato nella Zoho API console.
2. Per ogni client definisca gli scope minimi, con la sintassi servizio, modulo e operazione.
3. Verifichi il data center dell'account e annoti gli endpoint regionali da usare per token e API.
4. Scelga l'utente da cui generare il token e verifichi il costo della sua licenza.
5. Stimi il consumo giornaliero e confronti la stima con i crediti della Sua edizione, sulla documentazione ufficiale Zoho.
6. Preveda fin dall'inizio un registro delle chiamate e una coda che tenga bassa la concorrenza.

Se l'integrazione collega Zoho CRM a un sito, a un e-commerce o a un gestionale, la pagina sulle integrazioni Zoho personalizzate descrive come affrontiamo questi progetti. Può partire da lì con la mappa delle chiamate già pronta, che rende la discussione più rapida e il preventivo più preciso.

• Zoho: OAuth 2.0 for v2 APIs, An Overview
• Zoho: OAuth Scope
• Zoho Community: Zoho Concurrency API Limitation
• Zoho Community: Can I set API request limits for each client application?
• Zoho Community: ZOHO API limit exceed
• Zoho Community: Creator API limit
• Zoho Community: API Token with Limited Permissions?
• Zoho Community: How to generate oauth access token with the help of api only
• Zoho Community: Clarification on Workflow and API Limits