Autenticação

A API usa Bearer Token no header Authorization em todas as chamadas.

Authorization: Bearer nnt_test_xxxxxxxxxxxxxxxxxxxxxxxxxx

Ambientes

A chave carrega o ambiente embutido — você nunca envia ambiente no body. A mesma URL base (https://api.notare.nexosos.com) atende os dois — a chave decide.

Prefixo	Ambiente	O que acontece
nnt_test_	Sandbox	Valida o request com as regras reais e devolve um retorno simulado. Não gera nota.
nnt_live_	Produção	Emite a NFS-e de verdade — documento fiscal válido.

Veja a página Sandbox para entender exatamente o que é simulado e o que é validado de verdade.

Modelo de chave: única por conta principal

A API key é emitida pela conta principal (cadastro mestre) e vale para todas as empresas vinculadas ao tenant. Você não gera uma chave por CNPJ — gera uma chave por integração, e o cnpjEmitente no body é que decide qual empresa emite a NFS-e.

• Quem pode emitir / revogar: apenas usuários com role owner ou admin da conta principal.
• Quem é cobrado: o uso de todas as empresas é faturado na conta principal.
• Validação no servidor: se o cnpjEmitente não pertence ao tenant da chave, a Notare responde 403 Forbidden antes de qualquer chamada à prefeitura.

Esse modelo é equivalente ao de provedores como Stripe e Plugnotas: a chave representa o tenant, não uma empresa específica. Multi-CNPJ não exige multi-chave.

Gerar uma chave

1. Login em app.notare.nexosos.com com a conta principal (role owner ou admin)
2. API Keys no menu lateral (item visível apenas pra owner/admin)
3. Nova API key → escolha ambiente + nome descritivo (ex: erp-sap-prod)
4. Copie e guarde — o plaintext só é exibido 1 vez (a Notare armazena apenas hash bcrypt)

Boas práticas

• Uma chave por integração — se você tem 3 ERPs falando com a Notare, gere 3 chaves
• Nunca commit no repo — use cofre de segredos (Vault, AWS Secrets Manager, GCP Secret Manager)
• Rotação a cada 90 dias — gere nova, atualize no ERP, revogue a antiga
• Escopo mínimo — em planos Enterprise dá pra restringir por permissão (nfse:emit, nfse:read)

Rate limits

Plano	Requests/min	Concurrency
Starter	60	5
Growth	300	20
Scale	1.500	100
Enterprise	Negociado	Negociado

Quando estourar: HTTP 429 com header Retry-After em segundos.

Erros de auth

Status	Quando	Como resolver
401 Unauthorized	Header ausente, mal formatado, ou chave revogada	Verificar prefixo Bearer e regenerar se necessário
403 Forbidden	Chave válida mas sem permissão pra essa operação	Verificar escopo da chave (plano Enterprise)
429 Too Many Requests	Rate limit estourado	Respeitar Retry-After, considerar upgrade de plano

Revogar uma chave

Portal → API Keys → ícone de revogar na linha da chave.

Chamadas em curso podem terminar (até 30s). Novas chamadas falham com 401 imediatamente. Como a chave é tenant-wide, revogar interrompe a integração de todas as empresas que a usam — emita a substituta primeiro, atualize os clientes, depois revogue a antiga.