Começando a usar a EVO API

Definição

API significa Application Programming Interface (Interface de Programação de Aplicação). No contexto de APIs, a palavra Aplicação refere-se a qualquer software com uma função distinta. A interface pode ser pensada como um contrato de serviço entre duas aplicações. Esse contrato define como as duas se comunicam usando solicitações e respostas. A documentação de suas respectivas APIs contém informações sobre como os desenvolvedores devem estruturar essas solicitações e respostas, como esta API Reference.

A EVO API é uma API REST. REST significa Transferência Representacional de Estado. REST define um conjunto de funções como GET, PUT, DELETE e assim por diante, que podem ser usadas para acessar os dados do servidor. O solicitante e servidores trocam dados usando HTTP.

A principal característica da API REST é a ausência de estado. A ausência de estado significa que os servidores não salvam dados do cliente entre as solicitações. As solicitações ao servidor são semelhantes aos URLs que você digita no navegador para visitar um site. A resposta do servidor corresponde a dados simples, sem a renderização gráfica típica de uma página da Web.

Como usar a EVO API

Para começar a usar a EVO API, é necessário:

Obter uma chave de API para poder realizar solicitações.

Testar a API usando um cliente de API HTTP, onde você pode estruturar solicitações de API facilmente usando as chaves de API recebidas.

Vamos detalhar cada ambos esses pontos abaixo.

Obtendo as chaves da EVO API

Para obter as chaves necessárias para realizar solicitação de API, é necessário criá-las dentro do próprio EVO. É importante entender que há dois tipos de chaves de API possíveis de serem criadas:

Chave única de filial: chave criada na instância de uma filial com permissões e acesso somente a dados daquela filial;

Chave multifilial: chave criada em uma instância de ADM Geral com acesso somente a chamadas que possuem o parâmetro idbranch.

O caminho para a criação das chaves no EVO é Configurações - Integrações e acessar o card EVO na seção API:

Ao clicar no card EVO é apresentada a tela:

92e576e4fc02a2495bff23c9eacb8687ec2d47b430018d4ab29b9bb410f9ee62-image.png

1- Lista em ordem alfabética com todos os Tokens de integração criados.

2- Campo de pesquisa para buscar pelo nome do Token

3- NOVO TOKEN: botão para criar novos Tokens.

4- Ações: edita e exclui os Tokens criados.

5- Histórico de exclusão dos Tokens.

Criar um token

Clique em NOVO TOKEN.

7cd71a776f3bc29226e1ded9db13e04fd513f16e4c43e8033b0aec0af8d2892e-image.png

É apresenta a janela de solicitação de login e senha do sistema EVO

9763b4018a6f60017c3dc737f16bccab9af7e4e46ad7462a3f597f70ca4cfe99-image.png

Clique em CONFIRMAR.

Preencha o Nome do Token, o Nome do solicitante e o WhatsApp

59bae093b67bf72c44f513954d177c53136f3663260b22c6d9a88c4203debf9f-image.png

Preencha a 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 é necessário solicitar o cadastro neste formulário.

e872749cf3abca9f860e40895025e5fd31dba3a751c6e57874f9e8299400d312-image.png

Preencha as permissões

As permissões selecionadas devem estar relacionadas aos dados que a chave poderá acessar.

Cada uma dessas permissões estão ligadas aos endpoints e para verificar clique na seta para expandir.

3b4b17acffb047191c4ca8d071680c504406dec42288d239da0c28d7faa05e01-image.png

📘 Leia este artigo para entender a qual endpoint cada permissão se refere.

Ao selecionar todas as opções clique em CRIAR TOKEN.

Após criar o token, serão mostradas as chaves para usar na autenticação:

O seu DNS, que servirá como usuário;

E um token, que servirá como senha.

2eb66af3cf47c337a7e4c1f6b94eb26d25bcedf98dd26ca47a688c9a91ba481b-image.png

Editar e excluir token

Após a criação do token, você consegue editar as permissões ou excluir os tokens existentes. Basta clicar no ícone de "editar".

0eada00798d2b7a0d8c12f1f0fe3d13091e6860233b69df414f52ffb15cfdf8d-image.png

Testando a EVO API em um cliente de API HTTP

