Autenticação e ambientes da Captura Fiscal
A API de recepção automática aceita dois métodos de autenticação e separa o ambiente da plataforma do ambiente da SEFAZ.
API Key
O método mais comum. Envie a sua chave no header Authorization:
GET /v2/companies/{companyId}/inbound/nfse HTTP/1.1
Host: api.nfse.io
Authorization: ApiKey SUA_API_KEY
BearerQualquer prefixo antes de um espaço é aceito e descartado (ApiKey , Token , ou nenhum) — a chave em si é o que importa. A única exceção é Bearer : esse prefixo é tratado como um token de plataforma, não como API Key, e a autenticação falha.
A chave pode ser enviada de três formas equivalentes:
| Forma | Exemplo |
|---|---|
Header Authorization | Authorization: ApiKey SUA_API_KEY |
Header X-NFEIO-APIKEY | X-NFEIO-APIKEY: SUA_API_KEY |
Query string api_key | ?api_key=SUA_API_KEY |
A API Key é gerenciada no painel da empresa (em Chaves de API).
Cada endpoint de recepção é protegido por uma policy (NFeDist, CTeDist ou NFSeDist, conforme o documento), e cada policy aceita dois papéis de API Key:
| Policy do endpoint | Papéis de API Key aceitos |
|---|---|
NFeDist | Nota Fiscal (api.nfe.io) ou NFeDist (dfe.nfe.io) |
CTeDist | Nota Fiscal (api.nfe.io) ou CTeDist (dfe.nfe.io) |
NFSeDist | Nota Fiscal (api.nfe.io) ou NFSeDist (dfe.nfe.io) |
Ou seja: uma API Key com o papel geral Nota Fiscal (api.nfe.io) — que a maioria das chaves já possui — autentica os três produtos de recepção. Os papéis específicos (NFeDist/CTeDist/NFSeDist (dfe.nfe.io)) existem para chaves restritas a um único produto (princípio do menor privilégio).
Os endpoints de recepção (NF-e, CT-e, NFS-e) são protegidos exclusivamente pelo esquema de API Key (confirmado no código — os controllers usam ApiKeyDefaults.AuthenticationScheme). Um token Bearer de plataforma não autentica esses endpoints (retorna 401).
Papéis (roles)
Os endpoints de manutenção administrativa da NFS-e (fetch-now, notifications, statistics, reactivate) exigem o papel Management — chamadas sem ele retornam 403.
Ambientes
Há duas noções de ambiente que não devem ser confundidas:
| Noção | O que controla | Como é definido |
|---|---|---|
| Ambiente da plataforma | Produção × Homologação da NFE.io | Mesmo host api.nfse.io; selecionado pela API Key |
| Ambiente da SEFAZ | Validade fiscal dos documentos capturados | Campo environmentSEFAZ na ativação |
O campo environmentSEFAZ
Na ativação da captura, environmentSEFAZ indica o ambiente da SEFAZ:
{
"startFromDate": "2026-06-01T00:00:00Z",
"environmentSEFAZ": "Production"
}
- Valores aceitos:
"Production"(produção, validade fiscal real) e"Test"(homologação, sem validade fiscal). - Internamente mapeiam para
1 = Produçãoe2 = Homologação. - Quando omitido, o padrão é
Test(homologação).