Come recuperare gli orari lavorativi in Zoho

Recuperare gli orari lavorativi in Zoho CRM è semplice una volta stabilita la connessione OAuth — una singola richiesta GET all'endpoint delle impostazioni restituisce tutti i dati sugli orari lavorativi configurati per la tua organizzazione.

Perché è importante

Gli orari lavorativi influenzano una serie di comportamenti CRM sensibili al tempo, tra cui i calcoli degli SLA, la pianificazione dei workflow e le finestre di disponibilità del supporto. Se stai costruendo un'integrazione o verificando la configurazione di Zoho CRM in modo programmatico, hai bisogno di un metodo affidabile per estrarre questi dati senza dover navigare nell'interfaccia ogni volta. Comprendere la chiamata API sottostante è utile anche quando si automatizzano i confronti tra ambienti sandbox e organizzazioni di produzione.

Procedura passo dopo passo

Passaggio 1. Assicurati di avere una connessione Zoho CRM valida e autenticata per l'utente in questione. Il sistema verifica l'esistenza di una connessione memorizzata e aggiorna automaticamente l'access token se mancano meno di 120 secondi alla scadenza, quindi non è necessario gestire manualmente la rotazione del token prima di effettuare la chiamata. ^[1]

Passaggio 2. Ottieni un'istanza di ZohoCrmApi associata all'utente autenticato. Internamente, questa racchiude un ZohoCrmClient che contiene l'apidomain e l'accesstoken corrente, insieme a un callback token_refresher in grado di rinnovare silenziosamente le credenziali durante la sessione se viene rilevato un errore 401. ^[3]

Passaggio 3. Chiama il metodo di recupero degli orari lavorativi sull'istanza API. L'operazione è mappata su:

GET /settings/business_hours

In Python, viene invocata come:

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

La richiesta è indirizzata alla versione 6 dell'API di Zoho CRM, quindi assicurati che il tuo client non sia impostato su un numero di versione precedente. ^[4]

Passaggio 4. Analizza la risposta. Una chiamata riuscita restituisce un payload JSON contenente la configurazione degli orari lavorativi della tua organizzazione. Se la risposta contiene una chiave error anziché la struttura dati attesa, verifica la validità del token e i permessi dell'organizzazione prima di riprovare. ^[4]

Passaggio 5. Se stai eseguendo questa operazione all'interno di un sistema di test automatizzato, puoi invocarla tramite il meccanismo di chiamata degli strumenti inviando una richiesta a /api/chat con un corpo JSON che specifica "tool": "getbusinesshours" e un oggetto params vuoto. Il server estrae il risultato dello strumento da data.tool_result nella risposta. ^[5]

---

Errori comuni

• Record di connessione assente o non aggiornato. Se getzohoconnection restituisce None per il user_id specificato, l'istanza API non può essere creata e la chiamata fallirà silenziosamente. Verifica sempre che il record di connessione esista nel database prima di procedere. ^[1]

• Versione API errata. L'endpoint degli orari lavorativi viene chiamato esplicitamente con version=6. Omettere il parametro di versione o utilizzare una versione precedente come predefinita potrebbe restituire un errore 404 o una risposta con una struttura inattesa. ^[4]

• ID organizzazione mancante per configurazioni multi-prodotto. Se la tua integrazione utilizza anche Zoho Desk insieme a CRM, tieni presente che le chiamate a Desk richiedono un campo orgid separato (deskorg_id), distinto dall'identificatore dell'organizzazione CRM. Confonderli causerà errori di autenticazione sul prodotto sbagliato. ^[3]

• Scadenza del token durante la richiesta. Sebbene il livello di connessione aggiorni i token in modo proattivo 120 secondi prima della scadenza, i processi batch a lunga esecuzione possono comunque ricevere un errore 401. Il callback token_refresher è progettato per gestire questa situazione, ma verifica che sia configurato correttamente nell'istanza del tuo ZohoCrmClient. [^1, ^3]

---

Cosa verificare

• Conferma la validità dell'access token verificando che tokenexpiresat sia nel futuro prima di effettuare la chiamata, oppure controllando che la logica di aggiornamento automatico sia stata eseguita senza errori. ^[1]
• Verifica il dominio API corretto (api_domain) memorizzato nel record di connessione — questo valore viene restituito durante lo scambio iniziale del token OAuth e deve corrispondere al data center in cui è ospitata la tua organizzazione. ^[6]
• Esamina la risposta grezza alla ricerca di una chiave error; se presente, confronta la descrizione dell'errore con i tuoi scope OAuth per assicurarti che lo scope delle impostazioni CRM sia incluso in Config.ZOHO_SCOPES. [^2, ^6]

---

*Beam Help fornisce una guida esperta indipendente per i prodotti Zoho e non rappresenta il supporto ufficiale Zoho. Testa sempre le chiamate API su un'organizzazione sandbox prima di eseguirle in produzione.*