Come ottenere il riepilogo delle voci di tempo di un ticket in Zoho Desk

Recuperare il riepilogo delle voci di tempo per un ticket Zoho Desk ti fornisce una visione aggregata di tutto il tempo registrato su quel ticket — senza dover sommare manualmente le singole voci. Qui su Beam Help (supporto esperto indipendente per Zoho, non supporto ufficiale Zoho), ti guidiamo esattamente su come farlo tramite le API di Zoho Desk.

Perché è importante

Nella gestione delle operazioni di supporto, spesso hai bisogno di un totale rapido e consolidato del tempo trascorso su un ticket — per la fatturazione, i report SLA o le valutazioni della produttività degli agenti. Recuperare ogni singola voce e sommarle manualmente è inefficiente su larga scala. L'endpoint di riepilogo ti fornisce quell'aggregazione in una singola chiamata, risparmiando tempo e riducendo il rischio di errori di calcolo. ^[1]

---

Passo dopo passo

Passo 1. Verifica che il tuo token OAuth abbia gli scope Desk corretti.

Prima di effettuare qualsiasi chiamata API, conferma che le tue credenziali OAuth includano almeno Desk.tickets.READ e Desk.tickets.ALL. Questi scope regolano l'accesso ai dati a livello di ticket, incluse le voci di tempo. Senza di essi, l'API restituirà un errore di autorizzazione. ^[3]

Passo 2. Identifica il ticketId che vuoi interrogare.

Ogni richiesta all'endpoint di riepilogo delle voci di tempo richiede un identificatore di ticket valido. Puoi recuperarlo dall'interfaccia di Zoho Desk (appare nell'URL del ticket) oppure in modo programmatico tramite gli endpoint di elenco/ricerca dei ticket. Tieni questo valore a portata di mano — lo sostituirai nel percorso nel passo successivo. ^[1]

Passo 3. Chiama l'endpoint di riepilogo delle voci di tempo.

Invia una richiesta GET a:

GET /api/v1/tickets/{ticketId}/timeEntries/summary

Sostituisci {ticketId} con l'ID ticket effettivo del Passo 2. In Python, utilizzando il wrapper client di Desk, la chiamata si presenta così: ^[1]

summary = client.get_summation_of_ticket_time(ticketId="your_ticket_id")

Il parametro opzionale p può essere passato come dizionario se hai bisogno di fornire parametri di query aggiuntivi supportati dalla configurazione della tua organizzazione Desk. ^[1]

Passo 4. Analizza la risposta.

La risposta conterrà i dati di tempo aggregati per il ticket specificato. Esamina i campi restituiti per estrarre i totali, come il tempo complessivo registrato, il tempo fatturabile e il tempo non fatturabile, in base al tuo caso d'uso. ^[1]

Passo 5. (Opzionale) Confronta con la suddivisione per tipo di fatturazione.

Se hai bisogno del riepilogo suddiviso per classificazione di fatturazione, puoi integrare la chiamata al riepilogo con una richiesta separata all'endpoint del tipo di fatturazione:

GET /api/v1/tickets/{ticketId}/timeEntries/billingType

Questo restituisce le voci di tempo raggruppate per tipo di fatturazione, offrendoti una visione più granulare accanto al riepilogo complessivo. ^[7]

Passo 6. (Opzionale) Approfondisci le singole voci.

Se un valore aggregato richiede un'analisi più dettagliata, puoi recuperare l'elenco completo delle singole voci di tempo per il ticket:

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

Oppure recupera una singola voce specifica tramite il suo identificatore:

GET /api/v1/tickets/{ticketId}/timeEntries/{timeEntryId}

Entrambi gli endpoint accettano lo stesso dizionario di parametri di query opzionale p. ^[6][8]

---

Errori comuni

• Scope OAuth mancanti o insufficienti. Se il tuo token è stato generato senza Desk.tickets.READ o Desk.tickets.ALL, l'endpoint di riepilogo rifiuterà la richiesta. Verifica sempre la configurazione degli scope prima di eseguire il debug della richiesta stessa. ^[3]

• ticketId non valido o non corrispondente. Passare un ID ticket appartenente a un'organizzazione Zoho Desk errata, o per errore un ID record CRM, restituirà un errore di risorsa non trovata. Verifica la fonte dell'ID prima di chiamare l'endpoint. ^[1]

• Confondere l'endpoint di riepilogo con l'endpoint di elenco. Il percorso /api/v1/tickets/{ticketId}/timeEntries restituisce un elenco di singole voci, mentre /api/v1/tickets/{ticketId}/timeEntries/summary restituisce i totali aggregati. Sono operazioni distinte — assicurati di chiamare quella corretta per il tuo scopo. ^[1][6]

• Token di accesso scaduti. I token OAuth di Zoho scadono tipicamente dopo un'ora. Se ricevi un errore di autenticazione su un'integrazione che funzionava in precedenza, aggiorna il token di accesso prima di riprovare. ^[4]

---

Cosa verificare

• Copertura degli scope: Conferma che il tuo token OAuth includa Desk.tickets.READ o Desk.tickets.ALL prima di effettuare la chiamata. ^[3]
• Percorso endpoint corretto: Verifica che l'URL contenga /timeEntries/summary e non solo /timeEntries, per assicurarti di ricevere i totali aggregati anziché un elenco grezzo. ^[1][6]
• ID ticket valido: Confronta il valore ticketId con il tuo portale Zoho Desk per confermare che appartenga all'organizzazione e al record ticket corretti. ^[1]