Come ottenere il timer attivo per un ticket in Zoho Desk

Recuperare il timer attivo per un ticket di Zoho Desk è semplice: invia una singola richiesta GET autenticata all'endpoint activeTimer, passando l'ID del ticket come parametro di percorso.

Perché è importante

Quando gli agenti registrano il tempo sui ticket di supporto, potresti dover verificare programmaticamente se un timer è attualmente in esecuzione — ad esempio, per applicare regole di fatturazione, costruire dashboard o attivare automazioni quando il tracciamento del tempo è attivo. L'endpoint dedicato activeTimer restituisce solo il timer in corso, mantenendo la logica di integrazione pulita ed evitando la necessità di filtrare un elenco completo di timer.

Procedura passo dopo passo

Passaggio 1. Assicurati che il tuo token OAuth includa gli scope corretti di Zoho Desk. Come minimo hai bisogno di Desk.tickets.READ (e idealmente Desk.tickets.ALL) autorizzati per la tua app connessa. Questi scope devono essere presenti al momento della generazione o del rinnovo del token. ^[8]

Passaggio 2. Ottieni un access token valido per l'utente di destinazione. Se il token è scaduto, la tua integrazione deve chiamare il flusso di rinnovo del token utilizzando il refreshtoken memorizzato, il tuo clientid e il tuo clientsecret per ricevere un nuovo accesstoken prima di procedere. ^[6]

Passaggio 3. Identifica il ticketId del ticket di cui vuoi ispezionare il timer attivo. Questo è l'identificatore numerico o alfanumerico univoco che Zoho Desk assegna a ciascun record di ticket. ^[1]

Passaggio 4. Effettua una richiesta GET al seguente endpoint, sostituendo l'ID ticket reale nel percorso:

GET /api/v1/tickets/{ticketId}/activeTimer

La richiesta accetta un dizionario di parametri di query opzionale (p) se hai bisogno di passare filtri aggiuntivi o suggerimenti di paginazione. ^[1]

Passaggio 5. In Python, utilizzando il wrapper delle API di Zoho Desk, la chiamata si presenta così:

# Assuming `api` is an initialised ZohoDeskApi instance
response = api.get_active_timer_for_a(ticketId="1234567890")
print(response)

Passa un dizionario p come secondo argomento se hai bisogno di parametri di query aggiuntivi; altrimenti il valore predefinito è None. ^[1]

Passaggio 6. Analizza la risposta. Una chiamata riuscita restituisce i dettagli del timer attualmente in esecuzione per quel ticket. Se nessun timer è attivo, l'API restituirà tipicamente un risultato vuoto o un indicatore di stato pertinente — gestisci entrambi i casi nel tuo codice. ^[1]

Passaggio 7. Se hai bisogno anche del record completo del timer (non solo quello attivo), utilizza invece l'endpoint complementare:

GET /api/v1/tickets/{ticketId}/timer

Questo recupera i dati generali del timer del ticket indipendentemente dal fatto che sia attualmente in esecuzione. ^[3]

Passaggio 8. Per modificare il timer dopo averlo recuperato, utilizza l'endpoint PATCH:

PATCH /api/v1/tickets/{ticketId}/timer

Passa le tue modifiche come dizionario data nel corpo della richiesta. ^[2]

Passaggio 9. Se hai bisogno di avviare un nuovo timer da zero, utilizza l'endpoint di avvio dedicato:

POST /api/v1/tickets/{ticketId}/timer/start

Fornisci i campi richiesti nel parametro body data. ^[5]

Errori comuni

• Access token mancante o scaduto. Se l'access_token è assente o non aggiornato, ogni chiamata API fallirà con un errore di autenticazione. Verifica sempre che il token sia rinnovato prima di effettuare richieste al timer. ^[6]
• orgid errato o mancante. Le chiamate alle API di Zoho Desk richiedono che l'ID organizzazione sia impostato sul client. Se deskorg_id non è memorizzato, il client deve rilevarlo automaticamente chiamando prima l'endpoint delle organizzazioni; senza di esso, le richieste potrebbero restituire errori di autorizzazione o di instradamento. ^[7]
• Scope OAuth insufficienti. Gli endpoint del timer rientrano nelle autorizzazioni dei ticket. Se Desk.tickets.READ o Desk.tickets.ALL non erano inclusi al momento dell'autorizzazione della connessione OAuth, la chiamata verrà rifiutata anche con un token valido. ^[8]
• Nessun timer attivo esistente. L'endpoint activeTimer è specifico per i timer in corso. Se nessun timer è attualmente in esecuzione sul ticket, non assumere che si tratti di un errore — controlla il corpo della risposta prima di trattarlo come un fallimento. ^[1]

Cosa verificare

• Conferma che il tuo token OAuth abbia almeno lo scope Desk.tickets.READ e non sia scaduto prima di effettuare la richiesta. ^[8]
• Verifica che il ticketId che stai passando sia corretto e appartenga alla stessa organizzazione di Zoho Desk contro cui il tuo client è autenticato. [^1, ^7]
• Se la risposta è vuota, effettua una verifica incrociata utilizzando GET /api/v1/tickets/{ticketId}/timer per confermare se esiste un record di timer per quel ticket. ^[3]

---

*Beam Help è una risorsa di supporto esperto indipendente per i prodotti Zoho e non è il supporto ufficiale Zoho.*