---
title: "Como consultar uma DC-e pela API"
description: "Como acompanhar o estado de uma DC-e — o campo status, a diferença entre Rejected e Refused, e o histórico de eventos do documento."
source_url: https://nfe.io/docs/documentacao/declaracao-de-conteudo-eletronica/integracao-api/como-consultar-uma-declaracao-de-conteudo
last_updated: 2026-09-04
---

# Como consultar uma DC-e pela API

```
GET /v2/companies/{companyId}/ContentDeclarations/{id}
```

Devolve o estado atual de uma DC-e — situação, chave de acesso, protocolo, numeração, emitente, destinatário e valor total.

:::caution A consulta não traz os itens declarados
A resposta traz nome, inscrição e valor total do emitente e do destinatário — não os itens, nem o endereço completo. Guarde o corpo que você enviou na emissão, ou [baixe o XML autorizado](./dace-e-xml.md), se precisar do detalhe completo.
:::

## O campo `status`

| Valor | Significado |
|---|---|
| `Created` | Criado, ainda não transmitido |
| `Processing` | Em processamento |
| `Authorized` | Autorizado pela SEFAZ — tem `accessKey` e `protocol` |
| `Rejected` | Rejeitado **pela SEFAZ**, com `cStat` no histórico |
| `Cancelled` | Cancelado |
| `Refused` | Parou por veredito **nosso** — veja `refusedStep` e `refusedReasons` |
| `Unknown` | Situação que esta versão do contrato não conhece |

:::tip `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` no histórico de eventos. `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.
:::

:::caution Tolere valores de status que você não conhece
`status` e `flowStatus` podem ganhar valores novos sem aviso — implantação é em ondas, e por alguns minutos convivem duas versões do serviço. Trate um valor desconhecido (`Unknown` ou outro) como "estado que ainda não conheço" e não falhe — um consumidor que estoura em enum novo repete, do lado do cliente, o mesmo tipo de incidente que a API já teve do lado do servidor.
:::

```json title="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",
  "issuerName": "EMPRESA EXEMPLO LTDA - MATRIZ",
  "issuerFederalTaxNumber": "11222333000181",
  "recipientName": "EMPRESA EXEMPLO LTDA - FILIAL",
  "recipientFederalTaxNumber": "99887766000105",
  "totalValue": 3000
}
```

```json title="Documento recusado por nós (Refused)"
{
  "id": "0f6b1f5c-9a5e-4a0e-9c1b-2f4e6d8a1b23",
  "status": "Refused",
  "flowStatus": "DefineNumber",
  "refusedStep": "DefineNumber",
  "refusedReasons": ["Empresa sem certificado digital válido em custódia"],
  "createdAt": "2026-08-19T13:04:11.512Z",
  "issuerName": "EMPRESA EXEMPLO LTDA - MATRIZ",
  "issuerFederalTaxNumber": "11222333000181"
}
```

Campos ausentes são omitidos do JSON — nunca devolvidos como `null`. É por isso que o exemplo `Refused` acima não tem `accessKey`, `serie`, `number`, `protocol`: nenhum deles chegou a existir.

## O histórico de eventos

```
GET /v2/companies/{companyId}/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`.

| `eventType` | O que traz em `data` |
|---|---|
| `ContentDeclarationCreated` | `emitterType`, `emissionType`, `serie`, `number` |
| `NumberDefined` | `number`, `serie`, `accessKey` |
| `SentToSefaz` | Nada além de tipo, versão e data |
| `Authorized` | `protocol`, `authorizedAt` |
| `Rejected` | `cStat`, `reason` |
| `ContingencyAccepted` | `accessKey` |
| `DaceGenerated` | `hasFull`, `hasSummary`, `hasXml` |
| `CancelRequested` | `reason`, `cancellationProtocol`, `cStat` |
| `Cancelled` | `protocol`, `cancelledAt`, `cStat` |
| `CancelRejected` | `cStat`, `reason` |
| `Notified` | `eventType` (o evento notificado) |

:::caution 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`.
:::

```json title="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"
    }
  }
]
```

## Erros

| Código | O que significa |
|---|---|
| `401` | Token ausente, expirado, com audiência errada, ou chave de API no lugar de JWT |
| `403` | Token válido mas sem o escopo/papel da operação, ou assinatura não determinada |
| `404` | Documento inexistente, ou fora da assinatura do token |

## Veja também

- [Emitir uma DC-e](./emitir-uma-declaracao-de-conteudo.md)
- [Cancelamento de DC-e](./cancelamento.md)
- [DACE e XML](./dace-e-xml.md)