Criar uma chave API

As chaves API permitem que outro sistema comande o AssinaJá — o seu ERP a criar documentos, ou um assistente de IA a trabalhar pela interface MCP.

Chaves de acesso à API pública e ao MCP do AssinaJá. Crie uma por cada sistema externo ou assistente de IA, com os acessos limitados ao que essa integração precisa.

As chaves estão em Definições → Desenvolvedores → Chaves API, e só o Criador da organização as gere. A outro papel, o separador abre mas não mostra as chaves.

Uma chave por integração

Crie uma chave por cada sistema externo que integra com a API pública (cabeçalho X-Api-Key). Cada chave pode ser suspensa ou eliminada isoladamente, sem afetar as restantes integrações.

É essa a razão da regra: uma chave partilhada não pode ser revogada sem partir tudo o que a usa. Uma chave por sistema permite cortar uma integração e deixar as outras a funcionar.

Criar uma

Escolha Nova API Key.

1. Nome — dê-lhe o nome do sistema que a vai usar, por exemplo ERP Primavera.
2. Data de validade — “A chave é válida até esta data, inclusive (deixa de autenticar no fim desse dia).”
3. Acessos — marque apenas o que esta integração precisa. É obrigatório pelo menos um: “Selecione pelo menos um acesso — a chave só pode fazer o que estiver marcado.”
4. Criar chave.

A chave é mostrada uma única vez

Copie e guarde esta chave agora: é a única vez que é mostrada, e não fica guardada em lado nenhum. Se a perder, use «Rodar chave» para gerar outra com os mesmos acessos.

Não há forma de a recuperar depois. Ao lado de Copiar há Copiar como variável de ambiente, que copia ASSINAJA_API_KEY= seguido da chave, pronta a colar num ficheiro de configuração. O diálogo só fecha depois de marcar Guardei a chave em local seguro.

Acessos

Acesso	O que permite
Modelos — consultar	Listar e consultar modelos, incluindo signatários e campos de preenchimento.
Documentos — consultar	Listar documentos, acompanhar o progresso das assinaturas e descarregar ficheiros e relatórios.
Documentos — criar	Criar documentos a partir de modelos, de DOCX (MailMerge) ou de um PDF próprio.
Documentos — publicar	Publicar rascunhos — envia emails aos signatários e é irreversível.
Documentos — arquivar/eliminar	Arquivar e eliminar documentos.
Organização — consultar	Ver os dados da organização, o plano ativo e as funcionalidades disponíveis.
Analytics — consultar	Ler as métricas agregadas da organização: utilização, funil de assinatura e adoção. Nunca por pessoa. Só funciona se Definições → Políticas → Acesso de AI aos analytics também o permitir.
Catálogo de modelos	Só no plano Enterprise — ver abaixo.

Publicar é o perigoso

Documentos — publicar envia emails aos signatários e é irreversível. Criar e publicar são acessos deliberadamente separados, para que uma integração possa preparar rascunhos para uma pessoa rever, sem nunca os poder enviar. Conceda-o só quando o sistema deva mesmo enviar sozinho.

Para um assistente de IA, comece sem o acesso de publicar

Numa primeira ligação por MCP, marque Modelos — consultar, Documentos — consultar e Documentos — criar, e deixe Documentos — publicar de fora. O assistente prepara tudo e deixa o documento em rascunho; enviar continua a ser um ato seu, na aplicação. Depois de perceber como ele se porta, acrescente o acesso a publicar se quiser.

Analytics — consultar precisa também da política da organização — ver Acesso de IA às analytics.

O acesso ao catálogo de modelos

Catálogo de modelos — servir outras organizações é diferente dos restantes:

Permite que outras organizações gerem documentos a partir do catálogo de modelos desta organização (cabeçalho X-Api-Key-TemplateCatalog). Não dá nenhum outro acesso.

Usa o seu próprio cabeçalho e não concede mais nada. Está Disponível apenas no plano Enterprise.

Modelos pela API pública: duas regras

São regras da API pública, e valem para qualquer chave que consulte modelos:

• O plano que conta é o de quem serve o modelo, não o de quem chama. Se a organização dona do catálogo não tiver Modelos ativos, os cinco endpoints que consomem modelos respondem 423 FEATURE_TEMPLATES_NOT_ENABLED.
• Os rascunhos não existem para a API. Não aparecem na listagem, e pedir o detalhe de um dá 404. Publique o modelo antes de o integrar.

Gerir chaves

A lista mostra Nome, Chave, Acessos, Validade, Estado, Criada e Último uso — este último a dizer Nunca para uma chave que nunca autenticou. Essa coluna é a forma mais rápida de detetar uma chave que ninguém usa.

Ação	Efeito
Editar	Alterar o nome, a validade ou os acessos
Rodar chave	Gerar um segredo novo para a mesma integração — ver abaixo
Suspender	“Suspensa, a chave deixa de autenticar até ser reativada.”
Ativar	Reativar uma chave suspensa
Eliminar	Definitivo

O Estado de uma chave é Ativa, Suspensa ou Expirada.

Rodar uma chave

Quando perde uma chave, ou suspeita que foi exposta, não precisa de a eliminar e reconfigurar a integração do zero. Rodar chave abre Rodar a chave — “É gerada uma chave nova para esta integração. O nome, os acessos, a validade e os assistentes de IA ligados mantêm-se; só muda o segredo.” — e pergunta quando é que A chave atual deixa de funcionar:

Opção	Quando usar
Já — use isto se a chave pode ter sido exposta	“A integração que usa a chave atual deixa de conseguir autenticar no momento em que rodar.”
Daqui a 1 hora — tempo para trocar no sistema que a usa	A opção por omissão: as duas chaves funcionam durante uma hora.
Daqui a 24 horas	O mesmo, com um dia de folga.

A chave nova é mostrada uma única vez, como na criação — Chave rodada, com “A chave anterior continua a funcionar até {data}. Troque-a no sistema que a usa antes disso.” ou, se escolheu já, “A chave anterior deixou de funcionar.” Na lista, a chave passa a mostrar Rodada a {data} e, enquanto durar a sobreposição, “A anterior funciona até {data}”.

Uma chave Expirada não se roda — “Expirada: crie uma chave nova em vez de a rodar.”

Suspenda antes de eliminar

Suspender é reversível; eliminar não é — “é irreversível — a integração que a usa deixa imediatamente de conseguir autenticar.” Se suspeitar que uma chave está comprometida ou sem uso, suspenda-a e veja o que parte. Pode sempre reativar.

Ser avisado quando algo acontece

Para o seu sistema ser avisado quando algo acontece a um documento, em vez de andar a perguntar, veja Receber webhooks.

Ver também

• Receber webhooks
• Papéis e permissões — as chaves API e os webhooks são só do Criador; Integrações e Armazenamento, do Criador e do Administrador
• Configurar políticas da organização