Ligar as suas ferramentas com a API
A API permite que uma aplicação externa acceda aos dados da sua Organização de forma programática: efectivos, calendários, Reservas e facturação. Activa-se em dois cliques e protege-se com uma chave, uma lista de endereços autorizados e um acompanhamento do consumo.
Saber se a API se aplica ao seu caso
A API destina-se a um desenvolvedor, não a um responsável de Organização. Serve para fazer dialogar a sua conta com um software que manda escrever ou configurar: um site web personalizado, uma ferramenta de contabilidade, um ecrã de afixação feito em casa, uma ligação a outro sistema.
Para as necessidades correntes — obter a lista de Membros, actualizar Subscrições em massa, transmitir números à direcção — os módulos de importação, de exportação e de relatórios respondem sem escrever uma linha de código.
A API é proposta em versão beta: o seu funcionamento pode ainda evoluir.
Activar a API e obter a sua chave
- Vá a Administração›Configurações›API BETA.
- Active Ativar o módulo API e depois clique em Salvar.
- A sua Chave API é apresentada: copie-a com o botão Copiar e transmita-a apenas à ferramenta que está a ligar.
A chave transmite-se no cabeçalho HTTP X-API-Key de cada pedido. As chamadas fazem-se obrigatoriamente em HTTPS; nenhum pedido não cifrado é aceite.
Proteger a chave
Alguns reflexos merecem ser recordados à ferramenta ou ao prestador que a utiliza:
- nunca colocar a chave num repositório de código; guardá-la num ficheiro de configuração fora do repositório ou num gestor de segredos;
- restringir os endereços autorizados assim que a ferramenta faça chamadas a partir de um servidor fixo;
- regenerar a chave à menor dúvida — publicação acidental, fuga de registos, fim de missão de um prestador.
O botão Regenerar pede confirmação e invalida imediatamente a chave anterior. Todas as aplicações que a utilizavam deixam de funcionar enquanto não receberem a nova: avise-as antes de clicar.
Restringir o acesso por endereço IP
Active a Restrição por endereço IP: só os pedidos provenientes dos endereços que indicar são aceites, até ao limite de 10 endereços IPv4. Introduza cada endereço e valide com Adicionar; o seu endereço actual é apresentado no ecrã para o ajudar.
É a protecção mais eficaz e a mais frequentemente esquecida: mesmo divulgada, uma chave restringida ao endereço do seu prestador permanece inutilizável noutro local.
Acompanhar o consumo
O ecrã apresenta em permanência o que a sua chave consome:
- Uso neste minuto e Utilização hoje, cada uma comparada com o seu limite quando um limite está configurado;
- Estatísticas de utilização: Esta semana, Este mês, Total e Última solicitação.
Além dos limites indicados, os pedidos suplementares são temporariamente recusados. Um contador que roça permanentemente o seu tecto indica geralmente uma ferramenta mal regulada, que volta a pedir os mesmos dados em ciclo em vez de os guardar em cache.
A data do último pedido é útil no sentido inverso: uma chave activada mas nunca chamada há meses é uma chave a desactivar.
Descobrir o que a API permite
A documentação completa, com os parâmetros e exemplos de chamada, é apresentada na parte inferior do ecrã do módulo. Em linhas gerais:
- Utilizadores: é o único recurso modificável. Pode listar, consultar, criar, alterar e eliminar contas.
- Configuração: Subscrições, perfis, grupos e categorias de idade podem ser consultados, mas configuram-se unicamente a partir da aplicação.
- Reserva: calendários, Períodos disponíveis, Reservas e Etiquetas podem ser consultados.
- Facturação: Contas de facturação, Encomendas e pagamentos podem ser consultados.
