Autenticação e limites
API keys
A autenticação usa uma chave de API por empresa (tenant), enviada em todas as requisições no
header X-Api-Key:
X-Api-Key: enfe_a1b2c3d4_9f8e7d6c5b4a3210...
- Formato:
enfe_<prefixo>_<segredo>. - A chave é exibida uma única vez, na criação — guarde-a em um cofre de segredos. O Notavia armazena apenas o hash (irrecuperável).
- Pode haver várias chaves ativas (ex.: uma por sistema), e revogar uma não afeta as outras.
Gerando a chave (passo a passo)
Só usuários com papel Admin geram e revogam chaves.
- No portal, abra o espaço Administração e clique no bloco Integração (API).
- Em "Chaves de API", clique em Nova chave.
- Dê um nome que identifique o sistema que vai usá-la (ex.:
ERP-producao,loja-virtual) — o nome aparece na listagem e na auditoria. - A chave completa (
enfe_..._...) é exibida somente neste momento. Copie e guarde em um cofre de segredos; depois de fechar, não há como vê-la de novo (só o hash fica no banco). - Perdeu ou suspeita de vazamento? Revogue a chave na mesma tela (efeito imediato) e crie outra. Criação e revogação ficam registradas na auditoria da conta.
A listagem mostra o prefixo de cada chave (os 8 caracteres após enfe_) e o último uso —
é assim que você identifica qual chave é qual sem precisar do segredo.
A chave identifica a empresa: todos os recursos acessados (notas, cadastros, jobs) são automaticamente os daquela empresa — não há como acessar dados de terceiros.
curl -H "X-Api-Key: $NOTAVIA_KEY" https://SEU-DOMINIO/api/integracao/produtos
Respostas de autenticação
| HTTP | Significado |
|---|---|
401 Unauthorized |
Header ausente, chave malformada, inexistente ou revogada |
403 Forbidden |
Chave válida, mas sem acesso ao recurso |
Rate limit
O limite acompanha o plano da conta:
| Plano | Limite |
|---|---|
| Free | 20 requisições/minuto |
| Essencial, Profissional, Negócios, Escala | 100 requisições/minuto |
A janela é fixa (60 s), particionada por chave de API. Estourou:
HTTP/1.1 429 Too Many Requests
Retry-After: 37
Trate 429 com espera pelo valor de Retry-After (ou backoff exponencial). Para alto volume,
prefira webhooks a polling agressivo — polling de jobs conta no limite.
O rate limit (requisições/minuto) é por chave, compartilhado entre NF-e e DC-e. Já a cota de emissão é separada por documento: a DC-e tem franquia própria (Free 5/dia; pagos = franquia da NF-e + 15%) e não consome a cota de NF-e. Veja Planos e assinatura.
Boas práticas
- Use uma chave por sistema integrado; revogue na hora se houver suspeita de vazamento.
- Nunca exponha a chave em front-end, apps móveis ou repositórios — ela deve viver só no seu backend.
- Toda criação/revogação de chave fica registrada na auditoria da conta.