Come ottenere i dettagli del blueprint applicato in Zoho Desk

Recuperare il blueprint attualmente applicato a un ticket di Zoho Desk richiede una singola richiesta GET autenticata — nessun body necessario, solo un ID ticket valido e gli scope OAuth corretti.

Perché è importante

I blueprint in Zoho Desk impongono flussi di lavoro strutturati sui ticket, controllando quali transizioni gli agenti possono eseguire e quali dati devono essere acquisiti in ogni fase. Quando si creano integrazioni, automazioni o strumenti di audit, spesso è necessario ispezionare lo stato attivo del blueprint su un ticket specifico — ad esempio, per determinare quali pulsanti di transizione mostrare in un portale personalizzato, o per registrare la fase corrente a fini di conformità. Questa guida (di Beam Help — supporto esperto indipendente per Zoho, non supporto ufficiale Zoho) ti mostra esattamente come farlo tramite l'API REST di Zoho Desk.

---

Procedura passo dopo passo

Passaggio 1. Verifica che gli scope OAuth siano configurati.

Prima di effettuare qualsiasi chiamata API, verifica che il tuo token OAuth includa gli scope necessari per i ticket di Zoho Desk. Come minimo hai bisogno di Desk.tickets.READ nell'elenco degli scope autorizzati — scope più ampi come Desk.tickets.ALL soddisfano anch'essi questo requisito. ^[5]

Passaggio 2. Identifica l'ID del ticket di destinazione.

Hai bisogno del ticketId interno di Zoho Desk per il ticket di cui vuoi ispezionare il blueprint. Si tratta dell'identificatore numerico restituito quando un ticket viene creato o elencato — non il numero di ticket leggibile dall'utente mostrato nell'interfaccia. Se non lo hai ancora, recuperalo da una precedente chiamata di elenco o ricerca.

Passaggio 3. Chiama l'endpoint "Get Applied Blueprint Details".

Invia una richiesta HTTP GET al seguente percorso, sostituendo il tuo ID ticket effettivo:

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

Includi il tuo bearer token OAuth nell'intestazione Authorization come di consueto. Un dizionario di parametri di query opzionale (p) può essere passato se hai bisogno di filtrare o paginare la risposta, ma nella maggior parte dei casi non sono necessari parametri aggiuntivi. ^[1]

In Python, utilizzando il wrapper client di Zoho Desk, la chiamata si presenta così:

result = client.op_7_get_applied_blueprint_details(ticketId="1234567890")

Il metodo invia una GET a /api/v1/tickets/{ticketId}/blueprint e restituisce la risposta analizzata. ^[1]

Passaggio 4. Analizza la risposta.

Il corpo della risposta contiene i dettagli del blueprint attualmente applicato a quel ticket — inclusi gli stati di transizione attivi e i requisiti dei campi associati. Ispeziona l'oggetto restituito per trovare la fase corrente, le transizioni disponibili e gli eventuali campi obbligatori che devono essere compilati prima che una transizione possa procedere.

Passaggio 5. (Facoltativo) Confronta con la definizione del blueprint.

Se hai bisogno dello schema completo del blueprint — tutte le fasi, tutte le transizioni, tutte le condizioni — anziché solo lo stato applicato su un ticket, puoi recuperare la definizione del blueprint direttamente tramite il suo ID:

GET /api/v1/blueprints/{blueprintId}

Questo restituisce la configurazione completa del blueprint indipendentemente da qualsiasi ticket specifico. ^[2]

Per scoprire quali blueprint esistono in un dipartimento, puoi anche elencarli tutti:

GET /api/v1/blueprints

Questo restituisce ogni blueprint configurato nel dipartimento, utile per mappare gli ID dei blueprint prima di approfondire una definizione specifica. ^[7]

---

Errori comuni

• Tipo di ID errato. Passare il numero di ticket leggibile dall'utente (es. #1042) invece del ticketId numerico interno produrrà un errore 404 o di record non valido. Usa sempre l'ID generato dal sistema. ^[1]

• Scope OAuth mancante o insufficiente. Se il tuo token è stato generato senza Desk.tickets.READ (o uno scope più ampio equivalente come Desk.tickets.ALL), l'API restituirà un errore di autorizzazione. Rigenera il token includendo gli scope corretti. ^[5]

• Blueprint non applicato. Se nessun blueprint è stato applicato al ticket, l'endpoint potrebbe restituire un oggetto blueprint vuoto o null anziché un errore. Gestisci questo caso in modo appropriato nella logica della tua integrazione, senza assumere che un blueprint sia sempre presente. ^[1]

• Confusione tra endpoint a livello di ticket ed endpoint a livello di definizione. L'endpoint /api/v1/tickets/{ticketId}/blueprint restituisce lo stato *applicato* per un ticket specifico, mentre /api/v1/blueprints/{blueprintId} restituisce la *definizione* di un blueprint. Questi servono scopi diversi — non sostituire l'uno con l'altro. ^[1][2]

---

Cosa verificare

• Verifica degli scope: Conferma che il tuo token OAuth attivo includa Desk.tickets.READ o Desk.tickets.ALL prima di effettuare la chiamata. ^[5]
• ID ticket corretto: Verifica che il ticketId che stai passando sia l'ID di sistema interno, non il numero visualizzato nell'interfaccia di Zoho Desk. ^[1]
• Gestione della risposta: Assicurati che il tuo codice gestisca il caso in cui il campo blueprint sia vuoto o null, indicando che nessun blueprint è attualmente applicato a quel ticket. ^[1]