Autenticação da DC-e
As outras APIs da NFE.io autenticam com Authorization: <chave-de-api>. A DC-e não aceita esse formato — responde 401. É por isso que as bibliotecas oficiais (Node.js, PHP, Ruby), que autenticam por chave de API, ainda não atendem a DC-e.
A DC-e é o primeiro produto da NFE.io a autenticar por token JWT com escopos e papéis — um modelo diferente do padrão de chave de API usado no restante da plataforma. Veja Chaves de autenticação para o modelo usado nas demais APIs.
O token
Envie Authorization: Bearer <token>. O token precisa ter a audiência (aud) dfetech.contentdeclaration.api.
| Escopos que autorizam leitura | contentdeclaration:read, api.all.read, api.all.read-write |
| Escopos que autorizam emissão e cancelamento | contentdeclaration:write, api.all.read-write |
| Papéis aceitos (token de usuário, login no console) | dce:read para leitura, dce:issue para emissão |
api.all.read não autoriza emissãoEscopo de leitura não vira permissão de emitir documento fiscal — mesmo sendo um escopo "amplo" (api.all.*), ele só cobre a operação que o nome diz.
Assinatura, empresa e o cabeçalho X-Subscription-Id
O isolamento dos documentos é pela assinatura contida no token — não pelo companyId da rota. São duas dimensões distintas: a assinatura diz de quem são os documentos; o companyId diz qual empresa emite (a empresa cujo certificado assina o documento).
| Tipo de token | Como a assinatura é definida |
|---|---|
Token de assinatura (client_credentials) | A assinatura vem do próprio token. Se você enviar X-Subscription-Id, ele tem que coincidir com a assinatura do token — divergente, a resposta é 403 |
| Token de usuário (login no console) | O token não carrega assinatura. Informe X-Subscription-Id com a assinatura escolhida — sem ele, ou com uma assinatura que não é daquele usuário, a resposta é 403 |
O cabeçalho aceita o valor com ou sem o prefixo sub_ (ambos são aceitos e equivalentes).