Pular para o conteúdo principal
Ver como MarkdownDocs para agentes

Como consultar uma DC-e pela API

GET /v1/subscriptions/{subscriptionId}/taxpayers/{taxpayerId}/contentdeclarations/{id}

Devolve o estado atual de uma DC-e e o que foi declarado nela:

  • situação (status, flowStatus), chave de acesso, protocolo, série e número;
  • emitente e destinatário — nome e CNPJ ou CPF — e o valor total;
  • os itens declarados, em items, com os mesmos nomes de campo do corpo da emissão e na mesma ordem;
  • quais arquivos já podem ser baixados, em artifacts (veja DACE e XML);
  • o código e o motivo da SEFAZ quando ela rejeitou (rejectionCStat, rejectionReason) ou respondeu ao cancelamento (cancellationCStat, cancellationReason);
  • o lote (batchId), a versão do leiaute registrada na criação (specVersion) e o ambiente (environment: 1 produção, 2 homologação).

Endereços, transporte e informações adicionais não estão no detalhe. Se precisar deles, guarde o corpo que você enviou na emissão ou baixe o XML autorizado.

O campo status​

ValorSignificado
CreatedCriado, ainda não transmitido
ProcessingEm processamento
AuthorizedAutorizado pela SEFAZ — tem accessKey e protocol
RejectedRejeitado pela SEFAZ — veja rejectionCStat e rejectionReason
CancelledCancelado
RefusedParou por veredito nosso — veja refusedStep e refusedReasons
UnknownSituação que esta versão do contrato não conhece
Rejected e Refused não são a mesma coisa

Rejected é a SEFAZ dizendo não, depois de receber o documento — motivo fiscal, com cStat. Refused é a NFE.io parando a emissão antes de transmitir — cadastro incompleto, certificado com problema, ou validação local. Um documento Refused nunca chegou à SEFAZ.

Tolere valores de status que você não conhece

status e flowStatus podem ganhar valores novos sem aviso, e durante uma atualização do serviço duas versões podem conviver por alguns minutos. Trate um valor desconhecido (Unknown ou outro) como "estado que ainda não conheço" e não falhe.

Documento autorizado
{
  "id": "0f6b1f5c-9a5e-4a0e-9c1b-2f4e6d8a1b23",
  "status": "Authorized",
  "flowStatus": "Finished",
  "accessKey": "33260811222333000181990010000000211208201894",
  "serie": 1,
  "number": 21,
  "protocol": "133260000123456",
  "createdAt": "2026-08-19T13:04:11.512Z",
  "artifacts": { "hasFull": true, "hasSummary": true, "hasXml": true },
  "issuerName": "EMPRESA EXEMPLO LTDA - MATRIZ",
  "issuerFederalTaxNumber": "11222333000181",
  "recipientName": "EMPRESA EXEMPLO LTDA - FILIAL",
  "recipientFederalTaxNumber": "99887766000105",
  "totalValue": 3000,
  "items": [
    {
      "itemNumber": 1,
      "description": "EQUIPAMENTO DE EXEMPLO",
      "ncm": "84713012",
      "quantity": 2,
      "unitValue": 1500.00,
      "totalValue": 3000.00
    }
  ],
  "specVersion": "1.00",
  "environment": 2
}
Documento rejeitado pela SEFAZ (Rejected) — itens abreviados
{
  "id": "5d1e9a77-3c2b-4f0e-8a6d-7b9c0e1f2a34",
  "status": "Rejected",
  "flowStatus": "Finished",
  "accessKey": "33260811222333000181990010000000221208201890",
  "serie": 1,
  "number": 22,
  "createdAt": "2026-08-19T14:10:02.118Z",
  "artifacts": { "hasFull": false, "hasSummary": false, "hasXml": false },
  "rejectionCStat": 812,
  "rejectionReason": "Usuário emitente bloqueado para emissão de DCe",
  "issuerName": "EMPRESA EXEMPLO LTDA - MATRIZ",
  "issuerFederalTaxNumber": "11222333000181",
  "recipientName": "EMPRESA EXEMPLO LTDA - FILIAL",
  "recipientFederalTaxNumber": "99887766000105",
  "totalValue": 3000,
  "items": [ … ],
  "environment": 2
}
Documento recusado por nós (Refused) — itens abreviados
{
  "id": "0f6b1f5c-9a5e-4a0e-9c1b-2f4e6d8a1b23",
  "status": "Refused",
  "flowStatus": "Finished",
  "serie": 0,
  "number": 0,
  "refusedStep": "DefineNumber",
  "refusedReasons": ["Empresa sem certificado digital válido em custódia"],
  "createdAt": "2026-08-19T13:04:11.512Z",
  "artifacts": { "hasFull": false, "hasSummary": false, "hasXml": false },
  "issuerName": "EMPRESA EXEMPLO LTDA - MATRIZ",
  "issuerFederalTaxNumber": "11222333000181",
  "recipientName": "EMPRESA EXEMPLO LTDA - FILIAL",
  "recipientFederalTaxNumber": "99887766000105",
  "totalValue": 3000,
  "items": [ … ],
  "environment": 2
}

