Começando a usar a EVO API

Entenda os conceitos básicos de API, como utilizá-la e quais as integrações possíveis com o EVO

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:

1. Obter uma chave de API para poder realizar solicitações.
2. Testar a API usando um cliente de API HTTP, onde você pode estruturar solicitações de API facilmente usando as chaves de API recebidas. Fornecemos tanto este aqui, ReadMe, quanto o Swagger para isso.

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, um modal lateral abrirá pedindo que você nomeie a chave e escolha as permissões dela. As permissões são relacionadas aos endpoints de cada entidade da EVO API.

📘

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

Clique em Criar Token para salvar a chave:

🚧

Uma vez criada a chave, ela não é editável, sendo necessário criar outra caso queira ter permissões distintas.

Tendo clicado em Criar Token, seu usuário e senha do EVO serão pedidos para confirmação e então serão mostradas as chaves para usar na autenticação, que serão sempre:

• O seu DNS, que servirá como usuário;
• E uma chave aleatória que deve ser salva no ato da criação, que servirá como senha.

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 ReadMe, 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.

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

Sandbox da nossa API Reference aqui no ReadMe

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 entidades da EVO API:

• Activities: endpoints para obter aulas existentes, matricular aluno nelas, criar aulas teste, ver lista de aulas;
• BankAccounts: endpoints para obter contas bancárias de alunos;
• 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;
• Management: endpoints para obter clientes ativos e não renovados, e oportunidades;
• MemberMembership: endpoints para obter resumos de contratos de clientes, além de cancelá-los;
• Members: endpoints para obter, atualizar, autenticar clientes;
• Memberships: endpoints para obter contratos e suas categorias;
• Notifications: endpoints para inserir notificações
• Payables: endpoints para obter contas a pagar e centro de custos;
• 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, ligar treino a cliente.

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).