Coleção Postman da DC-e

A DC-e ainda não tem SDK — as bibliotecas oficiais autenticam por chave de API, e a DC-e exige token JWT. A coleção do Postman é o substituto prático: você importa um arquivo e tem as oito operações prontas, com os cabeçalhos que ninguém adivinha lendo só a URL.

Baixar a coleção (nfe-io-dce.postman_collection.json)

A referência manda

A coleção é espelho da referência de API — as mesmas rotas, as mesmas operações, os mesmos corpos de exemplo. Se algo divergir, a referência está certa e a coleção tem um defeito a corrigir.

O que vem dentro

Oito requisições, em quatro grupos, na ordem do fluxo de integração:

Grupo	Requisição	Método
1 · Emitir	Emitir uma DC-e	POST …/contentdeclarations
	Emitir em lote ($batch)	POST …/contentdeclarations/$batch
2 · Acompanhar	Consultar uma DC-e	GET …/contentdeclarations/{id}
	Listar DC-e (OData)	GET …/contentdeclarations
	Histórico de eventos	GET …/contentdeclarations/{id}/events
3 · Baixar	Baixar a DACE (PDF)	GET …/contentdeclarations/{id}/pdf
	Baixar o XML autorizado	GET …/contentdeclarations/{id}/xml
4 · Cancelar	Cancelar uma DC-e	DELETE …/contentdeclarations/{id}

Cada requisição traz, na própria descrição dentro do Postman, o que a resposta significa e o link para a página correspondente aqui.

Importar

O arquivo é uma coleção no schema v2.1.0, importável por qualquer versão recente do Postman.

1. Baixe o arquivo pelo link acima.
2. No Postman, clique em Import, no canto superior esquerdo.
3. Arraste o .json para a janela, ou use files e selecione-o.
4. A coleção aparece na barra lateral como NFE.io - DC-e (Declaracao de Conteudo Eletronica).

Não há arquivo de environment a importar: as variáveis vivem na própria coleção, na aba Variables. É um arquivo só, e um passo a menos onde errar.

Preencher as variáveis

Abra a coleção, vá à aba Variables e preencha a coluna Current value:

Variável	O que é	Padrão
baseUrl	O host da API	https://api.nfe.io — já preenchido
subscriptionId	A assinatura sobre a qual você opera. Aceita com ou sem o prefixo sub_	vazio
taxpayerId	O contribuinte emitente: a empresa cujo certificado assina o documento	vazio
token	O JWT, sem a palavra Bearer — a coleção já a acrescenta. Não tem como obtê-lo? Veja abaixo	vazio
environment	2 homologação, 1 produção	2
documentId	O documento a consultar, baixar ou cancelar	preenchido sozinho — veja abaixo

Onde conseguir o token

A coleção não traz uma requisição que gere o token, porque obtê-lo depende de uma credencial provisionada para a sua conta — e esse provisionamento ainda é feito caso a caso. Fale com o suporte para receber a sua. O que o token precisa ter depois de emitido — audiência, escopos e papéis — está em Autenticação.

A chave de API da plataforma não funciona aqui

As outras APIs da NFE.io autenticam com Authorization: <chave-de-api>. A DC-e exige Authorization: Bearer <token JWT> com a audiência dfetech.contentdeclaration.api, e responde 401 para a chave de API. Veja Autenticação.

environment vem em 2 de propósito

Homologação é o padrão seguro. Em produção, uma emissão é transação fiscal real e queima numeração — trocar para 1 é uma decisão, não um ajuste. O valor também tem de coincidir com o ambiente cadastrado da empresa; divergente, a resposta é 400 com a regra B10-10.

Homologar pela internet não é possível hoje

O endereço de homologação da DC-e é interno e só resolve dentro da rede da NFE.io. Para homologar sua integração, fale com o suporte — é a mesma orientação da página de Autenticação.

O roteiro, na ordem em que a coleção está

1. Emitir. Dispare Emitir uma DC-e. Sem o cabeçalho Prefer, a resposta é 200 com o documento já em estado terminal. A aba Tests dessa requisição lê o id da resposta — do corpo ou do cabeçalho Location — e guarda em {{documentId}}. É o que faz o resto da coleção funcionar sem você copiar e colar identificador.

2. Acompanhar. Consultar uma DC-e devolve o documento completo. Histórico de eventos responde por que ele está nesse estado, o que importa quando o estado é Rejected ou Refused. Listar DC-e é a visão de várias, com $filter, $orderby, $top, $skip, $count e $select.

3. Baixar. DACE (PDF) é a representação impressa; XML autorizado é o documento fiscal. Os dois respondem 302 para uma URL temporária.

4. Cancelar. Justificativa de 15 a 255 caracteres, e a resposta é 204.

As armadilhas que a coleção já conhece

Estão escritas dentro de cada requisição, e vale saber antes de disparar a primeira:

• 202 é resultado possível sempre. Se a autorização não chegar a estado terminal dentro do tempo de espera do servidor, o modo síncrono degrada para 202 com Location — mesmo sem você ter pedido o modo assíncrono.
• O lote não oferece repetição segura, e recusa o Idempotency-Key em vez de ignorá-lo. Reenviar o mesmo $batch emite os documentos de novo. Para ter garantia contra duplicidade, emita item por item pela requisição unitária, cada um com o seu Idempotency-Key.
• 204 no cancelamento significa "pedido aceito", não "cancelada". O desfecho vem depois, pela SEFAZ. Confirme por GET {id} (status: Cancelled) ou pelo histórico de eventos.
• A URL do PDF e a do XML expiram em 5 minutos. Baixe na hora; não guarde nem repasse o link. Se preferir JSON ao redirecionamento, acrescente ?format=uri.
• Os campos da listagem são uma lista fechada de dezesseis nomes, e a comparação é exata — createdAt funciona, createdat responde 400.
• Idempotency-Key usa {{$guid}}, que gera uma chave nova a cada disparo. Para exercitar a repetição segura, troque por um valor fixo.

Os dados dos exemplos são fictícios

Os CNPJ, CPF, nomes e endereços dos corpos de exemplo são os mesmos publicados na referência de API — exemplos, não empresas. Troque-os pelos seus antes de emitir.

Veja também

• Autenticação — o token, os escopos e a assinatura na URL
• Emitir uma DC-e pela API
• Como consultar uma DC-e pela API
• DACE e XML da DC-e
• Cancelamento de DC-e
• Referência de API da DC-e