Come recuperare le regole di assegnazione in Zoho

Il recupero delle regole di assegnazione in Zoho CRM avviene tramite una singola richiesta GET autenticata all'endpoint /settings/assignment_rules, passando il modulo di destinazione come parametro.

Perché è importante

Le regole di assegnazione controllano come i record in entrata — lead, contatti, trattative e altro — vengono distribuiti automaticamente al tuo team di vendita. Se stai costruendo un'integrazione, verificando la configurazione del CRM o sincronizzando le regole con un sistema esterno, dovrai recuperare queste regole in modo programmatico. Questo è utile anche per risolvere i problemi relativi al mancato instradamento dei record come previsto. Come promemoria, Beam Help è un supporto esperto indipendente per Zoho e non è il supporto ufficiale di Zoho.

---

Procedura passo dopo passo

Passaggio 1. Registra la tua applicazione e ottieni le credenziali OAuth visitando la Zoho API Console, creando un'applicazione Server-based e annotando il tuo Client ID e Client Secret. Imposta il tuo redirect URI (ad esempio, http://localhost:8080/api/auth_callback) e assicurati di includere lo scope ZohoCRM.settings.ALL tra gli scope selezionati. ^[8]

Passaggio 2. Genera un URL di autorizzazione OAuth costruendo una richiesta con i parametri clientid, redirecturi, scope, responsetype e accesstype. Il parametro access_type deve essere impostato su offline e prompt su consent in modo che venga emesso un refresh token insieme all'access token. ^[2]

Passaggio 3. Scambia il codice di autorizzazione restituito da Zoho con un access token e un refresh token. Invia una richiesta POST all'endpoint token di Zoho con granttype: authorizationcode, il tuo clientid, clientsecret, redirecturi e il valore code. Conserva in modo sicuro i valori risultanti accesstoken, refreshtoken, apidomain e tokenexpiresat per un uso successivo. ^[2]

Passaggio 4. Quando il tuo access token scade, utilizza il refresh token memorizzato per ottenerne uno nuovo. Invia una richiesta POST con granttype: refreshtoken insieme al tuo clientid e clientsecret. Aggiorna i valori memorizzati accesstoken e tokenexpires_at dopo ogni aggiornamento riuscito in modo che le chiamate successive rimangano autenticate. ^[3]

Passaggio 5. Con un access token valido a disposizione, chiama l'endpoint delle regole di assegnazione. Esegui una richiesta GET a:

GET /settings/assignment_rules?module=<ModuleName>

Il parametro module (indicato come m nell'implementazione sottostante) specifica le regole di assegnazione del modulo Zoho CRM che desideri recuperare — ad esempio, Leads, Contacts o Deals. ^[1]

In Python, questa chiamata si presenta così:

def get_assignment_rules(self, m: str):
    return self.c.request("GET", "/settings/assignment_rules", {"module": m})

L'oggetto client (self.c) deve già contenere un access token valido e aggiornato prima di effettuare questa chiamata. ^[1]

Passaggio 6. Gestisci la risposta. Una chiamata riuscita restituisce le regole di assegnazione configurate per il modulo specificato. Se il token è scaduto o lo scope è insufficiente, riceverai un errore di autenticazione — in tal caso, avvia il flusso di aggiornamento del token descritto nel Passaggio 4 e riprova. ^[3]

---

Errori comuni

• Scope mancante. Se ZohoCRM.settings.ALL non è incluso nella configurazione dello scope OAuth, l'API rifiuterà la richiesta. Verifica gli scope registrati nella Zoho API Console e nella configurazione del tuo ambiente. ^[8]

• Access token scaduto. Gli access token di Zoho hanno una durata limitata (in genere 3600 secondi). Se tokenexpiresat è già trascorso e non hai effettuato l'aggiornamento, la chiamata fallirà. Controlla sempre la scadenza prima di effettuare una richiesta e aggiorna il token in modo proattivo. [^2, ^3]

• Data center errato. Zoho opera su più data center (com, eu, in, com.au, jp). Il valore api_domain restituito durante lo scambio del token deve essere utilizzato come URL base per tutte le chiamate API — non impostare come hardcoded https://www.zohoapis.com se la tua organizzazione si trova su un DC diverso. [^5, ^8]

• Sensibilità alle maiuscole nel nome del modulo. Il parametro module deve corrispondere esattamente al nome API interno del modulo di Zoho CRM. Utilizza il nome API (ad es., Leads, non leads) per evitare un errore di "modulo non trovato". ^[1]

---

Cosa verificare

• Scope presente: Conferma che ZohoCRM.settings.ALL sia presente negli scope OAuth registrati e nella configurazione del tuo file .env prima di effettuare la chiamata. ^[8]
• Token aggiornato: Verifica che il valore memorizzato tokenexpiresat sia nel futuro; in caso contrario, esegui il flusso di aggiornamento prima di chiamare l'endpoint. ^[3]
• URL base corretto: Assicurati di utilizzare il valore api_domain restituito durante lo scambio del token come radice delle tue richieste API, non un dominio impostato come hardcoded. ^[5]