Come ottenere il riepilogo delle voci di tempo di un'attività in Zoho Desk

Recuperare il riepilogo delle voci di tempo per un'attività specifica in Zoho Desk è semplice tramite una singola chiamata API che restituisce i dati di tempo aggregati per quell'attività. Ecco tutto ciò che ti serve per farlo funzionare correttamente.

Perché è importante

Nella gestione delle operazioni di supporto, i responsabili del team hanno spesso bisogno di una visione consolidata del tempo che gli agenti hanno registrato per una determinata attività, senza dover scorrere ogni singola voce. L'endpoint di riepilogo fornisce quel totale aggregato in un'unica richiesta, rendendolo ideale per dashboard di reportistica, revisioni di fatturazione o audit SLA. Se stai costruendo automazioni o integrazioni su Zoho Desk, questa è la chiamata da utilizzare ogni volta che è necessario il tempo totale per singola attività.

Procedura passo dopo passo

Passaggio 1. Verifica che il tuo token OAuth includa lo scope corretto per le attività di Zoho Desk. Il token deve contenere almeno Desk.tasks.READ (o il più ampio Desk.tasks.ALL) affinché l'API autorizzi la richiesta. Senza questo scope, la chiamata restituirà un errore di autorizzazione. ^[7]

Passaggio 2. Identifica il taskId dell'attività che vuoi riepilogare. Si tratta dell'identificatore univoco che Zoho Desk assegna a ogni record di attività. Puoi recuperarlo da una precedente chiamata API all'elenco delle attività o direttamente dall'URL dell'attività nel portale Desk. ^[1]

Passaggio 3. Esegui una richiesta GET al seguente endpoint, sostituendo il tuo identificatore di attività effettivo:

GET /api/v1/tasks/{taskId}/timeEntries/summary

L'operazione dell'endpoint è getsummationoftasktime e accetta due parametri: taskId (obbligatorio, stringa) e un parametro opzionale p per ulteriori opzioni di query. ^[1]

Passaggio 4. In Python, la chiamata si presenta così:

def get_summation_of_task_time(self, taskId: str, p: dict = None):
    """Get Summation of Task Time Entries"""
    return self.c.request("GET", f"/api/v1/tasks/{taskId}/timeEntries/summary", p, None)

Passa l'ID dell'attività come taskId. Se hai bisogno di filtrare o paginare i dati sottostanti, fornisci un dizionario di parametri di query tramite p; altrimenti lascialo come None. ^[1]

Passaggio 5. Analizza la risposta. L'API restituisce un oggetto di riepilogo contenente i dati di tempo aggregati per tutte le voci registrate per quell'attività. Presenta i campi principali — come il tempo totale registrato — agli utenti in un formato leggibile, anziché esporre gli ID interni grezzi. ^[8]

Errori comuni

• Scope mancante o errato. La causa più frequente di una risposta 401 o 403 è un token OAuth generato senza Desk.tasks.READ o Desk.tasks.ALL. Ri-autorizza la connessione includendo gli scope corretti. ^[7]
• taskId errato. Passare un ID ticket o un ID contatto al posto di un ID attività risulterà in una risposta 404 o vuota. Verifica sempre che l'ID provenga da un record di attività e non da un'altra entità di Zoho Desk. ^[1]
• Omettere completamente il parametro p rispetto al passare None. Il parametro è opzionale, quindi passare None è sicuro, ma se il tuo framework di integrazione richiede un dizionario vuoto esplicito, usa {} per evitare errori imprevisti sugli argomenti. ^[1]

Cosa verificare

• Verifica che il token OAuth in uso includa Desk.tasks.READ o Desk.tasks.ALL negli scope concessi prima di effettuare la chiamata. ^[7]
• Conferma che il valore taskId corrisponda a un'attività valida nel tuo portale Zoho Desk, non a un ticket o a un altro tipo di record. ^[1]
• Esamina i campi della risposta di riepilogo e assicurati che il codice a valle gestisca i casi in cui non sono ancora state registrate voci di tempo (il riepilogo potrebbe restituire valori zero anziché un corpo vuoto). ^[1]

---

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