Come recuperare le preferenze del servizio in Zoho

Il recupero delle preferenze del servizio in Zoho CRM avviene tramite una singola richiesta GET autenticata all'endpoint /settings/service_preferences, che restituisce la configurazione del servizio corrente per la tua organizzazione.

Perché è importante

Quando si creano integrazioni o automazioni su Zoho CRM, spesso è necessario verificare come sono configurati i servizi prima di prendere decisioni a valle. L'endpoint delle preferenze del servizio fornisce uno snapshot programmatico di tali impostazioni senza dover navigare nell'interfaccia utente. Questo è particolarmente utile durante audit di onboarding, confronti tra ambienti o quando si esegue il debug di comportamenti imprevisti del servizio. In qualità di supporto esperto indipendente (non supporto ufficiale Zoho), Beam Help documenta questi pattern affinché il tuo team possa lavorare più velocemente.

Passo dopo passo

Passo 1. Assicurati che il tuo utente disponga di una connessione Zoho CRM attiva e autenticata. Prima di qualsiasi chiamata API, il sistema verifica il record di connessione memorizzato e aggiorna automaticamente il token OAuth se si trova entro 120 secondi dalla scadenza — quindi non dovresti mai dover attivare manualmente un aggiornamento durante una richiesta. ^[7]

Passo 2. Se il token di accesso deve essere aggiornato, il livello OAuth scambia il refresh token memorizzato con uno nuovo e aggiorna sia accesstoken che tokenexpiresat nel record di connessione. Verifica che accesstoken sia presente nella risposta prima di procedere; se è assente, l'aggiornamento è fallito e la chiamata deve essere interrotta. ^[8]

Passo 3. Crea un'istanza del client API di Zoho CRM utilizzando la connessione autenticata. Passa apidomain, l'accesstoken corrente e un callback token_refresher in modo che qualsiasi scadenza durante la richiesta possa essere gestita in modo trasparente senza interrompere la chiamata. ^[2]

Passo 4. Chiama l'endpoint delle preferenze del servizio inviando una richiesta GET a /settings/service_preferences utilizzando la versione 6 dell'API. In Python si presenta così:

def get_service_preferences(self):
    return self.c.request("GET", "/settings/service_preferences", version=6)

Il metodo restituisce il payload completo delle preferenze del servizio per la tua organizzazione CRM. ^[1]

Passo 5. Analizza il corpo della risposta. I dati restituiti riflettono la configurazione corrente dei servizi. Memorizza o registra il risultato secondo le necessità per la tua logica di audit o integrazione. ^[1]

Errori comuni

• Token mancante o scaduto. Se accesstoken non è presente dopo un tentativo di aggiornamento, il client API non avrà credenziali valide e la richiesta fallirà con un errore 401. Verifica sempre che l'aggiornamento del token abbia restituito una chiave accesstoken valida prima di procedere. ^[8]

• Versione API errata. La chiamata getservicepreferences punta esplicitamente alla versione 6 dell'API di Zoho CRM. L'utilizzo di un numero di versione diverso potrebbe restituire un errore 404 o una struttura di risposta inattesa. ^[1]

• Nessun record di connessione trovato. Se l'utente non ha completato il flusso OAuth, getzohoconnection restituisce None e l'istanza API non può essere creata. Gestisci questo caso richiedendo all'utente di riconnettersi prima di tentare qualsiasi recupero delle impostazioni. ^{[2] [7]}

• Mancata corrispondenza del dominio. Zoho opera su più data center (ad es. .com, .eu, .in). L'api_domain memorizzato nel record di connessione deve corrispondere al data center in cui è ospitata l'organizzazione CRM, altrimenti le richieste verranno instradate in modo errato. ^[2]

Cosa verificare

• Validità del token: Conferma che accesstoken sia presente e che tokenexpires_at sia nel futuro prima che la richiesta venga inviata. ^[7]
• Versione API: Verifica che il tuo client stia passando esplicitamente version=6 quando chiama /settings/service_preferences. ^[1]
• Integrità del record di connessione: Controlla che apidomain e refreshtoken siano entrambi popolati nella connessione memorizzata; un refresh_token mancante impedirà il recupero da qualsiasi scadenza del token. ^{[7] [8]}