17. API de integração e chaves API

A API de integração serve para que o seu próprio programa, folha de cálculo ou script leia automaticamente os dados dos seus projetos: a lista de projetos, as listas de cabos e de materiais, a tabela de circuitos e a lista de bornes dos quadros, o mapa de quantidades e a composição do pacote de projeto. A API é só de leitura: não altera o desenho nem o projeto.

Quem pode obter uma chave de API

A chave de API é ativada pelo operador para cada conta. Se a sua conta recebeu a autorização, na página Perfil aparece o cartão Chaves de API; sem ela o cartão não é visível. Uma conta pode ter no máximo 5 chaves ativas em simultâneo.

A chave vê os mesmos projetos que você: os seus e, a pedido, os que foram partilhados consigo. As listas e o mapa de quantidades de um projeto partilhado só são devolvidos se a partilha permitir também a exportação.

Criar uma chave

1. No cartão Chaves de API da página Perfil, clique no botão Nova chave.
2. Dê um nome à chave (por exemplo, o nome do programa que a vai usar).
3. Escolha o âmbito: Ler projetos dá a lista de projetos e os respetivos dados, Ler documentos dá as listas, o mapa de quantidades e o pacote de projeto. Indique apenas o que o programa realmente precisa.
4. Escolha a validade: 30, 90 ou 365 dias. Uma chave expirada deixa de funcionar; em vez disso, cria uma nova.
5. Introduza a sua palavra-passe atual (numa conta sem palavra-passe é necessário um início de sessão recente). Na primeira chave, aceite as condições de utilização da API.

Depois de criada, a chave é mostrada uma única vez: copie-a e guarde-a num local seguro. Mais tarde, a lista mostra apenas o prefixo (avk_…), com as datas de criação e de validade, a última utilização e o número de chamadas. Enviamos também uma notificação por e-mail sobre a nova chave (sem a chave).

Revogar uma chave

Com o botão Revogar ao lado da chave no cartão, a chave fica imediatamente inutilizável; isto não pode ser desfeito. Revogue a chave quando já não a usar, quando descontinuar o programa que a usava ou se suspeitar que foi divulgada.

Conselhos de segurança

• Trate a chave como a sua palavra-passe: quem a conhecer pode ler os seus projetos dentro do âmbito indicado.
• Guarde-a num cofre de segredos (gestor de palavras-passe, variável de ambiente do servidor ou variável secreta da CI), não no código-fonte: não a envie para o repositório git, nem para uma folha de cálculo partilhada ou um e-mail.
• Não a use em código executado no navegador (página web, extensão do navegador): aí qualquer pessoa a pode ler. O lugar da chave é num servidor, num script ou num programa de computador.
• Cada programa deve ter a sua própria chave, com o âmbito mais restrito possível e uma validade curta; assim, revogar uma chave não pára mais nada.

Utilização a partir de um programa

No cabeçalho do pedido, a chave é enviada como token Bearer: Authorization: Bearer avk_…. Os endpoints estão em /api/v1/ (por exemplo GET /api/v1/projects) e respondem em JSON. A descrição completa em formato OpenAPI está disponível em /api/v1/openapi.json; a maioria das ferramentas de desenvolvimento consegue importá-la.

O número de chamadas é limitado por chave e por conta (por defeito 60 por minuto e 10 000 por dia); acima disso o servidor responde com 429, por isso aguarde um pouco. O início de sessão no site (cookie) não abre a API, e a chave não inicia sessão na interface web.