Guida per amministratori all’API Zendesk

Che cos'è l'API Zendesk?

Un’API, o Application Programming Interface, è uno strumento per le applicazioni software. Se pensi a un ristorante, il cameriere porta i piatti dalla cucina al tuo tavolo. L’API funziona in modo simile: Trasferisce i dati da un punto all’altro. Nell’API, il piatto è chiamato risorsae il waiter che lo trasporta è chiamato endpoint. Pensa a un piatto specifico che potresti richiedere al ristorante. Alcuni endpoint restituiscono una raccolta di elementi, ad esempio un vassoio di campionamento. Un esempio nell’API potrebbe essere l’ endpoint List Users. Restituisce un elenco di tutti gli utenti nel tuo account Zendesk Support. Alcuni endpoint, come l’endpointMostra utente, sono più mirati e restituiscono solo un singolo elemento.

Puoi anche usare l’API per apportare modifiche in Zendesk. Immagina di dire a un cameriere come vorresti cucinare la tua bistecca. Lo chef cambierà effettivamente la bistecca in base alle tue esigenze. L’API è una potente risorsa che molti dei nostri clienti usano per importare in blocco risorse, creare app, trasferire dati a origini esterne e altro ancora.

La maggior parte della documentazione di riferimento per l’API Zendesk è disponibile nella sezione Riferimento APIdel portale per sviluppatori Zendesk. La documentazione di riferimento descrive tutti gli endpoint disponibili. Per iniziare, puoi anche usare la guida per sviluppatori Zendesk . Sebbene la documentazione sia completa, in questo articolo esamineremo come decodificarli e usarli.

Perché usare l'API?

Ora che sai cos'è l'API, potresti chiederti: "Perché dovrebbe interessarmi?" In poche parole, puoi usare l’API per aggiungere funzionalità che non sono disponibili nell’interfaccia utente (nativa o a livello di piano) a un ritmo molto più rapido rispetto al tentativo di eseguire tutte le operazioni manualmente.

Per gli account attualmente con piani Essential o Team, l’uso dell’API consente di avere un metodo diretto per esportare i dati senza dover passare a Professional (che consente l’esportazione automatizzata dei dati). Allo stesso modo, puoi usare l’API per ottenere i dati dei ticket a scopo di report. L’API può restituire tutte le informazioni correlate a un ticket, quindi puoi usare l’output dell’API per trasferire i dati a un’applicazione di report di terzi.

La possibilità di aggiornare rapidamente molti record è un altro vantaggio dell’uso dell’API. Ad esempio, mentre puoi creare una sola organizzazione alla volta nell’interfaccia agente, puoi creare fino a 100 organizzazioni alla volta con l’API. Allo stesso modo, le limitazioni al numero di elementi che puoi aggiornare alla volta sono più elevate con l’API. L’interfaccia consente di modificare 60 ticket contemporaneamente, mentre l’API consente di modificare fino a 100 ticket.

Altre attività comuni includono:

• Creazione di ticket
• Migrazione dei dati dei ticket in Zendesk da un altro sistema
• Modifica degli utenti in blocco
• Ricerca di record
• E molto altro!

Ora che abbiamo spiegato perché dovresti usare l’API, vediamo come effettuare una richiesta API.

Formato

L’API Zendesk restituisce i dati in un formato leggero chiamato JSON. Consulta Utilizzo di JSON nel Centro assistenza Zendesk. Puoi visualizzare i dati formattati in un browser web installando un’estensione del visualizzatore JSON perChromeo Firefox.

JSON ha il seguente aspetto:

{
  "posts": [
    {
      "id": 35467,
      "title": "How do I open the safe"
    },
    {
      "id": 35468,
      "title": "How do I reset the combination?"
    },
  ]
}

Un tipico endpoint ha il seguente aspetto:

subdomain.zendesk.com/api/v2/users/me.json

Gli endpoint possono eseguire le azioni seguenti:

• GET - Recupera elementi 
• POST - Crea elementi che prima non esistevano
• PUT - Aggiorna elementi esistenti
• DELETE - Rimuovi elementi

