{ "info": { "name": "NFE.io - DC-e (Declaracao de Conteudo Eletronica)", "description": "As oito operacoes da API da DC-e, na ordem do fluxo de integracao: emitir, acompanhar, baixar, cancelar.\n\nEsta colecao e **espelho da referencia publicada** em https://nfe.io/docs/desenvolvedores/rest-api/declaracao-de-conteudo-v1 - mesmas rotas, mesmas operacoes, mesmos corpos de exemplo. Se algo aqui divergir da referencia, a referencia esta certa.\n\n## Antes de disparar qualquer coisa\n\nPreencha as variaveis da colecao, na aba **Variables**:\n\n| Variavel | O que e |\n|---|---|\n| `baseUrl` | `https://api.nfe.io` - ja preenchido |\n| `subscriptionId` | a assinatura sobre a qual voce opera. Aceita com ou sem o prefixo `sub_` |\n| `taxpayerId` | o contribuinte emitente: a empresa cujo certificado assina o documento |\n| `token` | o JWT, sem a palavra `Bearer`. Audiencia `dfetech.contentdeclaration.api` |\n| `environment` | `2` homologacao (padrao), `1` producao. Tem de bater com o ambiente cadastrado da empresa |\n| `documentId` | preenchido sozinho pela requisicao de emissao |\n\n> **A DC-e nao aceita a chave de API da plataforma.** As outras APIs da NFE.io autenticam com `Authorization: `; aqui e `Authorization: Bearer `, e a chave de API responde `401`.\n\n> **`environment` vem em `2` de proposito.** Homologacao e o padrao seguro: em producao a emissao e transacao fiscal real e queima numeracao.\n\n> **Onde conseguir o token:** esta colecao nao traz uma requisicao que o gere, porque obte-lo depende de uma credencial provisionada para a sua conta. Fale com o suporte para receber a sua.\n\nDocumentacao: https://nfe.io/docs/docs/documentacao/declaracao-de-conteudo-eletronica/conceitos", "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json" }, "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "item": [ { "name": "1 - Emitir", "description": "A emissao unitaria e a emissao em lote. Comece pela unitaria: ela preenche o `{{documentId}}` que o resto da colecao usa.", "item": [ { "name": "Emitir uma DC-e", "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "// Guarda o id da DC-e emitida em {{documentId}}, para as requisicoes seguintes.", "// O id chega no corpo (200) ou no cabecalho Location (202) - os dois sao possiveis.", "let id = null;", "try { id = pm.response.json().id; } catch (e) { /* 202 costuma vir sem corpo */ }", "if (!id) {", " const loc = pm.response.headers.get('Location');", " if (loc) { id = loc.split('?')[0].split('/').filter(Boolean).pop(); }", "}", "if (id) {", " pm.collectionVariables.set('documentId', id);", " console.log('documentId =', id);", "} else {", " console.log('Nenhum id na resposta - confira o status e o corpo.');", "}" ] } } ], "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Idempotency-Key", "value": "{{$guid}}", "description": "Repeticao segura. Troque por um valor fixo para exercitar o replay." }, { "key": "Prefer", "value": "respond-async", "description": "Ligue para receber 202 + Location em vez de esperar o desfecho.", "disabled": true } ], "body": { "mode": "raw", "raw": "{\n \"emitterType\": \"SelfIssuer\",\n \"emissionType\": \"Normal\",\n \"environment\": {{environment}},\n \"issuer\": {\n \"cnpj\": \"11222333000181\",\n \"name\": \"EMPRESA EXEMPLO LTDA - MATRIZ\",\n \"address\": {\n \"street\": \"Rua Exemplo\",\n \"number\": \"1000\",\n \"neighborhood\": \"Centro\",\n \"cityCode\": 3550308,\n \"cityName\": \"Sao Paulo\",\n \"state\": \"SP\",\n \"postalCode\": \"01001000\"\n }\n },\n \"recipient\": {\n \"cnpj\": \"99887766000105\",\n \"name\": \"EMPRESA EXEMPLO LTDA - FILIAL\",\n \"address\": {\n \"street\": \"Avenida Exemplo\",\n \"number\": \"250\",\n \"neighborhood\": \"Jardim Exemplo\",\n \"cityCode\": 3304557,\n \"cityName\": \"Rio de Janeiro\",\n \"state\": \"RJ\",\n \"postalCode\": \"20010000\"\n },\n \"email\": \"contato@exemplo.com.br\"\n },\n \"items\": [\n {\n \"itemNumber\": 1,\n \"description\": \"EQUIPAMENTO DE EXEMPLO\",\n \"ncm\": \"84713012\",\n \"quantity\": 2,\n \"unitValue\": 1500.00,\n \"totalValue\": 3000.00\n }\n ],\n \"transport\": {\n \"mode\": \"Carrier\",\n \"carrierCnpj\": \"12345678000195\"\n }\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{baseUrl}}/v1/subscriptions/{{subscriptionId}}/taxpayers/{{taxpayerId}}/contentdeclarations" }, "description": "Emite uma DC-e. O servico faz numeracao, assinatura com o certificado da empresa, validacao de schema e transmissao a SEFAZ em uma chamada.\n\n**Sem o cabecalho `Prefer`** a resposta e `200` com o documento em estado terminal. **Com `Prefer: respond-async`** (desabilitado aqui - ligue no painel de cabecalhos) a resposta e `202` com o `id` e o cabecalho `Location`.\n\n> `202` e resultado possivel **sempre**: se a autorizacao nao chegar a estado terminal dentro do tempo de espera do servidor, o modo sincrono degrada para `202`.\n\n`serie` e `number` sao atribuidos pelo servidor - nao os envie.\n\n`Idempotency-Key` faz um reenvio nao emitir um segundo documento. Aqui ele usa `{{$guid}}`, que gera uma chave nova a cada disparo; troque por um valor fixo (o numero do pedido no seu sistema) para exercitar a repeticao.\n\nA aba **Tests** guarda o `id` da resposta em `{{documentId}}`, para as requisicoes seguintes.\n\nPagina: /docs/documentacao/declaracao-de-conteudo-eletronica/integracao-api/emitir-uma-declaracao-de-conteudo" }, "response": [] }, { "name": "Emitir em lote ($batch)", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "[\n {\n \"emitterType\": \"SelfIssuer\",\n \"emissionType\": \"Normal\",\n \"environment\": {{environment}},\n \"issuer\": {\n \"cnpj\": \"11222333000181\",\n \"name\": \"EMPRESA EXEMPLO LTDA - MATRIZ\",\n \"address\": {\n \"street\": \"Rua Exemplo\",\n \"number\": \"1000\",\n \"neighborhood\": \"Centro\",\n \"cityCode\": 3550308,\n \"cityName\": \"Sao Paulo\",\n \"state\": \"SP\",\n \"postalCode\": \"01001000\"\n }\n },\n \"recipient\": {\n \"cnpj\": \"99887766000105\",\n \"name\": \"EMPRESA EXEMPLO LTDA - FILIAL\",\n \"address\": {\n \"street\": \"Avenida Exemplo\",\n \"number\": \"250\",\n \"neighborhood\": \"Jardim Exemplo\",\n \"cityCode\": 3304557,\n \"cityName\": \"Rio de Janeiro\",\n \"state\": \"RJ\",\n \"postalCode\": \"20010000\"\n }\n },\n \"items\": [\n {\n \"itemNumber\": 1,\n \"description\": \"EQUIPAMENTO DE EXEMPLO\",\n \"ncm\": \"84713012\",\n \"quantity\": 1,\n \"unitValue\": 1500.00,\n \"totalValue\": 1500.00\n }\n ],\n \"transport\": { \"mode\": \"Mail\" }\n },\n {\n \"emitterType\": \"SelfIssuer\",\n \"emissionType\": \"Normal\",\n \"environment\": {{environment}},\n \"issuer\": {\n \"cnpj\": \"11222333000181\",\n \"name\": \"EMPRESA EXEMPLO LTDA - MATRIZ\",\n \"address\": {\n \"street\": \"Rua Exemplo\",\n \"number\": \"1000\",\n \"neighborhood\": \"Centro\",\n \"cityCode\": 3550308,\n \"cityName\": \"Sao Paulo\",\n \"state\": \"SP\",\n \"postalCode\": \"01001000\"\n }\n },\n \"recipient\": {\n \"cpf\": \"11144477735\",\n \"name\": \"PESSOA EXEMPLO\",\n \"address\": {\n \"street\": \"Rua do Destino\",\n \"number\": \"45\",\n \"neighborhood\": \"Centro\",\n \"cityCode\": 3550308,\n \"cityName\": \"Sao Paulo\",\n \"state\": \"SP\",\n \"postalCode\": \"01001000\"\n }\n },\n \"items\": [\n {\n \"itemNumber\": 1,\n \"description\": \"ACESSORIO DE EXEMPLO\",\n \"quantity\": 1,\n \"unitValue\": 89.90,\n \"totalValue\": 89.90\n }\n ],\n \"transport\": { \"mode\": \"Mail\" }\n }\n]", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{baseUrl}}/v1/subscriptions/{{subscriptionId}}/taxpayers/{{taxpayerId}}/contentdeclarations/$batch" }, "description": "Recebe um array de declaracoes e aceita cada uma independentemente. A resposta e sempre `200`, com um resultado por item; a posicao no array de entrada volta em `index`, e todos os itens compartilham o mesmo `batchId`.\n\n> **O lote e sempre assincrono.** Cada item aceito volta com `status: 202` - nenhum traz o documento pronto na resposta; acompanhe cada `id` por `GET {id}`.\n\n> **Nao envie `Idempotency-Key` nesta requisicao.** Esta rota nao oferece repeticao segura, e o cabecalho e **recusado** em vez de ignorado. Reenviar o mesmo lote **emite os documentos de novo**. Para ter a garantia contra duplicidade, emita **item por item** na requisicao unitaria, cada um com o seu `Idempotency-Key`.\n\nQuem nao integra pela API emite em lote subindo uma **planilha** no painel - outro caminho, que nao usa esta rota.\n\nPagina: /docs/documentacao/declaracao-de-conteudo-eletronica/integracao-api/emitir-uma-declaracao-de-conteudo" }, "response": [] } ] }, { "name": "2 - Acompanhar", "description": "O estado de um documento, a lista de varios, e o historico que explica por que um documento esta no estado em que esta.", "item": [ { "name": "Consultar uma DC-e", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/v1/subscriptions/{{subscriptionId}}/taxpayers/{{taxpayerId}}/contentdeclarations/{{documentId}}" }, "description": "Devolve o documento completo: `status`, chave de acesso, serie e numero, protocolo, itens, transporte e enderecos.\n\n`{{documentId}}` e preenchido sozinho pela requisicao de emissao.\n\nPagina: /docs/documentacao/declaracao-de-conteudo-eletronica/integracao-api/como-consultar-uma-declaracao-de-conteudo" }, "response": [] }, { "name": "Listar DC-e (OData)", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/v1/subscriptions/{{subscriptionId}}/taxpayers/{{taxpayerId}}/contentdeclarations?$top=10&$count=true&$orderby=createdAt desc" }, "description": "Consulta em lista, com `$filter`, `$orderby`, `$top`, `$skip`, `$count` e `$select`. Devolve as colunas promovidas de cada documento - chave de acesso, situacao, serie e numero, emitente, destinatario, valor total e ambiente. Itens, transporte e enderecos **nao** estao na lista: para isso e a consulta por id.\n\n- `$top` tem **teto de 200**, que tambem e o padrao. Acima disso a resposta e `400`; pagine com `$skip`\n- O total vem em `@odata.count`, e so quando voce manda `$count=true`. Ele conta sob o mesmo filtro, nao o tamanho da pagina\n- Os campos aceitos em `$filter`, `$orderby` e `$select` sao exatamente estes dezesseis: `id`, `accessKey`, `status`, `companyId`, `accountId`, `createdAt`, `batchId`, `protocol`, `serie`, `number`, `issuerName`, `issuerFederalTaxNumber`, `recipientName`, `recipientFederalTaxNumber`, `totalValue`, `environment`. Nome fora da lista responde `400`, **inclusive por diferenca de maiuscula**: a comparacao e exata\n\nDois exemplos que funcionam:\n\n- `$filter=status eq 'Authorized' and createdAt ge 2026-09-01T00:00:00Z`\n- `$select=id,status,number,totalValue`\n\nPagina: /docs/documentacao/declaracao-de-conteudo-eletronica/integracao-api/como-consultar-uma-declaracao-de-conteudo" }, "response": [] }, { "name": "Historico de eventos", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/v1/subscriptions/{{subscriptionId}}/taxpayers/{{taxpayerId}}/contentdeclarations/{{documentId}}/events" }, "description": "O historico do documento, em ordem de versao: o que aconteceu, quando, e os campos de negocio daquele acontecimento.\n\nE a resposta para *por que este documento esta neste estado?* - inclusive quando o estado e `Rejected` ou `Refused`, e para confirmar o desfecho de um cancelamento (`CancelRequested`, `Cancelled`, `CancelRejected`).\n\nPagina: /docs/documentacao/declaracao-de-conteudo-eletronica/integracao-api/como-consultar-uma-declaracao-de-conteudo" }, "response": [] } ] }, { "name": "3 - Baixar", "description": "Os dois artefatos do documento autorizado. Os dois respondem com URL temporaria de 5 minutos.", "item": [ { "name": "Baixar a DACE (PDF)", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/v1/subscriptions/{{subscriptionId}}/taxpayers/{{taxpayerId}}/contentdeclarations/{{documentId}}/pdf?layout=full" }, "description": "A DACE, a representacao impressa da DC-e. `layout=full` e o completo e `layout=summary` o resumido; qualquer outro valor devolve o completo.\n\n> A resposta padrao e `302` para uma **URL temporaria, valida por 5 minutos** - baixe na hora, nao a guarde nem a repasse. Acrescente `&format=uri` para receber `200` com `{ \"uri\": \"...\" }` em JSON em vez do redirecionamento.\n\nO PDF e representacao; o documento fiscal e o XML.\n\nPagina: /docs/documentacao/declaracao-de-conteudo-eletronica/integracao-api/dace-e-xml" }, "response": [] }, { "name": "Baixar o XML autorizado", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/v1/subscriptions/{{subscriptionId}}/taxpayers/{{taxpayerId}}/contentdeclarations/{{documentId}}/xml" }, "description": "O XML autorizado - este, sim, e o documento fiscal.\n\n> Mesma mecanica da DACE: `302` para uma URL temporaria de **5 minutos**, ou `200` com `{ \"uri\": \"...\" }` se voce acrescentar `?format=uri`.\n\nAntes de a DC-e ser autorizada nao existe XML a baixar.\n\nPagina: /docs/documentacao/declaracao-de-conteudo-eletronica/integracao-api/dace-e-xml" }, "response": [] } ] }, { "name": "4 - Cancelar", "description": "Janela de 24 horas contada da autorizacao, justificativa de 15 a 255 caracteres, e desfecho assincrono.", "item": [ { "name": "Cancelar uma DC-e", "request": { "method": "DELETE", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "If-Match", "value": "W/\"3\"", "description": "Versao esperada do documento. Divergente, a resposta e 412 e nada e enfileirado.", "disabled": true } ], "body": { "mode": "raw", "raw": "{\n \"reason\": \"Cancelamento por erro na descricao dos itens declarados\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{baseUrl}}/v1/subscriptions/{{subscriptionId}}/taxpayers/{{taxpayerId}}/contentdeclarations/{{documentId}}" }, "description": "Solicita o cancelamento de uma DC-e autorizada, com justificativa de **15 a 255 caracteres** (fora disso a resposta e `400`, regra `L-XJUST`).\n\n> **`204` significa pedido aceito, nao cancelada.** O cancelamento vai a SEFAZ de forma assincrona; confirme por `GET {id}` (`status: Cancelled`) ou pelo historico de eventos.\n\nDuas regras que so a SEFAZ responde, e por isso nao viram erro no `204`: o **prazo de 24 horas** contado da autorizacao, e o documento **ter de estar autorizado**.\n\n`If-Match` (desabilitado aqui) faz o cancelamento falhar com `412` se o documento mudou desde a sua leitura.\n\nPagina: /docs/documentacao/declaracao-de-conteudo-eletronica/integracao-api/cancelamento" }, "response": [] } ] } ], "variable": [ { "key": "baseUrl", "value": "https://api.nfe.io", "type": "string" }, { "key": "subscriptionId", "value": "", "type": "string" }, { "key": "taxpayerId", "value": "", "type": "string" }, { "key": "token", "value": "", "type": "string" }, { "key": "environment", "value": "2", "type": "string" }, { "key": "documentId", "value": "", "type": "string" } ] }