Autenticação
A API usa Bearer Token no header Authorization em todas as chamadas.
Authorization: Bearer nt_test_xxxxxxxxxxxxxxxxxxxxxxxxxx
Ambientes
A chave carrega o ambiente embutido — você nunca envia ambiente no body.
| Prefixo | Ambiente | Notas geradas |
|---|---|---|
nt_test_ | Homologação | Sem valor fiscal — pra teste de integração |
nt_live_ | Produção | Documento fiscal válido |
A mesma URL base (https://api.notare.nexosos.com) atende os dois ambientes — a chave decide.
Gerar uma chave
- Login em app.notare.nexosos.com
- Empresas → selecione a empresa emitente
- API keys → Gerar nova
- Escolha ambiente + nome descritivo (ex:
erp-sap-prod) - Copie e guarde — a chave só é exibida 1 vez
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 → Empresas → API keys → ⋯ → Revogar.
Chamadas em curso podem terminar (até 30s). Novas chamadas falham com 401 imediatamente.