17. API de integração e chaves de API

A API de integração serve para que o seu próprio programa, planilha 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 de distribuição, o levantamento de quantidades e a composição do pacote de desenhos. A API só lê: ela não altera o desenho nem o projeto.

Quem pode obter uma chave de API

A chave de API é liberada pelo operador, conta por conta. Se a sua conta recebeu a permissão, o cartão Chaves de API aparece na página Perfil; sem ela, o cartão não é exibido. Uma conta pode ter no máximo 5 chaves ativas ao mesmo tempo.

A chave enxerga os mesmos projetos que você: os seus e, sob solicitação, os que foram compartilhados com você. As listas e o levantamento de um projeto compartilhado só são fornecidos se o compartilhamento também permitir 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 vai usá-la).
3. Escolha o escopo: Ler projetos fornece a lista de projetos e os dados dos projetos, Ler documentos fornece as listas, o levantamento e o pacote de desenhos. Indique apenas o que o programa realmente precisa.
4. Escolha a validade: 30, 90 ou 365 dias. Uma chave vencida deixa de funcionar; você cria uma nova no lugar dela.
5. Informe a sua senha atual (em uma conta sem senha, é necessário um login recente). Na primeira chave, aceite os termos de uso da API.

Depois de criada, a chave é exibida uma única vez: copie-a e guarde-a em local seguro. Depois, a lista mostra apenas o prefixo (avk_…), com as datas de criação e de vencimento, o último uso e o número de chamadas. Também enviamos uma notificação por e-mail sobre a nova chave (sem a chave em si).

Revogar uma chave

Com o botão Revogar ao lado da chave no cartão, a chave se torna imediatamente inutilizável; isso não pode ser desfeito. Revogue a chave quando não a usar mais, quando desativar o programa que a usava ou quando suspeitar de vazamento.

Dicas de segurança

• Trate a chave como a sua senha: quem a conhece pode ler os seus projetos dentro do escopo indicado.
• Guarde-a em um cofre de segredos (gerenciador de senhas, variável de ambiente do servidor ou variável secreta do CI), não no código-fonte: não a envie para o repositório git, nem para uma planilha compartilhada ou um e-mail.
• Não a use em código executado no navegador (página web, extensão do navegador): lá qualquer pessoa pode lê-la. O lugar da chave é em um servidor, em um script ou em um programa de desktop.
• Dê a cada programa a sua própria chave, com o escopo mais restrito possível e validade curta; assim, revogar uma chave não interrompe nenhum outro programa.

Uso a partir de um programa

No cabeçalho da requisição, a chave é enviada como token Bearer: Authorization: Bearer avk_…. Os endpoints ficam em /api/v1/ (por exemplo, GET /api/v1/projects) e a resposta é JSON. A descrição completa em formato OpenAPI está 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 padrão, 60 por minuto e 10.000 por dia); ao exceder, o servidor responde com 429, então aguarde um pouco. O login no site (cookie) não abre a API, e uma chave não faz login na interface web.