Come ottenere il timer di un'attività in Zoho Desk

I timer delle attività in Zoho Desk ti permettono di tracciare il tempo dedicato alle singole attività, e l'API di Zoho Desk espone due endpoint distinti per recuperare tali dati — uno per il record completo del timer e uno per il timer attualmente in esecuzione.

Perché è importante

Quando devi verificare il tempo registrato per le attività di supporto, creare dashboard di reportistica personalizzate o integrare i dati sul tempo delle attività di Zoho Desk in uno strumento di fatturazione di terze parti, devi sapere quale endpoint API chiamare e come autenticarti correttamente. Sono disponibili due operazioni di lettura separate: recuperare il record completo del timer per un'attività e recuperare solo il timer *attivo* (attualmente in esecuzione). Scegliere quello sbagliato può restituire dati vuoti o una risposta fuorviante.

---

Procedura passo dopo passo

Passaggio 1. Verifica che i tuoi scope OAuth includano i permessi per le attività.

Prima di effettuare qualsiasi richiesta relativa al timer, verifica che il token OAuth di Zoho Desk connesso sia stato emesso con almeno Desk.tasks.READ (o Desk.tasks.ALL) nel suo elenco di scope. Senza questo, l'API rifiuterà la tua richiesta con un errore di autorizzazione. ^[5]

Passaggio 2. Ottieni un access token valido.

La tua integrazione deve disporre di un access token corrente per Zoho Desk. Se il token è scaduto, utilizza il refresh token memorizzato per chiamare l'endpoint token di Zoho con il tuo clientid, clientsecret e granttype: refreshtoken. Una risposta positiva includerà un nuovo accesstoken e un valore tokenexpires_at aggiornato. ^[6]

Passaggio 3. Identifica il taskId che vuoi interrogare.

Ogni richiesta relativa al timer è limitata a un'attività specifica. Hai bisogno dell'identificatore univoco dell'attività (es. "1234567890") prima di chiamare uno dei due endpoint. Questo viene tipicamente restituito quando crei o elenchi le attività tramite l'API di Zoho Desk.

Passaggio 4. Recupera il record completo del timer per un'attività.

Invia una richiesta GET a:

GET /api/v1/tasks/{taskId}/timer

Sostituisci {taskId} con il tuo identificatore di attività reale. Un dizionario di parametri di query opzionale (p) può essere passato per eventuali argomenti di filtro o paginazione supportati. In Python si presenta così: ^[1]

response = desk_api.get_task_timer(taskId="1234567890")

Questo restituisce il record completo del timer associato a quell'attività, incluse le voci di tempo storiche.

Passaggio 5. Recupera solo il timer attualmente attivo (se presente).

Se hai bisogno di sapere solo se un timer è *in esecuzione in questo momento* su un'attività, chiama invece l'endpoint dedicato al timer attivo:

GET /api/v1/tasks/{taskId}/activeTimer

Anche in questo caso, sostituisci il tuo taskId reale. In Python: ^[2]

response = desk_api.get_active_timer_for_a_2(taskId="1234567890")

Questo endpoint restituisce dati solo quando un timer è attivamente in esecuzione sull'attività specificata. Se nessun timer è in corso, aspettati un payload vuoto o nullo.

Passaggio 6. (Facoltativo) Aggiorna il timer se necessario.

Se i dati del timer recuperati necessitano di correzione — ad esempio, per modificare il tempo registrato — puoi effettuare una richiesta PATCH allo stesso percorso /api/v1/tasks/{taskId}/timer, fornendo un dizionario data con i campi da aggiornare. ^[7]

Passaggio 7. Inizializza il client API di Desk con il corretto org_id.

Zoho Desk è limitato all'organizzazione. Quando costruisci il client API, assicurati che orgid sia valorizzato. Se mancante, il sistema può individuarlo automaticamente chiamando l'endpoint dell'elenco organizzazioni e memorizzando il primo id restituito. Senza un orgid valido, tutte le chiamate all'API di Desk — incluse le richieste relative al timer — falliranno. ^[4]

---

Errori comuni

• Chiamare l'endpoint sbagliato. GET /api/v1/tasks/{taskId}/timer restituisce la cronologia completa del timer, mentre GET /api/v1/tasks/{taskId}/activeTimer restituisce solo un timer live in corso. ^[1][2] Se ti aspetti lo stato in tempo reale ma chiami il primo, potresti vedere dati non aggiornati.
• Access token mancante o scaduto. Il flusso di aggiornamento del token deve completarsi con successo — in particolare, la risposta deve contenere access_token — prima che venga tentata qualsiasi chiamata all'API di Desk. Una chiave di errore nella risposta di aggiornamento significa che il token non è stato rinnovato. ^[6]
• Scope OAuth insufficienti. La richiesta di dati del timer richiede permessi di lettura a livello di attività (Desk.tasks.READ o Desk.tasks.ALL). Gli scope vengono impostati al momento dell'autorizzazione OAuth e non possono essere aggiunti retroattivamente senza una nuova autorizzazione. ^[5]
• orgid mancante. Zoho Desk richiede un ID organizzazione in ogni richiesta. Se il tuo record di connessione non ha deskorg_id memorizzato, il client deve risolverlo prima di procedere. ^[4]

---

Cosa verificare

• Copertura degli scope: Conferma che Desk.tasks.READ o Desk.tasks.ALL sia presente nella configurazione degli scope OAuth attivi. ^[5]
• Validità del token: Verifica che tokenexpiresat sia nel futuro; in caso contrario, avvia un aggiornamento prima di chiamare gli endpoint del timer. ^[6]
• Selezione corretta dell'endpoint: Usa /activeTimer per i controlli dello stato in tempo reale e /timer per i record storici completi, e conferma che il taskId nel percorso corrisponda all'attività che intendi interrogare. ^[1][2]

---

*Beam Help è una risorsa di supporto esperto indipendente per i prodotti Zoho — non siamo il supporto ufficiale Zoho. Per problemi a livello di piattaforma, fai sempre riferimento alla documentazione ufficiale dell'API di Zoho Desk.*