Come recuperare le ore di turno in Zoho

Recuperare le ore di turno in Zoho CRM è semplice una volta stabilita la connessione OAuth — una singola chiamata API all'endpoint delle impostazioni restituisce tutta la configurazione delle ore di turno per la tua organizzazione.

Perché è importante

Gli orari lavorativi e i calendari dei turni guidano i calcoli degli SLA, i trigger di automazione e le finestre di disponibilità del supporto all'interno di Zoho CRM. Se stai costruendo un'integrazione o verificando la configurazione del CRM in modo programmatico, hai bisogno di un metodo affidabile per estrarre questi dati senza navigare manualmente nell'interfaccia utente. Comprendere la chiamata API sottostante è utile anche per risolvere le discrepanze tra il comportamento atteso e quello effettivo degli orari lavorativi.

Procedura passo dopo passo

Passaggio 1. Assicurati che esista una connessione OAuth valida per l'utente.

Prima che qualsiasi chiamata API possa avere successo, la tua applicazione deve disporre di un token di accesso attivo per l'account Zoho di destinazione. Il record di connessione viene cercato tramite user_id nel tuo archivio locale e, se il token è entro 120 secondi dalla scadenza, viene aggiornato automaticamente prima che la richiesta venga inviata — questo buffer di aggiornamento anticipato riduce gli errori 401 a metà richiesta. ^[1]

Passaggio 2. Crea un'istanza del client API di Zoho CRM.

Usa il helper getzohoapi, passando il userid pertinente e specificando "crm" come apptype. Questa funzione recupera la connessione memorizzata, configura un callback token_refresher per una ri-autenticazione trasparente e restituisce un'istanza ZohoCrmApi pronta all'uso insieme al record di connessione. ^[4]

Passaggio 3. Chiama lo strumento getshifthours.

Con il client API a disposizione, invoca getshifthours. Internamente, questo invia una richiesta HTTP GET all'endpoint /settings/shift_hours utilizzando la versione 6 dell'API. ^[2]

result = api.get_shift_hours()

Il metodo è anche esposto come strumento con nome (getshifthours) nel registro degli strumenti CRM, quindi può essere attivato anche tramite il percorso di dispatch standard execute_tool. ^[5]

Passaggio 4. Gestisci la risposta.

La chiamata restituisce l'oggetto di configurazione delle ore di turno da Zoho CRM. Analizza il dizionario restituito per i dettagli del programma di cui hai bisogno. Se la risposta contiene una chiave "error", verifica prima la validità del token — il livello OAuth restituisce {"error": "No access token in response"} quando lo scambio o l'aggiornamento del token fallisce. ^[3]

Passaggio 5. Aggiorna i token in modo proattivo se si opera in un contesto di test o batch.

Quando si eseguono più chiamate API sequenziali (ad esempio, durante i test di integrazione), ricontrolla il valore tokenexpiresat prima di ogni chiamata e invoca il token_refresher se il tempo corrente rientra nella finestra di tolleranza di 120 secondi. Questo schema impedisce che una sessione valida scada a metà batch. ^[6]

---

Errori comuni

• Record di connessione obsoleto o mancante. Se getzohoconnection restituisce None, non è possibile effettuare alcuna chiamata API. Verifica che la tabella zohoconnections contenga una riga per il userid di destinazione prima di procedere. ^[1]

• apptype errato passato a getzohoapi. Passare "desk" invece di "crm" instraderà la richiesta attraverso il client Zoho Desk, che non espone l'endpoint /settings/shifthours. Usa sempre "crm" per questa operazione. ^[4]

• Versione API non corrispondente. L'implementazione di getshifthours punta esplicitamente alla versione 6 dell'API di Zoho CRM. Sovrascrivere la versione in un wrapper client personalizzato potrebbe causare un errore 404 o uno schema di risposta inatteso. ^[2]

• Lacune negli scope OAuth. Al token di accesso devono essere stati concessi gli scope appropriati per le impostazioni CRM durante il flusso di autorizzazione iniziale. Se il token è stato emesso senza i permessi di lettura delle impostazioni, l'endpoint restituirà un errore di autorizzazione anche se il token stesso è valido. ^[7]

---

Cosa verificare

• Validità del token: Conferma che tokenexpiresat nel tuo record di connessione sia nel futuro (tenendo conto della tolleranza di 120 secondi) prima di effettuare la chiamata. ^[1]
• Endpoint e versione corretti: Verifica che il tuo client stia puntando a GET /settings/shift_hours alla versione 6 dell'API. ^[2]
• Struttura della risposta: Assicurati che l'oggetto restituito non contenga una chiave "error"; in caso contrario, riesamina gli scope OAuth e la validità del token di aggiornamento. ^[3]

---

*Beam Help è una risorsa di supporto esperto indipendente per gli utenti Zoho — non siamo il supporto ufficiale Zoho. Per problemi a livello di piattaforma, fai sempre riferimento alla documentazione ufficiale di Zoho.*