Autenticação¶

Toda chamada à API exige uma API key no header X-Api-Key.

curl https://api.aceitou.com.br/api/v1/templates \
  -H "X-Api-Key: ak_live_xxxxxxxxxxxxxxxx"

Como obter sua chave¶

A chave é gerada pelo admin do tenant Aceitou do seu cliente, no portal dele:

Portal → Integrações → Aplicativos integrados
Nova integração — preenche nome do sistema integrador (o seu) + escopos
A chave (ak_live_...) aparece uma única vez na criação
Cliente Aceitou entrega a chave pra você por canal seguro (1Password ou similar)

Nunca exponha sua chave

A chave é equivalente à credencial completa de uma conta. Nunca commit em repo, nunca client-side (browser/mobile/desktop). Use exclusivamente em backend.

Escopos¶

Sua chave tem um conjunto de escopos definido na criação. Os comuns:

Escopo	Permite
`documents:read`	Listar e ler documentos
`documents:write`	Criar, enviar, cancelar documentos
`templates:read`	Listar e ler templates
`templates:write`	Criar, atualizar, excluir templates
`webhooks:manage`	Cadastrar/remover webhooks
`signers:manage`	Gerenciar signatários
`reports:read`	Acessar relatórios

Chamadas sem o escopo necessário retornam 403 Forbidden:

{
  "title": "Forbidden",
  "status": 403,
  "detail": "A chave de API não possui o escopo 'documents:write' necessário.",
  "requiredScope": "documents:write"
}

Se você precisar de mais escopos, peça ao seu cliente pra editar a integração ou criar uma chave nova com escopos maiores.

Rotação¶

Se suspeitar de vazamento, peça ao cliente pra rotacionar a chave no portal dele. A antiga deixa de funcionar imediatamente e você recebe a nova.

Operacionalmente: o ideal é que a rotação seja agendada (a cada 90/180 dias) e coordenada com você, pra não derrubar produção.

Diferença entre API Key direta e integração¶

	API Key direta (interna do tenant)	Integração / Aplicativo integrado
Quem usa	Scripts internos do próprio tenant	Sistema de terceiro (você)
Como tenant rastreia	Só nome e escopos	Nome do integrador, logo, contato técnico, log de uso
LGPD subprocessor	Não consta	Consta na lista exportável de subprocessadores
Cada chamada gera log de acesso	Não	Sim (timestamp, path, IP)

Como integrador externo, sua credencial sempre vem via "Aplicativos integrados" — nunca via "API Keys" direta do tenant.

Privacidade e LGPD (o que o tenant vê)¶

Toda chamada que você faz à API com a chave de integração é registrada do lado do tenant Aceitou (timestamp, método HTTP, path, resource_id quando aplicável, status code, IP de origem e User-Agent). Esses logs:

Você não acessa. São do tenant — o admin Aceitou dele consulta no portal e pode exportar pra DPO. Nada que você precise fazer.
Servem pra compliance LGPD. O tenant precisa saber "quem acessou os dados do titular X" pra responder direitos do titular (art. 18) e manter trilha de auditoria de subprocessadores (art. 37).
Retenção 90 dias. Worker periódico expira logs antigos.

Boas práticas do seu lado:

Inclua um User-Agent identificável em todo HTTP client. Facilita pro tenant saber qual versão do seu app fez aquela chamada.
Não faça scraping ou poll agressivo — webhook é melhor que polling, e logs gordos só ajudam a denunciar abuso seu.
Se uma chamada falhar 401/403, NÃO retry agressivo. Pode ser revoke ou rotate em curso; respeite e contate o tenant fora-de-banda.