Chaves API

As chaves API abrem o acesso programático ao dAio Business. Permitem que as suas próprias aplicações, scripts e sistemas consultem diretamente a plataforma — dados meteorológicos, qualidade do ar, pólen, condições marítimas, inteligência setorial — sem passar pela interface web. É o ponto de entrada para industrializar as suas integrações: alimentar um ERP, despoletar um processamento de negócio, exibir previsões no seu próprio painel.

Cada chave autentica as chamadas em nome da sua organização e herda os respetivos direitos. Combinada com os webhooks, oferece-lhe um canal completo: você consulta o dAio a pedido através da API, e o dAio notifica-o em tempo real através dos webhooks.

Dica: crie uma chave distinta por utilização (um serviço, um ambiente, um parceiro). Poderá revogar uma sem interromper as restantes e rastrear com precisão qual a integração que consome o quê.

Para que serve uma chave API

Necessidade	A chave API permite…
Integração	Ligar o dAio ao seu SI (ERP, GMAO, BI) sem intervenção humana.
Automatização	Iniciar processamentos agendados (recolha diária de previsões, scoring de risco).
Difusão	Exibir dados do dAio nas suas próprias aplicações ou portais.
Partilha controlada	Dar a um parceiro um acesso limitado e revogável, sem criar uma conta de utilizador.

Informação: o acesso à API está reservado aos planos pagos. Uma organização sem subscrição ativa recebe uma resposta 403 (« API access requires a paid plan ») em cada chamada.

Criar uma chave

A criação de uma chave está reservada ao proprietário (owner) e aos administradores (admin) da organização. Os restantes perfis não podem criar nem revogar chaves.

1. Aceda a Definições > Chaves API.
2. Clique em Nova chave no canto superior direito.
3. Introduza um nome descritivo que identifique a utilização da chave (ex.: « Backend produção », « Conector Power BI », « Integração parceiro X »).
4. Clique em Criar.
5. A chave completa é apresentada num banner verde: copie-a imediatamente através do botão de cópia.

Atenção: a chave completa é apresentada apenas uma vez, no momento da sua criação. Nunca é apresentada novamente depois disso — a plataforma conserva apenas uma impressão cifrada. Se a perder, terá de gerar uma nova. Armazene-a sem demora num gestor de segredos (Vault, AWS Secrets Manager, variáveis de ambiente cifradas).

Uma vez criada, a chave aparece na lista com o seu nome, o seu prefixo (os primeiros carateres, para a identificar sem a revelar), um indicador de estado (verde = ativa, vermelho = revogada) e a sua data da última utilização.

Utilizar uma chave

Todos os pedidos para a API dAio devem incluir a sua chave no cabeçalho HTTP X-API-Key. A base da API é https://api-dev.daio.app, e os pontos de acesso B2B têm o prefixo /api/v1/.

curl -H "X-API-Key: VOTRE_CLE_API" \
  "https://api-dev.daio.app/api/v1/weather/current?lat=48.8566&lon=2.3522"

Atenção: o cabeçalho esperado é mesmo X-API-Key, e não Authorization: Bearer. Uma chave inválida, revogada ou transmitida noutro cabeçalho devolve uma resposta 401 (« Invalid API key »).

Consulte a documentação técnica da API para a lista completa dos pontos de acesso (meteorologia, previsões horárias, qualidade do ar, pólen, marinha, processamento em lote) e o formato das respostas.

Limites de taxa

Para garantir a estabilidade do serviço, cada chave está sujeita a um limite de taxa horário. O contador é próprio de cada chave e reinicia-se a cada hora.

Plano	Pedidos por hora
Gratuito / sem subscrição	Sem acesso à API
Solo · Team · Enterprise (dAio Business)	20 000

Quando o limite é atingido, a API devolve uma resposta 429 (« Rate limit exceeded ») acompanhada de um cabeçalho Retry-After que indica o prazo antes de tentar novamente.

Informação: este limite horário é distinto da quota mensal de pedidos incluída na sua fórmula. Consulte o detalhe das quotas por plano na secção Subscrição.

Fazer uma rotação de chave

A rotação regenera uma chave mantendo o seu nome e a sua localização na lista. Utilize-a para renovar periodicamente os seus segredos sem reconfigurar toda a sua integração.

1. Na lista, clique no ícone de rotação (seta circular) em frente à chave.
2. Confirme a operação.
3. O novo valor é apresentado apenas uma vez — copie-o imediatamente.
4. Atualize as suas aplicações com este novo valor.

Dica: agende uma rotação a cada 90 dias, e sistematicamente após a saída de um colaborador que tenha tido acesso aos segredos ou em caso de suspeita de fuga.

Revogar uma chave

Para cortar o acesso de uma chave comprometida ou não utilizada:

1. Na lista, clique no ícone de eliminação (caixote do lixo) em frente à chave.
2. Confirme a revogação.

A revogação é imediata e irreversível. Qualquer pedido que utilize a chave revogada receberá de imediato uma resposta 401. A chave permanece visível na lista, marcada como Revogada, a título de histórico.

Segurança das chaves

Uma chave API equivale a uma palavra-passe: quem a detém pode consultar a API com os direitos da sua organização.

Atenção: nunca faça commit de uma chave no seu código-fonte ou num repositório Git, mesmo privado. Uma chave enviada por engano para um repositório é considerada comprometida — revogue-a e faça-lhe uma rotação sem demora. Nunca a transmita por e-mail, mensagem ou ticket de suporte em texto simples.

• Armazene as chaves num gestor de segredos ou em variáveis de ambiente, nunca diretamente no código.
• Não as exponha do lado do cliente (aplicação web, móvel, JavaScript no navegador): uma chamada à API deve partir do seu servidor.
• Compartimente: uma chave por ambiente (produção, teste) e por utilização.
• Vigie a data da última utilização: uma chave inativa há muito tempo é uma chave a revogar.

Boas práticas

• Nomeie explicitamente cada chave de acordo com a sua utilização e o seu ambiente, para identificar de relance o que ela alimenta.
• Aplique o menor privilégio: crie chaves dedicadas e revogáveis em vez de uma chave única partilhada por todas as suas integrações.
• Automatize a rotação a cada 90 dias e integre-a nos seus procedimentos de saída de colaborador.
• Faça a gestão dos 429 do lado do cliente: respeite o cabeçalho Retry-After e suavize as suas chamadas em vez de encadear pedidos.
• Revogue imediatamente qualquer chave que suspeite estar comprometida — a revogação produz efeito sem demora.
• Documente internamente qual a chave que serve para quê e quem é responsável por ela, para auditorias de segurança tranquilas.

Dica: associe as suas chaves API aos webhooks para uma integração completa — consulte o dAio a pedido e deixe o dAio notificá-lo dos eventos em tempo real.