Pular para o conteúdo

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. Crie uma por cada sistema externo ou assistente de IA, com os acessos limitados ao que essa integração precisa.

Definições → Desenvolvedores tem os separadores Geral, Chaves API, Webhooks, Integrações e Armazenamento — os dois últimos só para o Criador e o Administrador. Geral abre primeiro, com os endereços da API pública e do Servidor MCP e a ligação Abrir documentação da API.

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

O separador Definições → Desenvolvedores → Chaves API, ainda sem chaves, com o
botão Nova API Key.

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.

Escolha Nova API Key.

  1. Nome — dê-lhe o nome do sistema que a vai usar, por exemplo ERP Primavera. Se quiser, junte uma Descrição.
  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.

O diálogo Nova API Key, com o nome, a data de validade e a lista de acessos ainda por marcar.

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 — ligações de assinatura Obter as ligações de assinatura dos signatários pendentes. Quem tiver a ligação assina em nome do signatário — é uma credencial, não uma consulta.
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.
Webhooks — segredo de assinatura Ler e rodar o segredo com que assinamos os webhooks que enviamos, para o sistema de destino poder validar o cabeçalho X-AssinaJa-Signature. Conceder só a quem integra webhooks: com este segredo é possível assinar eventos.
Catálogo de modelos Só no plano Enterprise — ver abaixo.

Documentos — consultar não dá as ligações de assinatura: essas têm o seu próprio acesso, Documentos — ligações de assinatura, porque quem tem uma ligação assina pelo signatário. Conceda-o só a uma integração que precise mesmo de entregar as ligações.

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

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.

Uma chave com este acesso é partilhada com outras organizações, por isso não pode ter também nenhum acesso Documentos: a plataforma recusa guardá-la assim. Para o catálogo, use uma chave à parte.

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.

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.

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.”

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