Se você precisa integrar o seu sistema a um outro sistema via API é necessário a URL da API (host) do seu servidor e um Token no sistema que permitirá a comunicação entre as duas plataformas. Neste tutorial, vamos mostrar como localizar seu Host, gerar um Token no sistema e quais são os cuidados que você deve ter para garantir a segurança da integração.
¶ URL API (host)
A URL API (host) de um sistema é uma estrutura de endereço que indica o local onde a API está disponível para acesso. No caso da URL https://seudominio/webservice/v1/, o "seudominio" é o nome de domínio do site onde a API está hospedada, o "webservice" é o diretório onde se encontra a API e o "v1" é a versão da API, a partir desse endereço é possível adicionar os demais endpoints responsáveis por retornar as informações sobre as tabelas do sistema.
Vale ressaltar que esse endereço funciona apenas para o consumo da API e não possui uma interface visual para ser acessada pelo navegador retornando apenas um pop-up solicitando os dados de usuário e senha que seriam referentes ao token.
¶ Gerando um Token API
Para gerar um token API é necessário seguir os seguintes passos:
- Acesse o Menu “Configurações”.
- Selecione a opção “Usuários”.
- Em seguida selecione a opção “Usuários” novamente.
- Na página dos usuários, clique em “Novo” ou “Editar” caso já tenha criado um usuário para a integração.
É importante que o usuário seja exclusivo para a integração, para que os Logs de alterações possam identificar se uma determinada ação foi realizada pelo usuário ou pela integração.
Após acessar o formulário de criação ou edição de usuários, você deve marcar a opção “Permite acesso ao webservice”, essa opção é a responsável por gerar o Token utilizado para acessar os recursos do sistema via API. Depois de marcar a opção, clique em “Salvar”, após salvar as alterações no formulário, o Token será gerado automaticamente.
É importante lembrar que o Token está vinculado ao usuário, portanto, se o e-mail ou a senha do usuário forem alterados, o Token também será alterado automaticamente. Além disso, se o grupo de usuários vinculado ao usuário não tiver as permissões necessárias, o Token não poderá acessar os recursos do sistema via API.
Caso tenha dúvidas sobre o processo de gerar um novo usuário, temos a seguinte wiki sobre o assunto: Usuários.
¶ Criando um Grupo de Usuários exclusivo para a integração API
Para ter um maior controle dos acessos que as integrações conseguem fazer no sistema e dos IPs que podem acessar o sistema via API, é recomendado criar um grupo de usuários exclusivo para as integrações.
Para gerar um grupo de usuários, é preciso seguir o seguinte passo a passo:
- Acesse o Menu “Configurações”.
- Selecione a opção “Usuários”.
- Em seguida selecione a opção “Grupo de Usuários”.
- Na página dos grupos de usuários, clique em “Novo” ou “Duplicar Grupo” caso já exista um grupo com as permissões necessárias ou aproximadas das necessárias para a integração.
Nesse caso, as permissões a serem liberadas devem ser confirmadas com a integração, já que as autorizações necessárias variam bastante de uma integração para outra.
Caso tenha dúvidas de como alterar as permissões de um grupo de usuários, temos a seguinte wiki sobre o assunto: Como Alterar as Permissões em cada Grupo de Usuário.
As integrações API normalmente solicitam a liberação de um IP para que o servidor onde está hospedado a aplicação tenha permissão de acesso ao sistema, para liberar os IPs da integração no grupo de usuários, siga o caminho:
- Acesse o Menu “Configurações”.
- Selecione a opção “Usuários”.
- Em seguida selecione a opção “Grupo de Usuários”.
- Na página dos grupos de usuários, clique em “Editar”.
Após editar o grupo, libere os IPs no campo indicado, separados por ponto e vírgula ( ; ).
Se você não quiser criar um grupo de usuários exclusivo para a integração, é possível liberar o acesso ao sistema para os IPs das integrações os inserindo no grupo de usuários onde foi vinculado o usuário Token, entretanto, para isso você deve liberar o bloco de IPs das integrações e dos seus próprios usuários que acessam o sistema, para que não haja perda de acesso ao IXC Provedor.
Caso queira saber mais sobre as redes permitidas no grupo de usuários, temos a seguinte wiki sobre o assunto: Redes Permitidas no acesso do grupo.
Gerar um Token para integrações API é um processo simples, mas é importante ter cuidado para garantir a segurança da integração. Criar um usuário exclusivo para a integração, criar um grupo de usuários com as permissões necessárias e controlar o acesso dos IPs são medidas que devem ser tomadas para garantir a segurança do sistema do provedor e das informações dos usuários.