Come eliminare un ruolo in Zoho Desk

L'eliminazione di un ruolo in Zoho Desk avviene tramite una singola chiamata API autenticata che individua il ruolo tramite il suo identificatore univoco. Ecco tutto ciò che ti serve per eseguire l'operazione correttamente.

Perché è importante

La gestione dei ruoli è fondamentale per controllare cosa possono vedere e fare i tuoi agenti Zoho Desk. Nel tempo, le organizzazioni accumulano ruoli ridondanti o obsoleti che rendono la configurazione disordinata e creano confusione tra gli amministratori. Sapere come rimuoverli in modo programmatico — invece di cercarli nell'interfaccia utente — fa risparmiare tempo e mantiene la configurazione ordinata, soprattutto quando si gestiscono ruoli su larga scala tramite automazione o integrazioni.

> Nota: Beam Help è un servizio di supporto esperto indipendente per Zoho — non siamo il supporto ufficiale Zoho.

---

Procedura passo dopo passo

Passaggio 1. Verifica di avere gli scope OAuth corretti.

Prima di effettuare qualsiasi chiamata API, verifica che il token OAuth di Zoho Desk collegato includa le autorizzazioni necessarie. Lo scope richiesto per le operazioni a livello di impostazioni (che include la gestione dei ruoli) è Desk.settings.DELETE — insieme agli scope correlati come Desk.settings.READ e Desk.settings.ALL per un accesso più ampio. ^[3]

Passaggio 2. Recupera il role_id che vuoi eliminare.

Non è possibile eliminare un ruolo senza conoscerne l'identificatore esatto. Utilizza una richiesta GET all'endpoint dei ruoli (oppure controlla il pannello di amministrazione di Zoho Desk) per elencare i ruoli esistenti e annotare il role_id di quello che vuoi rimuovere. Conserva questo valore — lo passerai direttamente nella chiamata di eliminazione.

Passaggio 3. Esegui la richiesta DELETE.

Invia una richiesta DELETE al seguente endpoint, sostituendo l'identificatore effettivo del ruolo a {role_id}: ^[1]

DELETE /api/v1/roles/{role_id}

Il nome dell'operazione è deleterole e accetta roleid come parametro principale del percorso, con un parametro opzionale p per eventuali opzioni di query aggiuntive. ^[1]

Passaggio 4. Utilizza il client helper Python (se applicabile).

Se stai lavorando con un'integrazione basata su Python, la chiamata corrisponde a un metodo client semplice. Passa il role_id come stringa e, facoltativamente, fornisci un dizionario per il parametro p: ^[1]

def delete_role(self, role_id: str, p: dict = None):
    return self.c.request("DELETE", f"/api/v1/roles/{role_id}", p, None)

Passaggio 5. Inizializza il client Desk con il corretto org_id.

Le chiamate API di Zoho Desk richiedono che l'ID organizzazione sia impostato sul client. Quando crei l'istanza ZohoDeskClient, passa l'orgid insieme al dominio API e al token di accesso. Se l'orgid non è ancora memorizzato, il client può individuarlo automaticamente chiamando l'endpoint delle organizzazioni e salvando il primo risultato. ^[6]

Passaggio 6. Gestisci il rinnovo del token in modo proattivo.

I token di accesso scadono. Racchiudi la chiamata di eliminazione all'interno di un flusso che verifica la validità del token e lo rinnova utilizzando il refreshtoken memorizzato prima che la richiesta venga inviata. Una funzione tokenrefresher dovrebbe recuperare il refresh token più recente dal tuo archivio dati, chiamare l'endpoint di rinnovo OAuth e aggiornare l'access_token memorizzato e il timestamp di scadenza. ^[6]

---

Errori comuni

• Endpoint del prodotto errato. Anche Zoho CRM dispone di un endpoint per l'eliminazione dei ruoli (DELETE /Contacts/roles/{roleid}), ma è destinato ai *ruoli dei contatti delle trattative* in CRM — non ai ruoli degli agenti Desk. ^[2] Assicurati di puntare a /api/v1/roles/{roleid} e di utilizzare un client autenticato per Desk, non un client CRM. ^[1]

• orgid mancante o scaduto. Zoho Desk richiede l'ID organizzazione in ogni richiesta. Se l'orgid è vuoto o non aggiornato, l'API rifiuterà la chiamata. Verifica sempre che sia valorizzato prima di eseguire l'eliminazione. ^[6]

• Scope OAuth insufficiente. Se il token è stato generato senza Desk.settings.DELETE (o il più ampio Desk.settings.ALL), l'API restituirà un errore di autorizzazione. Rigenera il token includendo l'intero gruppo di scope per le impostazioni. ^[3]

• Eliminazione di un ruolo con agenti ancora assegnati. L'API potrebbe rifiutare l'eliminazione di un ruolo a cui sono associati agenti attivi. Riassegna o rimuovi quegli agenti dal ruolo prima di tentare l'eliminazione.

---

Cosa verificare

• Copertura degli scope: Conferma che il token OAuth attivo includa Desk.settings.DELETE o Desk.settings.ALL prima di chiamare l'endpoint. ^[3]
• Endpoint e client corretti: Verifica di chiamare /api/v1/roles/{roleid} tramite un'istanza ZohoDeskClient — non un client CRM — e che l'orgid sia valorizzato. ^[1][6]
• Il ruolo non appare più: Dopo un DELETE riuscito, esegui una GET sull'elenco dei ruoli per confermare che il ruolo sia stato rimosso e che nessun agente si trovi inaspettatamente senza un'assegnazione di ruolo.