Come ottenere le voci di tempo sui ticket in Zoho Desk

Zoho Desk espone diversi endpoint API dedicati alla lettura delle voci di tempo su un ticket — dall'elenco di tutte le voci al recupero di un singolo record o di un riepilogo aggregato. Ecco come utilizzare ciascuno di essi in modo efficace.

Perché è importante

Il monitoraggio del tempo in Zoho Desk è essenziale per la fatturazione, la reportistica SLA e l'analisi della produttività degli agenti. Che tu abbia bisogno di estrarre tutte le ore registrate su un ticket di supporto, filtrare per tipo di fatturazione o visualizzare un riepilogo del tempo totale in una dashboard, l'API REST di Desk offre endpoint appositamente costruiti per ogni scenario. In qualità di supporto esperto indipendente (non supporto ufficiale Zoho), Beam Help ti guida attraverso ciascuna opzione qui di seguito.

Passo dopo passo

Passaggio 1. Verifica gli scope OAuth.

Prima di effettuare qualsiasi richiesta relativa alle voci di tempo, verifica che il tuo token OAuth includa almeno Desk.tickets.READ e Desk.tickets.ALL nell'elenco degli scope. Questi scope regolano l'accesso in lettura alle sotto-risorse dei ticket, incluse le voci di tempo. ^[7]

Passaggio 2. Elenca tutte le voci di tempo per un ticket.

Per recuperare ogni voce di tempo registrata su un ticket specifico, invia una richiesta GET a:

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

Sostituisci {ticketId} con l'ID numerico del ticket che stai interrogando. È possibile passare un dizionario opzionale p per controllare la paginazione o il filtraggio. ^[4]

Esempio (Python):

entries = desk_client.list_ticket_time_entries(ticketId="123456")

Passaggio 3. Recupera una singola voce di tempo tramite il suo ID.

Quando conosci già il timeEntryId specifico che vuoi esaminare, chiama l'endpoint del record individuale:

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

Sia ticketId che timeEntryId sono parametri di percorso obbligatori. Un dizionario opzionale p può contenere parametri di query aggiuntivi. ^[3]

Esempio (Python):

entry = desk_client.get_ticket_time_entry(ticketId="123456", timeEntryId="789")

Passaggio 4. Ottieni un riepilogo (totale) di tutto il tempo registrato.

Se hai bisogno solo dei totali aggregati anziché dei record individuali — utile per dashboard o riepiloghi di fatturazione — utilizza l'endpoint di riepilogo:

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

Questo restituisce una visualizzazione aggregata del tempo registrato per il ticket anziché un elenco di voci individuali. ^[5]

Esempio (Python):

summary = desk_client.get_summation_of_ticket_time(ticketId="123456")

Passaggio 5. Filtra le voci di tempo per tipo di fatturazione.

Per segmentare le voci di tempo in base al fatto che siano fatturabili o non fatturabili, utilizza il sotto-endpoint del tipo di fatturazione:

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

Passa eventuali criteri di filtro rilevanti tramite il dizionario del parametro p. ^[2]

Esempio (Python):

billable = desk_client.get_ticket_time_entries_by(ticketId="123456", p={"billingType": "Billable"})

Passaggio 6. Aggiorna una voce di tempo se sono necessarie correzioni.

Se una voce recuperata contiene dati errati, puoi modificarla con una richiesta PATCH a:

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

Fornisci i campi da modificare all'interno del dizionario data. ^[6]

Esempio (Python):

desk_client.update_ticket_time_entry(
    ticketId="123456",
    timeEntryId="789",
    data={"timeSpent": "02:30"}
)

Errori comuni

• Scope mancanti. Le richieste restituiranno un errore 401 o 403 se Desk.tickets.READ o Desk.tickets.ALL è assente dal token. Verifica sempre l'elenco degli scope durante la configurazione OAuth. ^[7]
• Confusione tra gli endpoint di riepilogo e di elenco. Il percorso /summary restituisce totali aggregati, non righe individuali. Tentare di iterarlo come un elenco causerà errori imprevisti. ^[5]
• Ordine del percorso errato. I sotto-percorsi /billingType e /summary devono comparire dopo /timeEntries nell'URL. Invertire o omettere qualsiasi segmento risulterà in un errore 404. ^[2][5]

Cosa verificare

• Conferma che il ticketId che stai utilizzando sia valido e appartenga al portale Zoho Desk della tua organizzazione prima di chiamare qualsiasi endpoint. ^[4]
• Verifica che il tuo token OAuth non sia scaduto e che contenga gli scope Desk.tickets corretti. ^[7]
• Dopo un aggiornamento tramite PATCH, recupera nuovamente la voce con gettickettime_entry per confermare che le modifiche siano state applicate come previsto. ^[3][6]