O método de autenticação da EVO API é o Basic Authentication, o que significa que para realizar chamadas de API, é necessário um usuário e senha: o DNS, como usuário, e a chave aleatória única criada no último passo, como senha.

Os clientes de API HTTP que dispomos que você possa testar chamadas de API são este, o Api Reference, onde você poderá navegar pelas diferentes entidades e seus endpoints, podendo testá-los. E também há o Swagger, onde você poderá fazer o mesmo em uma interface mais enxuta.

Para realizar os testes de chamadas bastará fornecer o usuário e senha e preencher os parâmetros delineados em cada endpoint. Tanto este canal quanto o Swagger dispõem desse ambiente sandbox onde você terá os retornos das suas chamadas-teste.

"Try it out"

Quais são as entidades da EVO API?

As entidades de API são as diversas áreas do produto às quais você pode realizar uma chamada de API. Eis um resumo das principais entidades da EVO API:

Activities: endpoints para obter aulas existentes, matricular aluno nelas, criar aulas teste, ver lista de aulas;

Configuration: endpoints para obter configurações de unidade, gateway, bandeiras de cartão, tradução de cartão, ocupação;

Employees: endpoints para obter, adicionar, atualizar e deletar colaboradores;

Entries: endpoints para obter entradas;

Invoices: endpoints para obter notas fiscais por data;

MemberMembership: endpoints para obter resumos de contratos de clientes;

Members: endpoints para obter, atualizar, autenticar clientes;

Memberships: endpoints para obter contratos e suas categorias;

Prospects: endpoints para obter, adicionar e atualizar oportunidades;

Receivables: endpoints para obter e marcar contas a receber, obter centro de custo;

Sales: endpoints para obter, criar vendas e retornar itens por 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 muitas outras!
Consulte a listagem completa das entidades na nossa API Reference.

Paginação da EVO API

O padrão de paginação para os retornos de chamadas da EVO API é de 50 registros. Há alguns endpoints que excepcionalmente permitem 100 registros no retorno.

Para regular a paginação do retorno de suas chamas, use os parâmetros takee skip.

O parâmetro total no **header ** indica a quantidade total de itens disponíveis para paginação na API.

Limitações de Requisições (Rate Limits)

Para garantir o desempenho e a estabilidade do sistema, a EVO API implementa limites de requisições (rate limits). Estes limites controlam o número de chamadas que podem ser realizadas dentro de intervalos de tempo específicos, com base nos seguintes critérios:

Por Minuto (por IP): Limite de 40 requisições por minuto. Após atingido, será retornado status 429 (Too Many Requests), e deve-se aguardar 1 minuto para novas chamadas.

Por Hora (por Chave de API): Limite de 10.000 requisições por hora. Caso ultrapassado, a chave será bloqueada por 1 hora.

Por Hora (por DNS): Limite de 20.000 requisições por hora para todas as chaves associadas ao mesmo DNS. Ao exceder, todas as chaves da academia ficam bloqueadas por 1 hora.

Nota: Durante o horário das 0h às 5h, os limites não são aplicados, permitindo execuções de alto volume, como requisições em lote.

Para mais informações e boas práticas sobre como evitar bloqueios, consulte a seção completa de Limites de requisições

Boas práticas de uso da EVO API

Por fim, aqui estão algumas boas práticas para o uso efetivo da EVO API.

Primeiro de tudo, é importante deixar claro que a EVO API foi pensada para ser usada em backend, pois a Basic Authentication requer as chaves de API para as solicitações.

🚧 Isso significa que usá-la em frontend pode expor métodos e dados da(s) sua(s) academia(s). Sempre implemente-a em backend.

Além disso, é essencial saber que a EVO API consome dados de produção, o que compete com os processos comuns do uso do EVO em si. Então recomenda-se puxar solicitações de API pesadas durante a madrugada da 01h às 06h, para evitar lentidão no uso do EVO por parte da(s) academia(s).

Começando a usar a EVO API

Definição#

Como usar a EVO API#

Obtendo as chaves da EVO API#

Criar um token#

Editar e excluir token#

Testando a EVO API em um cliente de API HTTP#

Quais são as entidades da EVO API?#

Paginação da EVO API#

Limitações de Requisições (Rate Limits)#

Boas práticas de uso da EVO API#