Autenticação
A API usa chaves de API por empresa. Toda requisição autenticada envia a
chave no header Authorization, no esquema Bearer:
Authorization: Bearer ck_live_xxxxxxxxxxxxxxxxxxxxxxxxGerando uma chave
- No painel, acesse Chaves de API no menu lateral.
- Clique em Nova chave, dê um nome e selecione os escopos.
- Copie o segredo na hora — ele é exibido uma única vez. Guardamos apenas um hash (Argon2id + pepper, o mesmo esquema das senhas); não é possível recuperar a chave depois.
Formato da chave
ck_<ambiente>_<lookupId>_<secret>ambiente:liveoutest(rótulo lógico).lookupId: identificador público que localiza a chave.secret: a parte secreta, verificada via hash.
Escopos
Restringem o que a chave pode fazer. Uma chave sem escopos tem acesso total dentro da empresa — com uma exceção, o financeiro (abaixo).
| Escopo | Permite |
|---|---|
documents:read | Ler documentos fiscais, baixar XML/DANFE e consultar inutilizações |
documents:write | Emitir / cancelar documentos e inutilizar numeração |
companies:read | Ler dados da empresa |
webhooks:read | Listar endpoints de webhook e entregas |
webhooks:write | Criar / alterar / remover endpoints de webhook |
tax-rules:read | Listar / detalhar regras tributárias |
tax-rules:write | Criar / alterar / remover regras tributárias |
clients:read | Listar / detalhar clientes |
clients:write | Criar / alterar / remover clientes |
carriers:read | Listar / detalhar transportadoras e a frota de cada uma |
carriers:write | Criar / alterar / remover transportadoras e veículos da frota |
products:read | Listar / detalhar produtos, com a tributação própria de cada um |
products:write | Criar / alterar / remover produtos, incluindo a tributação própria (CST/CSOSN, ICMS-ST, crédito do Simples, PIS/COFINS/IPI) e o CEST |
templates:read | Listar / detalhar templates fiscais |
templates:write | Criar / alterar / remover templates fiscais da empresa |
finance:read | Ler contas a pagar / receber, aging, inadimplentes e projeção de caixa |
finance:write | Lançar contas, dar baixa e estornar |
O financeiro é opt-in explícito
finance:read e finance:write não são concedidos pela regra do “sem
escopos = acesso total”. A chave precisa carregá-los literalmente, e só um
administrador da empresa pode criar uma chave com eles.
São duas razões independentes:
- toda chave criada antes de o módulo existir foi emitida por alguém que nunca viu a tela de Contas a pagar/receber — conceder retroativamente daria à chave um poder que ninguém escolheu dar;
- dentro do app, o Financeiro é restrito aos administradores. Sem esta exceção, qualquer membro criaria uma chave irrestrita e leria pela API o que a tela lhe nega.
Vale também para o MCP por OAuth: os escopos de financeiro só entram no token quando quem autorizou é administrador da empresa escolhida.
Além do escopo, a empresa precisa ter o módulo Financeiro contratado — sem
ele os endpoints respondem 403 feature_not_enabled (nunca uma lista vazia).
Boas práticas
- Use uma chave por integração — facilita revogar sem afetar as demais.
- Conceda somente os escopos necessários.
- Revogue chaves comprometidas imediatamente (a revogação é instantânea).
- Nunca exponha a chave no front-end; mantenha-a apenas no servidor.
Erros de autenticação
| Status | code | Significado |
|---|---|---|
401 | missing_api_key | Header Authorization ausente |
401 | invalid_api_key | Chave inválida, revogada ou expirada |
403 | insufficient_scope | A chave não tem o escopo exigido |