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_xxxxxxxxxxxxxxxxxxxxxxxx

Gerando uma chave

1. No painel, acesse Chaves de API no menu lateral.
2. Clique em Nova chave, dê um nome e selecione os escopos.
3. 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: live ou test (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 duas exceções, o financeiro e as notas recebidas (abaixo).

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

As notas recebidas também são opt-in explícito

received-documents:read e received-documents:write seguem a mesma regra do financeiro: a chave precisa carregá-los literalmente. O motivo é o mesmo — toda chave emitida antes deste recurso existir ganharia o acesso sem ninguém o ter escolhido — e há um segundo, só do :write: ele manifesta a nota perante a SEFAZ, em nome da empresa. Manifestação é ato jurídico e não tem desfazer.

Quem cria a chave precisa ter, no app, a permissão correspondente: ver notas recebidas para o :read, manifestar notas recebidas para o :write.

Chave do escritório (modo contador)

Escritórios de contabilidade que usam o Painel do Contador têm um segundo tipo de chave, criado em Painel do Contador → Configurações → Chaves de API do escritório. Ela começa com ok_ (a da empresa começa com ck_) e só entra nas rotas /v1/accounting — uma não serve no lugar da outra.

• Escopos sempre explícitos — não existe “sem escopos = acesso total”.
• Só o responsável ou um administrador do escritório cria e revoga (com 2FA).
• A chave alcança só as empresas com vínculo ativo. A empresa que encerra o vínculo sai do alcance na hora (403 company_not_in_portfolio), e escritório suspenso recebe 403 accounting_mode_inactive em tudo.
• Emitir exige a permissão da empresa, além do escopo: ela liga “Permitir que o escritório emita notas pela integração” em Configurações → Contador. Sem isso, criar, emitir, cancelar e corrigir respondem 403 office_issuing_not_allowed (ler continua liberado). O campo officeIssuingAllowed da carteira diz quem permitiu.

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