Opção de menu | Menu Configuração - Integrações |
Permissões de perfil | Menu Administrativo - Permissões:
|
Na tela de integração com a API é possível gerar, consultar, editar e organizar as chaves de API com segurança e melhor usabilidade.
Essa funcionalidade realiza integrações com parceiros ou sistemas externos que não possuem conexão direta com o EVO, viabilizando conexões personalizadas conforme a necessidade.
EVO API
Se você é cliente EVO Black, a possibilidade de API está incluída sendo possível realizar integrações com outros sistemas, com o apoio de um especialista. A disponibilidade e os limites variam conforme o plano de API contratado, que pode ser API Plus e API Pro.
Para saber sobre os planos consulte o artigo Planos - API EVO
O que é EVO API?
A EVO API permite que diferentes sistemas "conversem" entre si. API significa Interface de Programação de Aplicações. Ela funciona como um contrato entre os sistemas, dizendo como enviar e receber informações.
A EVO API segue o padrão REST, que utiliza funções como GET, PUT e DELETE para acessar ou modificar dados no servidor.
Uma característica importante é que ela não guarda dados entre uma solicitação e outra. Cada solicitação é como acessar um link de site: você faz o pedido, e o servidor devolve os dados sem uma interface gráfica.
Confira a Documentação para desenvolvedores para todas as informações sobre como usar a API.
Começar a usar a EVO API
Para começar, você precisa:
gerar uma chave de API para enviar solicitações.
usar uma ferramenta como Apidog ou Swagger para testar as solicitações.
Gerar chave de API
No EVO, você pode criar dois tipos de chaves:
Chave de unidade única: dá acesso apenas aos dados de uma unidade.
Chave multiunidade: permite acesso aos dados de várias unidades, usando o parâmetro
id-filial.
Vamos conhecer a tela e como criar a chave.
Conhecendo a tela
Em Configuração - Integrações, ao clicar no card EVO, é apresentada a tela em duas abas e as opções:
Aba Consumo: é possível consultar todas as requisições, por mês e por token.
Aba Tokens: consulta de todos os tokens cadastrados onde é possível ativar/inativar, editar e excluir.
Botão NOVO TOKEN: cria novos Tokens.
Histórico de alterações dos Tokens.
Como criar um Token
Clique em NOVO TOKEN.
É apresenta a janela de solicitação de login e senha do sistema EVO.
Clique em CONFIRMAR.
4. Na tela Novo Token preencha os campos de cada seção conforme indicado.
Geral
Nesta seção preencha o Nome do Token, o Nome do solicitante e o WhatsApp.
Os campos em asteriscos são obrigatórios
Utilização
Propósito de uso: informe a finalidade da integração selecionando as opções existentes.
Uso interno/Fornecedor parceiro: ao selecionar a opção Fornecedor/Parceiro informe o parceiro, o Nome do fornecedor, e-mail ou telefone.
Se o fornecedor não estiver na lista selecione a opção Outro.
Permissões
As permissões selecionadas devem estar relacionadas aos dados que a chave poderá acessar.
Cada uma dessas permissões estão ligadas com os endpoints e para verificar clique no expandir.
Após selecionar todas as opções clique em CRIAR TOKEN.
Importante
Todos os campos obrigatórios devem estar preenchidos.
É apresentado os termos de uso, para dar continuidade clique em ACEITAR.
É gerado o DNS e o Token.
Atenção
Todos os Tokens criados possuem validade de 2 anos a partir da data de criação.
Tokens criados pelo nosso suporte possuem expiração automática em 3 dias.
A proximidade da expiração será informada na barra de notificações com 30 dias de antecedência.
Também é possível consultar a validade do Token na coluna Data de expiração.
Consultando consumo de requisições
Na tela de Consumo é possível filtrar por mês e por Token cadastrado e será apresentado na grade de resultados:
Token: Token cadastrado
Requisições por período: quantidade de requisições do mês selecionado
Status atual do token que pode ser Ativo/Inativo.
A consulta é apresentada conforme o seu plano, veja a seguir.
EVO API Plus
Requisições
No card Requisições, são apresentadas as seguintes informações:
Consumo mensal, com o total utilizado e o limite por mês.
Consumo diário, com o total utilizado no dia e o limite diário.
Ao clicar em Limites de requisições, é possível visualizar a quantidade permitida conforme o plano.
Ao atingir o limite de requisições, é exibido no card a data de liberação para novas requisições.
Consumo por dia
Em consumo por dia é apresentado o card com as informações da quantidade de requisições por dia. Veja no exemplo abaixo, a linha horizontal representa os dias e a vertical a quantidade de requisições, ao passar o mouse pela linha é possível verificar a quantidade de requisições (hits) e qual o dia.
EVO API Pro
Nos cards serão apresentados os dados do mês selecionado.
Requisições
1- Total de requisições de todos os tokens cadastrados.
2- Valor diurno, valor noturno e valor total considerando todas as requisições e tokens.
3- Limite de requisições: permite verificar o total de requisições conforme o plano contratado. No exemplo apresentado, trata-se de um plano API Pro, no qual é possível utilizar o header para não haver limite diário.
EVO API Pro
Consumo por dia
Em consumo por dia é apresentado o card com as informações da quantidade de requisições por dia. Veja no exemplo abaixo, a linha horizontal representa os dias e a vertical a quantidade de requisições, ao passar o mouse pela linha é possível verificar a quantidade de requisições (hits) e qual o dia.
962 hits no dia 14
Alteração das chaves
Na aba Tokens é possível alterar o status do Token, editar e excluir, se for necessário.
Na chave desejada clique no ícone de editar.
É apresentada a tela com os dados para consulta do DNS e do Token.
É possível incluir ou excluir as permissões.
Clique em Salvar.
Para inativar ou ativar um Token selecione a chave Status.
Para excluir a chave, clique no ícone de lixeira, insira o login e a senha. Ao excluir as conexões que utilizam o Token este não poderá mais ser utilizado, confirme a ação.
As chaves/Tokens excluídos e alterados poderão ser consultados no ícone de relógio, na parte superior à direita da tela.
Testando a EVO API
A API do EVO usa autenticação básica. Para fazer chamadas, você precisa de:
Usuário: o DNS gerado no EVO.
Senha: a chave aleatória criada no último passo.
Você pode usar duas ferramentas para testar as chamadas da API:
Apidog: explore as áreas do sistema (entidades) e teste suas funções (endpoints).
Swagger: oferece as mesmas funcionalidades.
Como testar:
Informe seu usuário e senha.
Preencha os dados solicitados para cada função (endpoint).
As ferramentas oferecem um ambiente de teste seguro (sandbox), onde você pode ver os resultados das chamadas que fizer.
O que são as entidades da API?
Entidades são as áreas do sistema que você pode acessar ou modificar pela API. Alguns exemplos:
Activities: gerenciar aulas (criar, listar, matricular clientes).
BankAccounts: ver contas bancárias dos clientes.
Configuration: acessar configurações de unidade e meios de pagamento.
Employees: gerenciar colaboradores (adicionar, editar, excluir).
Invoices: buscar faturas por data.
Sales: gerenciar vendas (criar, listar, devolver itens).
Management: endpoints para obter clientes e oportunidades ativas e não renovadas.
MemberMembership: endpoints para obter resumos de contratos de clientes e realizar o cancelamento.
Members: endpoints para obter, atualizar e autenticar clientes.
Memberships: endpoints para obter contratos e suas categorias.
Notifications: endpoints para criar notificações.
Payables: endpoints para obter credores e centros de custo.
Prospects: endpoints para obter, adicionar e atualizar oportunidades.
Receivables: endpoints para obter e marcar contas a receber, além de obter centros de custo.
Sales: endpoints para obter, criar vendas e devolver itens de venda.
Service: endpoints para obter serviços.
Voucher: endpoints para obter vouchers.
Webhook: endpoints para criar, listar e remover webhooks.
Workout: endpoints para obter listas de treinos e associar treinos aos clientes.
Paginação da EVO API
A API do EVO retorna, por padrão, 50 registros por vez. Alguns endpoints permitem, excepcionalmente, até 100 registros.
Para ajustar a quantidade de registros retornados, use os parâmetros take e skip.
O cabeçalho da resposta sempre informa o número de registros retornados em relação ao total disponível.
Webhook
Na aba Webhook é possível enviar eventos do sistema automaticamente para ferramentas externas, como bots de IA, plataformas de automação, WhatsApp e Integrações via API.
Esta funcionalidade faz parte do plano API Pro.
Para configurar e entender todas as possibilidades dentro do sistema detalhadamente, consulte o artigo Configurar e enviar Webhook.