O que é a API do Zendesk?
Uma API, sigla em inglês de interface de programação de aplicativo, é uma ferramenta para aplicativos de software. Se pensarmos em um restaurante, o garçom carrega os pratos da cozinha até a sua mesa. A API funciona de maneira semelhante: ela leva os dados de um ponto até outro. Na API, o prato é chamado de recurso e o garçom que o leva até você é chamado de ponto de extremidade. Imagine um prato específico que você possa pedir em um restaurante. Alguns pontos de extremidade trazem a você uma coleção de itens como um prato de amostras. Um exemplo disso na API seria o ponto de extremidade List Users. Ele retorna uma lista de todos os usuários em sua conta do Zendesk Support. Alguns pontos de extremidade, como o ponto de extremidade Show User, têm um foco mais preciso e retornam apenas um único item.
Você também pode usar a API para fazer alterações em itens no Zendesk. Imagine descrever ao garçom como você gostaria que seu filé fosse preparado. O chef mudaria o filé para se adequar a você. A API é um recurso poderoso, que muitos clientes usam para importar em massa recursos, criar aplicativos, extrair dados para fontes externas e muito mais.
A maior parte da documentação de referência da API do Zendesk está disponível na seção de referência da API do portal do desenvolvedor do Zendesk. A documentação de referência descreve todos os pontos de extremidade disponíveis. Você também pode usar o guia do desenvolvedor da Zendesk para começar agora. Embora a documentação seja abrangente, veremos neste artigo como decodificar e usar os pontos de referência.
Por que usar a API?
Agora que você sabe o que é a API, talvez esteja se perguntando "Que diferença isso faz para mim"? Resumidamente, você pode usar a API para adicionar funções que não estão disponíveis na interface de usuário (nativamente ou no nível de seu plano) em um ritmo muito mais ágil do que se tentar fazer isso manualmente.
Em contas dos planos Essential ou Team, o uso da API permite que você tenha um método direto para exportar seus dados sem a necessidade de atualizar para o Professional (que permite exportações de dados automáticas). De modo semelhante, você pode usar a API para obter dados de tickets para relatórios. A API pode retornar todas as informações relacionadas a um ticket, portanto você pode usar a saída da API para transferir dados a um aplicativo de relatórios de terceiros.
A capacidade de atualizar rapidamente vários registros é outro benefício do uso da API. Por exemplo, enquanto você consegue criar apenas uma única organização de cada vez na interface do agente, pode criar até 100 organizações por vez com a API. Da mesma forma, as restrições de quantidade de itens que podem ser atualizados por vez são maiores com a API. A interface permite a edição de 60 tickets por vez, enquanto a API permite até 100 tickets.
Outras tarefas comuns incluem:
- Criação de tickets
- Migração de dados de tickets de outro sistema para o Zendesk
- Edição de usuários em massa
- Pesquisa de registros
- E muito mais!
Agora que descrevemos os motivos para você usar a API, vejamos como fazer uma solicitação de API.
Formato
A API do Zendesk retorna dados em um formato leve denominado JSON. Consulte Trabalho com JSON na Central de Ajuda do Zendesk. Você pode visualizar os dados formatados em um navegador da web instalando uma extensão do visualizador de JSON para Chrome ou Firefox.
O JSON tem esta aparência:
{
"posts": [
{
"id": 35467,
"title": "How do I open the safe"
},
{
"id": 35468,
"title": "How do I reset the combination?"
},
]
}Um ponto de extremidade típico tem esta aparência:
subdomain.zendesk.com/api/v2/users/me.json
Os pontos de extremidade podem realizar as seguintes ações:
- GET - recuperar itens
- POST - criar itens que não existiam antes
- PUT - atualizar itens existentes
- DELETE - remover itens
Em um navegador, somente é possível fazer solicitações GET. Você pode executar outras ações usando ferramentas como cURL ou Postman.
cURL
A documentação de referência usa cURL em todos os exemplos de ponto de extremidade. cURL é uma ferramenta de linha de comando que permite que você experimente comandos da API sem um navegador. Para obter mais informações, consulte Instalação e uso de cURL na Central de Ajuda da Zendesk. Você pode usar cURL em qualquer dos 4 tipos de chamadas. Ela vem pré-instalada no Mac, mas você precisará instalá-la no Windows. Consulte as orientações em Instalação de cURL na Central de Ajuda da Zendesk.
Status de suas solicitações
Para cada solicitação de API que você fizer, receberá uma resposta informando se ela funcionou ou não. Em caso negativo, a resposta dará indicações de por que a solicitação não funcionou. Essas respostas são denominadas códigos de status. Estas são algumas das respostas básicas:
- 200 - A solicitação teve êxito
- 400 - Falha na solicitação
- 409 - Erro de fusão ou restrição, tente a chamada novamente
- 422 - Entidade não processável
- 429 - Limite de taxa excedido
- 500 - Aviso ou status temporário, entre em contato com o suporte se persistir
Consulte Formato de resposta nos documentos da API para ver mais detalhes sobre os códigos de status.
Prática
Agora que já falamos das noções básicas de uma API, vamos usá-la para fazer pesquisas em nossos tickets.
Digamos que sou um usuário no plano Team e tenho usado tags para monitorar quando os tickets são transferidos para níveis de suporte diferentes. As tags que adiciono são escalation_one e escalation_two.
Agora desejo gerar um relatório de cada ticket de meu sistema que já passou por ambas as transferências. Tentei criar uma visualização para retornar esses tickets, mas ela não atende às minhas necessidades, pois os tickets arquivados não são mostrados. O que faço agora?
Resposta: use a API para obter os tickets!
Para fazer isso, verifique o ponto de extremidade da API Search. Esse ponto de extremidade não exclui tickets arquivados, portanto você pode usá-lo para retornar uma lista de todos os tickets que incluem essas duas tags. De maneira semelhante, a API Search é uma chamada GET simples, portanto, você pode usá-la diretamente em seu navegador se tiver entrado no Zendesk Support em outra aba do navegador. O formato do ponto de extremidade Pesquisa é este:
subdomain.zendesk.com/api/v2/search.json?query={search_string}
Importante: substitua "subdomínio" pelo subdomínio de sua conta.
A API Search é bastante flexível, e a consulta pode usar qualquer item escrito na referência de pesquisa do Zendesk. Em nosso exemplo, como estamos apenas procurando tags, o único parâmetro que usaremos em nossa cadeia de caracteres de pesquisa será "tags". Para pesquisar várias tags, basta adicionar uma vírgula entre as tags após o parâmetro "tags". A chamada deve ter esta aparência:
https://subdomain.zendesk.com/api/v2/search.json?query=tags:escalation_one,escalation_two
Para autenticar a solicitação, você deve ser um agente ou administrador e ter entrado no Zendesk Support em outra aba em seu navegador.
A execução dessa chamada em seu navegador retornará uma lista de tickets com ambas as tags. Você pode salvar a saída JSON para uso futuro.
Parabéns! Você chegou ao final! A API é uma ferramenta poderosa e versátil. Deste ponto em diante, você pode se aprofundar na documentação de referência e na documentação do desenvolvedor do Zendesk.