API de Declaração de Conteúdo Eletrônica (DC-e)
API de emissão da DC-e, o documento fiscal de circulação de bens de quem não é contribuinte do ICMS.
A DC-e (Declaração de Conteúdo Eletrônica) é o documento de quem movimenta bens sem inscrição estadual — e por isso sem NF-e a emitir.
A DC-e não tem tributo
Não existe grupo de tributo nesta API: sem ICMS, sem IBS/CBS, sem alíquota, sem base de
cálculo e sem cálculo tributário. Quem chega da NF-e procurando onde informar imposto não vai
encontrar — e não é omissão da documentação, é o que o documento é. Os valores do item
(unitValue, totalValue) são valor de mercadoria, nada mais.
O caminho de integração
| Passo | Operação |
|---|---|
| Emitir | POST /v1/subscriptions/{subscriptionId}/taxpayers/{taxpayerId}/contentdeclarations |
| Emitir em lote | POST /v1/subscriptions/{subscriptionId}/taxpayers/{taxpayerId}/contentdeclarations/$batch |
| Acompanhar | GET /v1/subscriptions/{subscriptionId}/taxpayers/{taxpayerId}/contentdeclarations/{id} |
| Auditar o histórico | GET /v1/subscriptions/{subscriptionId}/taxpayers/{taxpayerId}/contentdeclarations/{id}/events |
| Baixar a DACE (PDF) | GET /v1/subscriptions/{subscriptionId}/taxpayers/{taxpayerId}/contentdeclarations/{id}/pdf |
| Baixar o XML autorizado | GET /v1/subscriptions/{subscriptionId}/taxpayers/{taxpayerId}/contentdeclarations/{id}/xml |
| Cancelar | DELETE /v1/subscriptions/{subscriptionId}/taxpayers/{taxpayerId}/contentdeclarations/{id} |
| Consultar a SEFAZ | GET /v1/subscriptions/{subscriptionId}/taxpayers/{taxpayerId}/sefaz/dce-status |
Autenticação: token Bearer
A DC-e se integra com Authorization: Bearer <token>, um token JWT emitido pelo provedor de
identidade da NFE.io (https://idx.nfe.io/realms/nfeio), a partir de uma credencial da assinatura. Esse
é o meio de autenticação suportado nesta API — as bibliotecas oficiais (Node.js, PHP, Ruby) não
atendem a DC-e.
Como obter e renovar o token: veja Autenticação da DC-e.
A assinatura vai na URL
Toda rota carrega a assinatura e o contribuinte emitente, nesta ordem:
/v1/subscriptions/{subscriptionId}/taxpayers/{taxpayerId}/contentdeclarations…, em minúsculas.
O subscriptionId é a única fonte do escopo de dados — é ele que diz de quem são os
documentos; o taxpayerId diz qual contribuinte emite. Aceita o identificador com ou sem o
prefixo sub_. Nenhum cabeçalho de assinatura é lido, em rota nenhuma.
Contribuinte inexistente, ou de outra assinatura, responde 404 com type
https://docs.nfe.io/errors/dce/company-not-in-subscription — em todas as rotas, de leitura e
de escrita, antes de qualquer coisa do pedido ser lida.
⚠️ taxpayers na URL, companyId na listagem — e os dois estão certos. O recurso público
é o contribuinte; dentro da plataforma o mesmo identificador se chama empresa. Por isso o campo
companyId que a listagem devolve carrega exatamente o valor que você pôs em
{taxpayerId}.
Acesso ao produto
Emitir exige o produto DC-e contratado na assinatura. Sem ele, POST e $batch respondem
403 com type …/product-not-contracted — contrate o produto com o comercial da nfe.io.
Consultar, baixar e cancelar documentos já emitidos não dependem da contratação.
O ambiente vem do cadastro da empresa
O host é sempre https://api.nfe.io, para produção e para homologação. Quem decide o ambiente
do documento é o cadastro da empresa na plataforma, não o host nem a assinatura.
O corpo da emissão leva environment: 1 produção, 2 homologação. Ausente, 0 ou fora
desses dois valores, a resposta é 400. O valor tem de coincidir com o ambiente cadastrado da
empresa — divergente, a resposta é 422 com a regra B10-10 e os dois valores. Para homologar,
use uma empresa cadastrada em homologação e envie environment: 2, no mesmo host. Em
homologação, a DACE sai com a tarja "EMITIDO EM HOMOLOGAÇÃO — SEM VALOR FISCAL" e o
documento não tem validade fiscal.
Erros no formato Problem Details
Toda resposta de erro é application/problem+json (RFC 9457), com type estável no espaço
https://docs.nfe.io/errors/dce/… — é o discriminador para o seu código; title e detail
são texto para pessoas. Recusa sobre campos da requisição (400, 422) traz ainda
errors[], com name (o caminho do campo, em camelCase), reason (a explicação) e rule (o
identificador da regra, quando há).
As mensagens são em inglês, com uma exceção: o xMotivo da SEFAZ (em
rejectionReason, cancellationReason e nos eventos) é repassado em português, como veio.
400 ou 422: forma ou regra
| Código | Quando |
|---|---|
400 | a requisição não tem a forma do contrato: JSON ilegível, tipo errado, valor fora do conjunto aceito, cabeçalho ou parâmetro de consulta fora do formato, ou ausência de um campo que a API exige antes de qualquer regra — emitterType, environment, ao menos um item, a reason do cancelamento |
422 | a requisição se lê, e uma regra recusa o conteúdo: dígito verificador, ambiente divergente do cadastro (B10-10) e as regras da DC-e |
Toda recusa que traz rule é 422.
Tolere valores de enum que você não conhece
Os campos de estado (status, flowStatus) e os tipos de evento podem ganhar valores novos
sem aviso. Trate valor desconhecido como "estado que não conheço ainda" e não falhe: um
consumidor que estoura em enum novo deixa de ler o documento inteiro por causa de um campo.
Authentication
- HTTP: Bearer Auth
Token JWT emitido pelo provedor de identidade da nfe.io, enviado em
Authorization: Bearer <token>. É o meio de autenticação suportado na DC-e.
| Emissor | https://idx.nfe.io/realms/nfeio |
| Audiência e escopos | já vêm configurados na credencial; não é preciso pedir escopo |
Como obter e renovar o token: veja Autenticação da DC-e.
O acesso ao produto não vem de escopo do token: emitir depende da contratação da DC-e
(403 com …/product-not-contracted), e o alcance dos dados é a assinatura da URL.
Assinatura e empresa: as duas vão na URL
O isolamento dos documentos é pela assinatura do caminho ({subscriptionId}) — não pelo
taxpayerId. As duas coisas são dimensões distintas: a assinatura diz de quem são os
documentos, e o taxpayerId diz qual contribuinte emite. Nenhum cabeçalho de assinatura
é lido.
- Token de assinatura (
client_credentials): o{subscriptionId}da URL tem de ser a assinatura do próprio token — outra, a resposta é403. - Token de usuário (login no console): o
{subscriptionId}tem de ser uma assinatura a que o usuário tem acesso — outra, a resposta é403.
O 403 de assinatura vem com type https://docs.nfe.io/errors/dce/subscription-scope-undetermined,
qualquer que seja o detail. O contribuinte ({taxpayerId}) que não pertence à assinatura
responde 404, com type …/company-not-in-subscription.
Security Scheme Type: | http |
|---|---|
HTTP Authorization Scheme: | bearer |
Bearer format: | JWT |