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.
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:1- Lista em ordem alfabética com todos os Tokens de integração criados.2- Campo de pesquisa para buscar pelo nome do Token3- 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.
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"
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;
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.
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
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).