Campos opcionais sem valor são omitidos do JSON — nunca devolvidos como null. É por isso que o exemplo Refused não tem accessKey nem protocol: nenhum dos dois chegou a existir. Alguns campos têm outra regra:

  • serie e number vêm 0 enquanto a numeração não foi definida;
  • artifacts e items vêm sempre — sem artefato, os três has* são false; sem item, items é [];
  • issuerName e recipientName vêm sempre, e podem vir como texto vazio ("");
  • rejectionCStat, cancellationCStat e os motivos correspondentes só aparecem quando a SEFAZ respondeu algo a eles;
  • specVersion só aparece quando foi registrada na criação.

Os textos da SEFAZ (rejectionReason, cancellationReason) vêm em português, como ela respondeu.

O cabeçalho ETag​

A resposta 200 traz o cabeçalho ETag com a versão atual do documento, no formato de ETag fraca:

ETag: W/"4"

É esse valor que vai no If-Match do cancelamento: se o documento mudar entre a sua leitura e o pedido de cancelamento, a resposta é 412 e nada é enviado.

O histórico de eventos​

GET /v1/subscriptions/{subscriptionId}/taxpayers/{taxpayerId}/contentdeclarations/{id}/events

Devolve o histórico do documento, em ordem de versão — é a resposta para "por que este documento está neste estado?", inclusive quando o estado é Rejected ou Refused.

eventTypeO que traz em data
ContentDeclarationCreatedemitterType, emissionType, serie, number
NumberDefinednumber, serie, accessKey
SentToSefazNada além de tipo, versão e data
Authorizedprotocol, authorizedAt
RejectedcStat, reason
ContingencyAcceptedaccessKey
DaceGeneratedhasFull, hasSummary, hasXml
CancelRequestedreason, cancellationProtocol, cStat
Cancelledprotocol, cancelledAt, cStat
CancelRejectedcStat, reason
NotifiedeventType (o evento notificado)
Refusedstep (o passo em que a NFE.io parou a emissão), reasons
FlowFailedstep, reasons — uma falha no processamento daquele passo
FlowExhaustedstep, reasons, attempts (quantas tentativas foram feitas), cStat — as tentativas daquele passo se esgotaram
AuthorizationNotFoundstep, reasons, attempts, notFoundAnswers (quantas vezes a SEFAZ respondeu que não encontrou a autorização), cStat
ReprocessExecutedstep — o documento voltou a ser processado a partir desse passo

Os eventos de falha guardam o motivo no histórico de forma permanente. Se o documento voltar a ser processado depois de uma falha, refusedStep e refusedReasons são limpos no detalhe, mas o histórico continua mostrando o que aconteceu.

O histórico é uma projeção curada

XML assinado e dados pessoais completos não aparecem aqui de propósito. Tipos de evento novos podem surgir — um tipo que você não conhece vem apenas com tipo, versão e data, sem data.

Histórico — criação, numeração e autorização
[
  {
    "eventType": "ContentDeclarationCreated",
    "version": 1,
    "occurredAt": "2026-08-19T13:04:11.512Z",
    "data": {
      "emitterType": "SelfIssuer",
      "emissionType": "Normal",
      "serie": 1,
      "number": 0
    }
  },
  {
    "eventType": "NumberDefined",
    "version": 2,
    "occurredAt": "2026-08-19T13:04:12.004Z",
    "data": {
      "number": 21,
      "serie": 1,
      "accessKey": "33260811222333000181990010000000211208201894"
    }
  },
  {
    "eventType": "Authorized",
    "version": 4,
    "occurredAt": "2026-08-19T13:04:19.881Z",
    "data": {
      "protocol": "133260000123456",
      "authorizedAt": "2026-08-19T13:04:19Z"
    }
  }
]

Consultar várias de uma vez​

Quando o que você precisa é uma grade — o que foi emitido hoje, o que está preso em Processing, o que a SEFAZ rejeitou — a consulta em lista responde em uma chamada:

GET /v1/subscriptions/{subscriptionId}/taxpayers/{taxpayerId}/contentdeclarations

Ela aceita $filter, $orderby, $top, $skip, $count e $select, e devolve as colunas promovidas de cada documento — chave de acesso, situação, série e número, emitente, destinatário, valor total e ambiente. Itens, transporte e endereços não estão na lista: para os itens, use o GET {id} acima.

Quatro coisas que costumam pegar quem começa:

  • A resposta não é um array nu. As linhas vêm em value, no envelope OData.
  • $top tem teto de 200, que também é o padrão. Acima disso a resposta é 400; pagine com $skip.
  • O total vem em @odata.count, e só quando você manda $count=true. Ele conta sob o mesmo filtro, não o tamanho da página.
  • Opção que a listagem não sabe resolver é 400, com type terminado em unsupported-query, título The query could not be resolved. e, em detail, a mensagem do interpretador da consulta dizendo o que não foi entendido.

No filtro por lote ($filter=batchId eq '…'), um GUID casa com ou sem hífens.

Os parâmetros, o conjunto fechado de campos filtráveis e o que responde 400 estão na referência da operação.

Erros​

CódigoO que significa
400Na listagem: opção de consulta que não pode ser resolvida (unsupported-query) ou $top acima de 200
401Token ausente, inválido ou expirado — peça um novo token (veja Autenticação)
403A assinatura da URL não é a do token nem uma que o usuário acessa (type termina em subscription-scope-undetermined)
404Empresa da URL inexistente ou fora da assinatura (type termina em company-not-in-subscription), ou documento inexistente nessa empresa

Veja também​

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.