Pular para o conteúdo principal
Version: v1

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​

PassoOperação
EmitirPOST /v1/subscriptions/{subscriptionId}/taxpayers/{taxpayerId}/contentdeclarations
Emitir em lotePOST /v1/subscriptions/{subscriptionId}/taxpayers/{taxpayerId}/contentdeclarations/$batch
AcompanharGET /v1/subscriptions/{subscriptionId}/taxpayers/{taxpayerId}/contentdeclarations/{id}
Auditar o históricoGET /v1/subscriptions/{subscriptionId}/taxpayers/{taxpayerId}/contentdeclarations/{id}/events
Baixar a DACE (PDF)GET /v1/subscriptions/{subscriptionId}/taxpayers/{taxpayerId}/contentdeclarations/{id}/pdf
Baixar o XML autorizadoGET /v1/subscriptions/{subscriptionId}/taxpayers/{taxpayerId}/contentdeclarations/{id}/xml
CancelarDELETE /v1/subscriptions/{subscriptionId}/taxpayers/{taxpayerId}/contentdeclarations/{id}
Consultar a SEFAZGET /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ódigoQuando
400a 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
422a 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​

Token JWT emitido pelo provedor de identidade da nfe.io, enviado em Authorization: Bearer <token>. É o meio de autenticação suportado na DC-e.

Emissorhttps://idx.nfe.io/realms/nfeio
Audiência e escoposjá 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

Contact

nfe.io:

URL: https://nfe.io

NFE.io

A NFE.io é uma empresa de tecnologia que fornece soluções para automatizar e simplificar a emissão e gestão de notas fiscais eletrônicas. Com suas ferramentas, as empresas podem economizar tempo e reduzir erros, aumentando a eficiência e precisão do processo de emissão de notas fiscais.

Um dos principais cases de sucesso da NFE.io é a implementação da solução na empresa de transporte Rodonaves. Com a automatização da emissão e gestão de notas fiscais eletrônicas, a Rodonaves conseguiu reduzir em até 80% o tempo gasto nesse processo, o que se traduziu em uma significativa melhoria na eficiência operacional. Além disso, a empresa também conseguiu eliminar erros e atrasos na emissão de notas fiscais, o que melhorou a relação com seus clientes e aumentou a confiança dos órgãos fiscais.

Outro exemplo é a implementação da NFE.io na empresa de comércio eletrônico, a Loja Integrada. Com a automatização da emissão de notas fiscais, a Loja Integrada conseguiu aumentar a velocidade de emissão de notas em até 10 vezes, o que permitiu que a empresa atendesse a uma maior quantidade de clientes e, consequentemente, aumentar as suas vendas.

Além desses exemplos, a NFE.io também tem outros cases de sucesso com empresas de setores como indústria, construção, varejo e serviços, mostrando a versatilidade e eficácia da sua solução.

Em resumo, a NFE.io é uma empresa de tecnologia que oferece soluções para automatizar e simplificar a emissão e gestão de notas fiscais eletrônicas, ajudando as empresas a economizar tempo e reduzir erros, melhorando a eficiência e precisão do processo. Com cases de sucesso em diferentes setores, a NFE.io tem se destacado como uma empresa líder em automação fiscal.