Come recuperare le preferenze degli appuntamenti in Zoho

Recuperare le preferenze degli appuntamenti in Zoho CRM è semplice grazie a un unico endpoint API delle impostazioni che restituisce la configurazione di pianificazione della tua organizzazione in una sola chiamata.

Perché è importante

Quando si creano integrazioni o automazioni attorno alle funzionalità di pianificazione di Zoho CRM, spesso è necessario leggere le preferenze degli appuntamenti correnti in modo programmatico — ad esempio, per validare le regole di prenotazione, sincronizzare le finestre di disponibilità o verificare le modifiche alla configurazione. Conoscere l'endpoint esatto e come collegarlo a un client autenticato consente di risparmiare molto tempo di tentativi ed errori. Come sempre, Beam Help è un supporto esperto indipendente per Zoho e non è il supporto ufficiale di Zoho.

Procedura passo dopo passo

Passaggio 1. Assicurati che la connessione OAuth di Zoho CRM sia attiva e che il tuo token di accesso sia valido. Il livello API gestisce automaticamente il rinnovo del token cercando il refreshtoken memorizzato, chiamando l'endpoint di rinnovo OAuth e salvando il nuovo accesstoken nel database prima di effettuare qualsiasi richiesta downstream. ^[3]

Passaggio 2. Verifica che i tuoi scope OAuth includano le autorizzazioni necessarie per le impostazioni CRM. La configurazione degli scope deve coprire ZohoCRM.settings o lo scope più ampio ZohoCRM.org.ALL affinché l'endpoint delle impostazioni sia accessibile. Senza gli scope corretti, la richiesta verrà rifiutata prima di raggiungere il server. ^[2]

Passaggio 3. Crea un'istanza del client API di Zoho CRM utilizzando la connessione autenticata per l'utente di destinazione. Passa app_type="crm" quando chiami la funzione factory dell'API, in modo che venga inizializzata la classe client corretta anziché la variante Desk. ^[3]

Passaggio 4. Chiama l'endpoint delle preferenze degli appuntamenti. Invia una richiesta HTTP GET a /settings/appointment_preferences utilizzando la versione 6 dell'API. In Python, si presenta così: ^[1]

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

Il metodo delega al client HTTP sottostante (self.c), che allega automaticamente il bearer token e instrada la richiesta al dominio del data center corretto. ^[1]

Passaggio 5. Analizza la risposta. L'endpoint restituisce un payload JSON contenente le impostazioni delle preferenze degli appuntamenti della tua organizzazione. Esamina il dizionario restituito per i campi rilevanti per il tuo caso d'uso — regole di disponibilità, finestre di prenotazione o impostazioni di notifica — e gestisci eventuali chiavi di errore prima di procedere. ^[1]

Endpoint delle impostazioni correlati

Se hai bisogno di recuperare altre categorie di preferenze insieme ai dati degli appuntamenti, due endpoint correlati seguono lo stesso schema e la stessa versione:

• Preferenze chiamate — GET /settings/telephony (operazione: getcallpreferences) ^[4]
• Preferenze servizi — GET /settings/servicepreferences (operazione: getservice_preferences) ^[5]

Tutti e tre utilizzano la versione 6 dell'API e lo stesso client autenticato, quindi puoi raggrupparli in un'unica sessione senza dover eseguire nuovamente l'autenticazione.

Errori comuni

• Token di accesso scaduti. Se il token è scaduto e la logica di rinnovo fallisce (ad esempio, perché la riga refreshtoken è assente dal database), getzoho_api restituisce None e la chiamata alle impostazioni non verrà mai eseguita. Verifica sempre che l'oggetto API restituito non sia None prima di invocare qualsiasi metodo su di esso. ^[3]
• apptype errato. Passare apptype="desk" inizializzerà un ZohoDeskClient invece del client CRM, e il percorso /settings/appointment_preferences non esisterà su quel client — causando un confuso errore 404 o un errore di attributo. ^[3]
• Scope insufficienti. Se la tua applicazione OAuth è stata autorizzata con un insieme minimo di scope che esclude gli scope dell'organizzazione o delle impostazioni CRM, l'API restituirà un errore di autorizzazione. Ri-autorizza la connessione includendo lo scope completo ZohoCRM.org.ALL. ^[2]

Cosa verificare

• Validità del token — conferma che l'accesstoken memorizzato non sia scaduto e che la funzione tokenrefresher possa ottenere con successo un nuovo token dalla tabella zoho_connections. ^[3]
• Copertura degli scope — verifica che ZohoCRM.org.ALL o uno scope equivalente per le impostazioni sia presente nell'elenco degli scope autorizzati per il tuo client OAuth. ^[2]
• Versione API — assicurati che la richiesta specifichi esplicitamente la versione 6, poiché l'endpoint /settings/appointment_preferences è definito per quella versione e potrebbe non risolversi correttamente nelle versioni precedenti. ^[1]