Come ottenere una registrazione di tempo per un'attività in Zoho Desk

Recuperare una specifica registrazione di tempo per un'attività di Zoho Desk è semplice una volta che si dispone sia dell'ID attività che dell'ID della registrazione di tempo — una singola richiesta GET restituisce il record completo.

Perché è importante

Quando è necessario verificare le ore fatturabili, controllare il tempo registrato rispetto a un SLA, o inserire un record di tempo specifico in un flusso di lavoro di reportistica, recuperare una singola registrazione tramite il suo ID è l'approccio più preciso. Invece di elencare tutte le voci e filtrare lato client, questa chiamata mirata riduce le dimensioni del payload e mantiene l'integrazione efficiente. È inoltre la base per qualsiasi pattern di verifica-o-aggiornamento prima di modificare un record.

Procedura passo dopo passo

Passaggio 1. Identifica il taskId dell'attività di Zoho Desk di cui vuoi recuperare la registrazione di tempo. Si tratta dell'identificatore univoco dell'attività padre — puoi ottenerlo da una precedente chiamata di elenco attività o direttamente dall'URL dell'interfaccia di Desk. Tienilo a portata di mano; ogni endpoint delle registrazioni di tempo è associato a un'attività. ^[1]

Passaggio 2. Identifica il timeEntryId del log specifico che vuoi recuperare. Se non conosci ancora questo valore, chiama prima l'endpoint di elenco GET /api/v1/tasks/{taskId}/timeEntries per recuperare tutte le voci dell'attività, quindi annota l'ID del record di cui hai bisogno. ^[5]

Passaggio 3. Esegui una richiesta GET al seguente endpoint, sostituendo i valori reali ai parametri del percorso:

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

Sia taskId che timeEntryId sono parametri di percorso obbligatori. Un parametro opzionale p può essere passato come dizionario di query se la tua integrazione necessita di filtri aggiuntivi o di un contesto di paginazione. ^[1]

Passaggio 4. In Python, la chiamata si presenta così — passa i due ID come stringhe e, facoltativamente, fornisci un dizionario p per eventuali parametri di query aggiuntivi:

result = client.get_task_time_entry(
    taskId="your_task_id",
    timeEntryId="your_time_entry_id"
)

Il metodo esegue internamente una richiesta GET e restituisce la risposta analizzata contenente i dettagli della registrazione di tempo. ^[1]

Passaggio 5. Una volta ottenuto il record, puoi procedere con operazioni correlate in base al tuo caso d'uso:

• Per aggiornare la voce, usa PATCH /api/v1/tasks/{taskId}/timeEntries/{timeEntryId} con un payload data contenente i campi da modificare. ^[6]
• Per riepilogare tutto il tempo registrato per l'attività, chiama GET /api/v1/tasks/{taskId}/timeEntries/summary. ^[8]
• Per filtrare le voci per tipo di fatturazione, usa GET /api/v1/tasks/{taskId}/timeEntries/billingType. ^[4]
• Per creare una nuova registrazione di tempo per l'attività, usa POST /api/v1/tasks/{taskId}/timeEntries con il corpo dati appropriato. ^[3]

Errori comuni

• Ordine degli ID errato. Il percorso richiede prima taskId, poi timeEntryId. Invertirli produrrà un errore 404 o la restituzione di un record inatteso. Verifica entrambi i valori prima di effettuare la chiamata. ^[1]
• La registrazione di tempo appartiene a un'attività diversa. Un timeEntryId è valido solo sotto il taskId con cui è stato creato. Se lo si interroga sotto un'attività diversa, la richiesta fallirà. Conferma sempre l'attività padre prima di costruire l'URL. ^[1]
• Autenticazione mancante. Come tutte le chiamate all'API di Zoho Desk, questo endpoint richiede un token di accesso OAuth valido nelle intestazioni della richiesta. Assicurati che il token non sia scaduto prima di effettuare la chiamata. ^[7]
• Confusione tra elenco e recupero singolo. Se disponi solo dell'ID attività e non dell'ID della registrazione di tempo, devi prima chiamare l'endpoint di elenco (GET /api/v1/tasks/{taskId}/timeEntries) per scoprire gli ID delle voci disponibili — l'endpoint per il singolo record non funzionerà senza entrambi gli identificatori. ^[5]

Cosa verificare

• Conferma che entrambi gli ID siano corretti — verifica taskId e timeEntryId rispetto ai dati di Zoho Desk prima di effettuare la richiesta, per evitare discrepanze silenziose.
• Verifica che il payload della risposta contenga i campi attesi (ore registrate, tipo di fatturazione, proprietario, ecc.) e che il timeEntryId nella risposta corrisponda a quello richiesto. ^[1]
• Controlla la validità del token — se ricevi un errore di autenticazione, aggiorna il token di accesso OAuth e riprova la chiamata. ^[7]

---

*Beam Help è una risorsa di supporto esperto indipendente per i prodotti Zoho e non rappresenta il supporto ufficiale di Zoho. Per problemi a livello di piattaforma, fai sempre riferimento alla documentazione ufficiale e ai canali di supporto di Zoho.*