Come elencare le voci di tempo di un ticket in Zoho Desk

Elencare tutte le voci di tempo registrate su un ticket di Zoho Desk è semplice, una volta che si conosce il corretto endpoint API e gli scope OAuth necessari. Questo articolo ti guida attraverso l'intero processo — dall'autenticazione all'interpretazione della risposta.

Perché è importante

Le voci di tempo registrano quanto tempo gli agenti trascorrono a lavorare su un ticket, e recuperarle in modo programmatico ti consente di creare report di fatturazione, verificare l'impegno degli agenti o inviare dati a strumenti esterni di gestione paghe e fatturazione. Se stai integrando Zoho Desk con un sistema di terze parti, o vuoi semplicemente estrarre i dati di monitoraggio del tempo in blocco, questo endpoint è il tuo punto di partenza. Tieni presente che Beam Help è un supporto esperto indipendente per Zoho — non siamo il supporto ufficiale Zoho.

Passo dopo passo

Passaggio 1. Verifica che i tuoi scope OAuth includano i permessi per i ticket.

Prima di effettuare qualsiasi chiamata API, verifica che il tuo client OAuth connesso abbia ricevuto gli scope Desk necessari. Come minimo hai bisogno di Desk.tickets.READ nella tua stringa di scope; una configurazione più ampia include anche Desk.tickets.ALL insieme agli scope per contatti, attività e altri moduli. ^[2]

Passaggio 2. Identifica l'ID del ticket che vuoi interrogare.

Ogni richiesta di voci di tempo è limitata a un singolo ticket. Individua il ticketId numerico o alfanumerico del ticket in questione — puoi trovarlo nell'URL di Zoho Desk quando visualizzi il ticket, oppure recuperarlo in modo programmatico tramite l'endpoint dell'elenco ticket. ^[3]

Passaggio 3. Invia una richiesta GET all'endpoint delle voci di tempo.

Esegui una GET HTTP al seguente percorso, sostituendo il tuo identificatore di ticket effettivo:

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

In Python, utilizzando un wrapper client preconfigurato, la chiamata si presenta così:

def list_ticket_time_entries(self, ticketId: str, p: dict = None):
    return self.c.request("GET", f"/api/v1/tickets/{ticketId}/timeEntries", p, None)

Il parametro opzionale p accetta un dizionario di parametri query-string (ad esempio, opzioni di paginazione o filtraggio). ^[3]

Passaggio 4. (Facoltativo) Filtra i risultati per tipo di fatturazione.

Se hai bisogno solo di voci raggruppate o filtrate per la loro classificazione di fatturazione, utilizza invece la sotto-risorsa dedicata al tipo di fatturazione:

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

Questo restituisce le voci di tempo organizzate per categoria di fatturazione anziché come elenco piatto. ^[6]

Passaggio 5. (Facoltativo) Recupera un riepilogo aggregato invece delle singole voci.

Quando hai bisogno di totali aggregati — come le ore fatturabili totali per un ticket — chiama l'endpoint di riepilogo:

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

Questo ti fornisce una somma di tutto il tempo registrato sul ticket senza restituire ogni singolo record. ^[7]

Passaggio 6. Gestisci la paginazione con il parametro p.

Sia l'endpoint dell'elenco principale che l'endpoint del tipo di fatturazione accettano un dizionario p per i parametri di query. Passa le chiavi di paginazione (come from e limit) all'interno di questo dizionario per scorrere set di risultati di grandi dimensioni. ^[3][6]

Passaggio 7. Crea o aggiorna le voci se necessario.

Una volta che riesci a leggere le voci, potresti volerle anche scrivere. Per registrare una nuova voce, invia una POST allo stesso percorso base con un payload data:

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

Per modificare una voce esistente, utilizza una richiesta PATCH che include anche il timeEntryId:

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

^[8][4]

Errori comuni

• Scope mancanti o insufficienti. Se il tuo token è stato generato senza Desk.tickets.READ (o Desk.tickets.ALL), l'API restituirà un errore di autorizzazione. Rigenera il tuo token OAuth con la stringa di scope corretta prima di riprovare. ^[2]
• Formato ID ticket errato. Passare un *numero* di ticket (il riferimento leggibile dall'utente mostrato nell'interfaccia) invece dell'*ID* interno del ticket risulterà in una risposta 404 o vuota. Utilizza sempre l'identificatore interno. ^[3]
• Confondere l'endpoint dell'elenco con l'endpoint di riepilogo. Il percorso /timeEntries restituisce record individuali; /timeEntries/summary restituisce totali aggregati. Chiamare quello sbagliato ti fornirà dati in una forma inaspettata. ^[3][7]

Cosa verificare

• Conferma che il tuo token di accesso OAuth includa Desk.tickets.READ o Desk.tickets.ALL negli scope concessi prima di effettuare la richiesta. ^[2]
• Verifica che il ticketId nel percorso della tua richiesta sia l'ID del record interno di Zoho Desk, non il numero di ticket visualizzato. ^[3]
• Se ti aspetti più pagine di risultati, assicurati di passare i parametri di paginazione appropriati all'interno del dizionario p in modo che nessuna voce venga omessa silenziosamente. ^[3][6]