Come ottenere le voci di tempo dei ticket per tipo di fatturazione in Zoho Desk

Recuperare le voci di tempo dei ticket filtrate per tipo di fatturazione in Zoho Desk è semplice grazie a un endpoint API dedicato che circoscrive i risultati a un singolo ticket e li raggruppa per classificazione di fatturazione.

Perché è importante

Quando il tuo team di supporto registra il tempo sui ticket, non tutte le ore hanno lo stesso stato di fatturazione — alcune possono essere fatturabili, altre non fatturabili o gratuite. La possibilità di estrarre le voci di tempo segmentate per tipo di fatturazione ti consente di riconciliare le fatture, verificare l'impegno degli agenti e alimentare i flussi di lavoro di fatturazione a valle senza dover filtrare manualmente un elenco completo di voci di tempo.

Procedura passo dopo passo

Passaggio 1. Identifica il ticketId del ticket di cui vuoi recuperare le voci di tempo. Si tratta dell'identificatore univoco che Zoho Desk assegna a ogni ticket di supporto — puoi trovarlo nell'URL del ticket oppure interrogando prima l'endpoint dell'elenco dei ticket. ^[1]

Passaggio 2. Esegui una richiesta GET all'endpoint per tipo di fatturazione, sostituendo l'identificatore del tuo ticket nel percorso:

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

Questa operazione (gettickettimeentriesby) restituisce le voci di tempo per il ticket specificato, organizzate per tipo di fatturazione. ^[1]

Passaggio 3. Passa eventuali parametri di query opzionali utilizzando l'argomento dizionario p. L'endpoint accetta un parametro p che può contenere opzioni di paginazione o filtro insieme al ticketId obbligatorio. ^[1]

Passaggio 4. Se stai effettuando la chiamata da Python, il metodo wrapper si presenta come segue:

result = client.get_ticket_time_entries_by(
    ticketId="your_ticket_id_here",
    p={"page": 1}   # optional query params
)

Il metodo invia una richiesta GET al percorso costruito e restituisce il payload della risposta contenente le voci di tempo raggruppate per tipo di fatturazione. ^[1]

Passaggio 5. Analizza la risposta per estrarre i raggruppamenti per tipo di fatturazione. Ogni voce nella risposta conterrà il tempo registrato e la relativa classificazione di fatturazione, che potrai quindi utilizzare per la fatturazione o la reportistica. ^[1]

---

Endpoint correlati da conoscere

Il pattern di filtro per tipo di fatturazione è coerente in diverse entità di Zoho Desk, quindi puoi applicare lo stesso approccio a diversi livelli del tuo modello di dati:

• Voci di tempo a livello di account per tipo di fatturazione: GET /api/v1/accounts/{accountId}/timeEntries/billingType ^[2]
• Voci di tempo a livello di contatto per tipo di fatturazione: GET /api/v1/contacts/{contactId}/timeEntries/billingType ^[5]
• Voci di tempo a livello di agente per tipo di fatturazione: GET /api/v1/agents/{agentId}/timeEntries/billingType ^[6]
• Voci di tempo a livello di attività per tipo di fatturazione: GET /api/v1/tasks/{taskId}/timeEntries/billingType ^[4]

Se hai bisogno di *tutte* le voci di tempo per un ticket senza il raggruppamento per tipo di fatturazione, utilizza invece l'endpoint gemello GET /api/v1/tickets/{ticketId}/timeEntries. ^[8]

Errori comuni

• Endpoint dell'entità errato: È facile chiamare accidentalmente la variante per account o contatto quando si intende quella per ticket. Verifica che il percorso contenga tickets/{ticketId} e non accounts/{accountId} o contacts/{contactId}. ^[1][2][5]
• ticketId mancante o non valido: Il ticketId è un parametro di percorso obbligatorio. Passare una stringa vuota o un intero dove è attesa una stringa causerà il fallimento della richiesta o l'instradamento verso la risorsa sbagliata. ^[1]
• Confondere questo endpoint con l'endpoint dell'elenco semplice: timeEntries/billingType e timeEntries sono operazioni distinte con strutture di risposta diverse — utilizza il percorso per tipo di fatturazione solo quando hai specificamente bisogno di voci segmentate per classificazione di fatturazione. ^[1][8]

Cosa verificare

• Conferma che il ticketId nel percorso della richiesta corrisponda a un ticket esistente nella tua organizzazione Zoho Desk prima di chiamare l'endpoint. ^[1]
• Verifica che le voci di tempo siano state effettivamente registrate sul ticket, poiché un ticket valido senza voci di tempo restituirà un risultato vuoto anziché un errore. ^[1][8]
• Se hai bisogno di una visione più ampia (ad esempio, tutto il tempo fatturabile relativo a un account), considera di passare all'endpoint per tipo di fatturazione a livello di account anziché iterare sulle singole chiamate per ticket. ^[2]

---

*Beam Help è una risorsa di supporto esperto indipendente per i prodotti Zoho e non rappresenta il supporto ufficiale Zoho. Verifica sempre il comportamento delle API rispetto al tuo specifico piano Zoho Desk e alla versione API in uso.*