Como trabalhar com a API da Octadesk?
Escrito por Leon
atualizado
Quer utilizar a API da Octadesk e não sabe como? Vem com a gente que vamos te ajudar nisso. o/
Antes de tudo, você precisa saber que o link para acessar a documentação de nossa API está disponível aqui.
Vamos lá? 😉
O que é uma API?
A API (Application Programming Interface/ Interface de Programação de Aplicação) é um método utilizado para fazer com que os sistemas possam conversar entre si de forma simplificada, seguindo padrões e protocolos. Um exemplo das API’s em ação, muito utilizado em nosso dia adia, é o mecanismo de busca do Google, onde você consegue buscar qualquer termo e receber a resposta (resultado da busca) na tela do seu celular sem realizar muito esforço.
Como utilizar a documentação de API da Octadesk?
Existe uma série de termos que você precisa saber ao utilizar a API e abaixo listamos os mais importantes para te introduzir neste universo. o/
Dicionário de termos:
Cliente: É sempre quem inicia a comunicação com outro sistema. Um exemplo bem comum em nossas vidas seria o nosso navegador, em que a partir dele conseguimos enviar solicitações (acessar um site) para o dispositivo onde está armazenada a aplicação que precisamos;
Servidor: É quem recebe a solicitação. O servidor aloca as aplicações e outras informações que precisam estar disponíveis para os seus clientes acessarem;
GET: Utilizado como método de consulta, ou seja, ele vai buscar a informação em um sistema;
POST: Utilizado como método de criação, ou seja, ele irá criar o registro que precisamos em um sistema;
PUT: Utilizado como método de atualização, ou seja, após a criação da informação, você poderá utilizar esse método para atualizar essa informação caso seja necessário;
DELETE: utilizado como método de exclusão de registro;
Postman: Ferramenta que dá suporte à documentação das requisições feitas pela API. Ele possui ambiente para a documentação, execução de testes de API’s e requisições em geral.
Agora que você já está familiarizado com os termos, vamos te explicar com mais detalhes como utilizar nossa API.
A API da Octadesk permite fazer manipulações e consultas de informações do sistema por meio de JSON (JavaScript Object Notation), que é um formato leve de troca de dados. Só utilizamos esse formato JSON, ok? Não é possível utilizar nossa documentação de outra forma. Este formato é legível por humanos e fácil de entender, sendo amplamente utilizado na comunicação entre sistemas. Em JSON, os dados são organizados em objetos (coleção não ordenada de pares chave-valor) e arrays (lista ordenada de valores). A estrutura hierárquica permite representar informações complexas de maneira simples. Sua simplicidade facilita a análise e a geração de dados, sendo amplamente adotado em APIs, configurações de aplicativos e armazenamento de informações estruturadas.
Exemplo de Json:
{
"id": 123,
"nome": "Exemplo de Objeto",
"preco": 19.99,
"estoque": 50,
"disponivel": true,
"categorias": ["eletrônicos", "acessórios"]
}
No vídeo abaixo te mostramos como funciona a documentação de API da Octadesk. 🐙
Agora que você está familiarizado com nossa API, vamos colocar a mão de massa? =)
1. Obtendo o Token de acesso
Com nossa API é possível criar, editar e consultar informações. O primeiro passo é gerar um Access Token. O Access Token é a informação do usuário e suas permissões no formato JWT. Através dele é possível utilizar todas as outras funcionalidades e integrações das API’s.
Siga os passos abaixo para gerar o Access Token:
Acesse a documentação da API em: https://api-docs.octadesk.services/docs/;
Escolha a seção de “Login”;
Agora copie a URL base para inserir os endpoints e fazer as chamadas com sucesso;
Agora acesse o Postman e mude para POST o método de requisição;
Coloque a URL base na caixa de texto ao lado de POST colocando "https://" no início, ok?
Agora volte na documentação e copie os endpoints;
Agora volte mais uma vez no Postman e cole os endpoints na mesma caixa de texto anterior.
Agora voltamos na documentação de API e vemos que há 3 parâmetros que são obrigatórios para que a consulta retorne com sucesso: subdomain, apiToken e username;
Você deve copiar o "subdomain" e colar na seção de "Headers” no campo “Key" dentro do Postman;
Após isso dentro da Octadesk você vai obter seu subdomínio clicando em cima do seu nome no canto inferior esquerdo;
Agora cole o subdomínio ao lado de "subdomain" no Postman;
Volte na documentação e copie "apiToken";
Volte no Postman e coloque "apiToken" como chave também em "Headers" para que ele vire um parâmetro;
De volta à Octadesk, agora você precisa criar um "API Token" em "Tickets > Geral > Código de integração";
Você escolhe um nome e após confirma para copiar seu API Token;
Agora você volta no Postman e cola o API Token copiado na caixa correspondente ao lado de “apiToken”;
Como última chave temos o "Usarname" que você deve copiar da documentação;
O "Usarname" é sempre o e-mail utilizado para acessar a Octadesk e você deve colocá-lo na caixa de texto correspondente no Postman;
Prontinho! Temos tudo que precisamos e vamos clicar em "Send" que significa "Enviar" dentro do Postman;
Se seu retorno for “200 OK” a solicitação foi concluído com sucesso;
E assim já temos nosso Token Bearer, vamos aprender como utilizar? =)
Abaixo temos um vídeo explicativo com todo o passo a passo para gerar seu primeiro Access Token.🐙
2. Utilizando o Token Bearer na prática
Com o Access Token em mãos, você deve buscar o método da API conforme sua necessidade. Por exemplo, você pode incluir, consultar ou editar tickets no sistema. Abaixo temos um exemplo de como criar um novo ticket. Ah, é importante mencionar que nós estamos dando o exemplo utilizando o endpoint necessário para essa situação, mas você pode utilizar outros de acordo com a sua necessidade, ok?
No canto direito superior, selecione a seção "Tickets";
Como você deseja inserir o ticket, o método que deve ser utilizado é o POST.
De forma resumida:
A requisição deve ser encaminhada para a URL apontada de acordo com a opção selecionada no menu suspenso. Por exemplo, na imagem abaixo foi escolhida a opção “Tickets” e a URL para requisição é: https://api.octadesk.services/tickets/
Todas as chamadas seguintes no Postman deverão incluir na “Headers” a chave “Authorization” com o valor “Bearer” + “Token gerado nos passos anteriores“, onde {access-token} (Token gerado nos passos anteriores) deverá ser substituído. A figura abaixo exemplifica este preenchimento:
Pra essa API, a seção de Body é obrigatória para que a gente consiga passar todas as informações que precisam conter no ticket que você deseja criar. Na nossa documentação, para esse endpoint nós temos uma série de parâmetros que podem ser passados na seção de Body. Para este artigo nós vamos utilizar um Body simples conforme o exemplo abaixo:
{
"requester": {
"email": "COLOQUE AQUI O E-MAIL DO SOLICITANTE"
},
"summary": "COLOQUE AQUI O TÍTULO DESEJADO PARA O TICKET",
"comments": {
"public": {
"content": "COLOQUE AQUI TODO O CONTEÚDO DO COMENTÁRIO PÚBLICO (DESCRIÇÃO DO TICKET)"
}
}
}
No Postman essas informações deverão estar contidas nesta seção:
Após o preenchimento de todos os campos obrigatórios, você pode clicar em “Send” no Postman. Se a sua resposta for "200 OK", sua solicitação foi concluída com sucesso e o Postman retornará uma resposta parecida com a do print abaixo:
Essas respostas contém diversas informações importantes, como por exemplo o “number”, que se refere ao número do ticket e por meio dele você pode encontrar o ticket dentro de seu Octadesk.
Caso você tenha dúvida dos parâmetros aceitáveis em cada variável, basta clicar em “Model” para verificar os requisitos de cada variável.
Acima nós ensinamos como criar informações por meio do método POST, no vídeo abaixo vamos te mostrar como consultar informações por meio do método GET.
No vídeo abaixo consultamos listas padrões que temos em tickets na Octadesk e você aprende como utilizar o Token Bearer. Vamos lá?🐙
IMPORTANTE
É fundamental que você baixe o Postman clicando aqui para utilizar a API da Octadesk, ok?
Esperamos que esse texto tenha lhe ajudado a utilizar nossa API.
🐙 Dica do polvo 🐙
Para facilitar a integração com nossa API, recomendamos que você tenha o suporte de um desenvolvedor. Caso você não tenha, indicamos nossa parceira Facilita Muito, que possui conhecimento da nossa documentação e te auxiliará na construção da integração com base em suas necessidades. Você pode contatá-los por aqui!😉