Chave de API: integrar outro sistema com o seu estúdio
O que é
Seção intitulada “O que é”A chave de API permite que outro sistema (um ERP, uma folha de cálculo automática, um site ou uma aplicação sua) consulte e registe dados do seu estúdio sem que ninguém tenha de introduzir nada. Cada chave funciona como um utilizador do estúdio: só pode fazer aquilo que esse utilizador pode fazer.
Quando usar
Seção intitulada “Quando usar”- Um sistema de gestão precisa de consultar as vendas do dia para a contabilidade.
- Um site ou uma aplicação próprios precisam de registar clientes ou consultar o catálogo.
- Uma automatização precisa de registar despesas ou consultar contas a receber.
Antes de começar
Seção intitulada “Antes de começar”Só quem administra o estúdio (com acesso total ou permissão para editar Perfis e Utilizadores) pode criar, editar e revogar chaves. Se não conseguir criar uma chave, peça ao proprietário do estúdio para lhe dar acesso em Acessos → Perfis.
Recomendamos que crie primeiro um utilizador apenas para a integração, com um perfil que dê acesso apenas aos ecrãs de que o outro sistema precisa. A chave herda as permissões desse utilizador.
Passo a passo
Seção intitulada “Passo a passo”Passo 1 — Abrir o separador API Key
Seção intitulada “Passo 1 — Abrir o separador API Key”Em Configurações → Empresa, abra o separador API Key. Aí encontra a lista das chaves já criadas, com o utilizador associado a cada uma, os IPs permitidos, a Validade e o Último uso.
Passo 2 — Criar a chave
Seção intitulada “Passo 2 — Criar a chave”Clique em Nova chave, preencha o Nome e escolha o Utilizador. Em IPs permitidos, introduza um IP ou um intervalo por linha para aceitar apenas chamadas desses endereços (se deixar o campo vazio, são aceites todos os IPs). Em Validade, escolha Nunca expira ou Expira em e indique uma data: a chave é válida até ao fim desse dia. Clique em Criar chave e copie a chave através do botão de cópia. Não será apresentada novamente.
O outro sistema envia a chave em todas as chamadas, no cabeçalho Authorization, desta forma:
Authorization: Bearer hk_... (substitua hk_... pela chave completa).
Para usar a chave com uma IA (Claude Code, Gemini CLI, Cursor), marque também Permitir utilização como conector de IA em Conector de IA. Sem esta opção, a chave funciona nas integrações, mas não no conector. Consulte o artigo Conector de IA.
Passo 3 — Revogar uma chave
Seção intitulada “Passo 3 — Revogar uma chave”Na lista, clique no ícone do lixo da chave e confirme em Revogar. O sistema que usava a chave perde o acesso em até 30 segundos. Para alterar o nome, os IPs ou a validade, use o ícone do lápis.
O que acontece depois
Seção intitulada “O que acontece depois”- Tudo o que o outro sistema alterar com a chave aparece na Auditoria com a origem Chave de API, em nome do utilizador associado à chave.
- A chave deixa de funcionar automaticamente quando a validade termina ou quando o utilizador associado é desativado no estúdio. Na lista, aparece como Expirada ou Utilizador inativo.
- Uma chave nunca dá acesso a outra empresa, mesmo que o utilizador associado também trabalhe noutra.
Erros comuns e dúvidas
Seção intitulada “Erros comuns e dúvidas”P: A chave pode fazer tudo no sistema? R: Não. Tem as permissões do utilizador associado e só neste estúdio. Algumas áreas nunca aceitam chaves, mesmo que sejam de um utilizador com acesso total: início de sessão e mudança de empresa, o próprio ecrã das chaves, a gestão de utilizadores e convites, a Heya, o suporte, os painéis, as definições gerais da Empresa (logótipo, horários, feriados, domínio e e-mail dos relatórios) e os ecrãs da plataforma. Se tiver várias integrações, crie um utilizador para cada uma: na Auditoria, a alteração aparece em nome do utilizador associado à chave.
P: Perdi a chave. Posso voltar a vê-la? R: Não. O sistema guarda apenas uma impressão da chave, nunca a chave propriamente dita. Revogue a antiga e crie outra.
P: O outro sistema recebe “Este IP não está autorizado a usar esta chave de API.” O que faço? R: O IP de onde o sistema faz a chamada não está em IPs permitidos. Edite a chave e adicione o IP ou deixe a lista vazia para aceitar todos os IPs.
P: O outro sistema recebe “Esta rota não pode ser usada com chave de API.” Porquê? R: Está a chamar uma das áreas que não aceitam chaves (consulte a primeira pergunta). Estas operações têm de ser realizadas por uma pessoa, no ecrã.
P: Posso alterar o utilizador associado a uma chave? R: Não. Revogue a chave e crie outra com o novo utilizador.
P: A lista de utilizadores para a nova chave está vazia. Porquê? R: Os utilizadores da equipa da plataforma não podem ter chaves de API e não aparecem na lista. Registe um utilizador do próprio estúdio (de preferência, apenas para a integração) e crie uma chave para ele.