In un browser, puoi effettuare solo richieste GET. Puoi eseguire le altre azioni usando strumenti come cURL o Postman.

cURL

La documentazione di riferimento usa cURL in tutti gli esempi di endpoint. cURL è uno strumento da riga di comando che ti consente di provare i comandi API senza un browser. Per maggiori informazioni, consulta Installazione e uso di cURL nel Centro assistenza Zendesk. Puoi usare cURL per uno qualsiasi dei 4 tipi di chiamata. È preinstallato su un Mac, ma dovrai installarlo su Windows. Per istruzioni, consulta Installazione di cURL nel Centro assistenza Zendesk.

Stato delle richieste

Per ogni richiesta API che effettui, ricevi una risposta che ti informa se ha funzionato o meno. In caso contrario, la risposta fornirà indizi sul motivo per cui la richiesta non ha funzionato. Queste risposte sono denominate codici di stato. Alcuni di quelli di base sono i seguenti:

• 200 - La richiesta è riuscita
• 400 - Richiesta non riuscita
• 409 - Errore di unione o vincolo, riprova a chiamare
• 422 - Entità non elaborabile
• 429 - Limite di frequenza superato
• 500 - Avviso o stato temporaneo. Se il problema persiste, contatta l’assistenza

Per maggiori dettagli sui codici di stato, consulta Formato di risposta nella documentazione API.

Pratica

Ora che abbiamo esaminato le nozioni di base di un’API, possiamo usarla per cercare nei ticket.

Supponiamo che io abbia un piano a livello di team e abbia usato i tag per tenere traccia dell’escalation dei ticket a diversi livelli di assistenza. I tag che aggiungo sono escalation_one ed escalation_two.

Ora voglio generare un report di tutti i ticket nel mio sistema che hanno raggiunto entrambe le escalation. Ho provato a creare una vista per restituire questi ticket, ma non ha soddisfatto le mie esigenze perché i ticket archiviati non sono stati mostrati. Cosa devo fare adesso?

Risposta: Usa l’API per ottenere i ticket.

A tale scopo, dai un’occhiata all’endpoint API di ricerca. Questo endpoint non filtra i ticket archiviati, quindi puoi usarlo per restituire un elenco di tutti i ticket che includono questi due tag. Allo stesso modo, l’API di ricerca è una semplice chiamata GET, quindi puoi usarla direttamente nel browser se hai effettuato l’accesso a Zendesk Support in un’altra scheda del browser. Il formato dell’endpoint di ricerca è il seguente:

subdomain.zendesk.com/api/v2/search.json?query={search_string}

Importante: Assicurati di sostituire “sottodominio” con il sottodominio del tuo account.

L’API di ricerca è molto flessibile e la query può usare tutto ciò che è indicato nella Guida di riferimento di Zendesk Search. Nel nostro esempio, poiché stiamo semplicemente cercando tag, l'unico parametro che useremo nella nostra stringa di ricerca è "tag". Per cercare più tag, aggiungi una virgola tra i tag dopo il parametro "tag". Ora la chiamata dovrebbe avere il seguente aspetto:

https://subdomain.zendesk.com/api/v2/search.json?query=tags:escalation_one,escalation_two

Per autenticare la richiesta, assicurati di essere un agente o un amministratore e di aver effettuato l’accesso a Zendesk Support in un’altra scheda del browser.

L’esecuzione di questa chiamata nel browser restituisce un elenco di ticket con entrambi questi tag. Puoi quindi salvare l’output JSON per un uso futuro.

Complimenti, Sei arrivato alla fine. L’API è uno strumento potente con molti usi. Da qui puoi iniziare ad approfondire la documentazione diriferimentoe la documentazione per sviluppatori Zendesk.

Avvertenza sulla traduzione: questo articolo è stato tradotto usando un software di traduzione automatizzata per fornire una comprensione di base del contenuto. È stato fatto tutto il possibile per fornire una traduzione accurata, tuttavia Zendesk non garantisce l'accuratezza della traduzione.

Per qualsiasi dubbio sull'accuratezza delle informazioni contenute nell'articolo tradotto, fai riferimento alla versione inglese dell'articolo come versione ufficiale.