Come ottenere la registrazione del tempo di un agente in Zoho Desk

L'API REST di Zoho Desk espone tre endpoint dedicati che consentono di recuperare i dati di registrazione del tempo per qualsiasi agente — come elenco completo, singolo record o filtrati per tipo di fatturazione.

Perché è importante

Quando è necessario verificare come gli agenti impiegano il loro tempo, generare report di fatturazione o trasferire i dati di tracciamento del tempo in un sistema esterno, devi essere in grado di interrogare le registrazioni del tempo degli agenti in modo programmatico. Zoho Desk fornisce operazioni API appositamente progettate per questo caso d'uso, e sapere quale endpoint chiamare — e con quali parametri — consente di risparmiare un notevole sforzo di sviluppo.

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

---

Procedura passo dopo passo

Passaggio 1. Identifica l'agente di cui hai bisogno delle registrazioni del tempo.

Ogni richiesta richiede un agentId. Questo è l'identificatore univoco del record agente all'interno della tua organizzazione Zoho Desk. Puoi ottenerlo dalla sezione Agenti del pannello di amministrazione di Desk o da una precedente chiamata API che restituisce oggetti agente. Tieni questo valore a portata di mano — compare nel percorso URL per tutte e tre le operazioni seguenti. ^[5]

Passaggio 2. Elenca tutte le registrazioni del tempo per un agente.

Invia una richiesta GET al seguente percorso, sostituendo l'identificatore dell'agente:

GET /api/v1/agents/{agentId}/timeEntries

L'operazione si chiama listagenttime_entries. Un parametro opzionale p consente di passare filtri nella stringa di query (come paginazione o intervallo di date) insieme alla richiesta. In Python la chiamata si presenta così:

client.list_agent_time_entries(agentId="12345678", p={"from": 1, "limit": 50})

Questo restituisce l'intera raccolta di registrazioni del tempo associate a quell'agente. ^[5]

Passaggio 3. Recupera una singola registrazione del tempo specifica.

Se conosci già l'identificatore di una particolare registrazione del tempo — ad esempio, dall'elenco restituito nel Passaggio 2 — puoi recuperare solo quel record con:

GET /api/v1/agents/{agentId}/timeEntries/{timeEntryId}

L'operazione si chiama getagenttime_entry e richiede sia agentId che timeEntryId come parametri di percorso. Il dizionario opzionale p può contenere eventuali parametri di query aggiuntivi necessari per la tua integrazione. ^[7]

client.get_agent_time_entry(agentId="12345678", timeEntryId="98765432")

Passaggio 4. Filtra le registrazioni del tempo per tipo di fatturazione.

Quando vuoi solo le voci che corrispondono a una classificazione di fatturazione specifica (ad esempio, fatturabile vs. non fatturabile), utilizza la variante dell'endpoint per tipo di fatturazione:

GET /api/v1/agents/{agentId}/timeEntries/billingType

L'operazione si chiama getagenttimeentriesby. Passa il tipo di fatturazione desiderato tramite il dizionario del parametro p. Questo è particolarmente utile per generare fatture o riconciliare le ore fatturabili. ^[3]

client.get_agent_time_entries_by(agentId="12345678", p={"type": "Billable"})

Passaggio 5. Gestisci la risposta.

Tutti e tre gli endpoint restituiscono JSON. Analizza il corpo della risposta per estrarre i campi di registrazione del tempo di cui hai bisogno — come durata, riferimento al ticket e classificazione di fatturazione — e mappali nel tuo flusso di lavoro di reporting o fatturazione. ^[5][7][3]

---

Errori comuni

• Formato agentId errato. Passare un nome visualizzato o un'email invece dell'ID agente numerico risulterà in una risposta 404 o vuota. Risolvi sempre l'ID agente dall'API prima di costruire la tua richiesta. ^[5]
• Confondere l'endpoint per tipo di fatturazione con l'endpoint elenco. Il percorso /timeEntries/billingType è una route distinta, non una sotto-risorsa di una voce specifica. Non inserire un timeEntryId tra timeEntries e billingType. ^[3]
• Parametri di paginazione mancanti. L'endpoint elenco (/timeEntries) può restituire un set di risultati paginato. Se ometti i controlli di paginazione nel dizionario p, potresti ricevere solo la prima pagina di voci e perdere silenziosamente i record più vecchi. ^[5]

---

Cosa verificare

• Conferma che l'agentId che stai utilizzando corrisponda a un agente attivo nella tua organizzazione Zoho Desk prima di effettuare richieste in blocco.
• Verifica che le tue credenziali API abbiano il permesso di lettura per l'ambito Time Entry; senza di esso, tutti e tre gli endpoint restituiranno un errore di autorizzazione.
• Dopo aver recuperato le voci, confronta almeno un record con l'interfaccia utente di Zoho Desk (profilo agente → registrazioni del tempo) per confermare che i dati corrispondano a quanto visualizzato nel portale. ^[5][7][3]