CT-e eventos JSON — referência de campos
Endpoint: GET /api/integration/dfe/cte/inbound/eventos · Referência OpenAPI: CT-e Public API.
Documento de referência — Dicionário campo a campo do objeto
metadataretornado pelo endpoint de eventos CT-e inbound. O mesmo objeto, comprimido (Gzip+Base64), é o conteúdo do campojsonquandojson=true.
Endpoint: GET /api/integration/dfe/cte/inbound/eventos · Referência OpenAPI: CT-e Public API.
Convenções deste documento
eventDateParté a partição de data do evento (derivada da chavechCTe), não um instante — sai como string ISO. As demais datas (dhEvento,dhRegEvento,createdAt,updatedAt) saem como epoch milliseconds UTC.issuerTypeé sempre"INBOUND"nesta listagem — o mesmo modelo de dados também guarda eventosOUTBOUND(transmitidos pelo próprio MI), mas eles não aparecem aqui.detEvento(o detalhe assinado completo do evento) não é serializado neste objeto — obtenha-o viaxml=true.- A API omite qualquer campo com valor
nullda resposta (não serializa"campo": null) — um campo marcado nullable nesta tabela pode simplesmente não aparecer no JSON. Não assuma que a chave sempre existe.
1. Campos
| Campo | Tipo | Descrição |
|---|---|---|
eventDatePart | string (ISO datetime) | Partição de data do evento (derivada de chCTe), não um instante. |
id | UUID | Identificador interno do registro do evento. |
customerId | UUID | Tenant proprietário do registro. |
companyId | UUID | Empresa (do tenant) que é parte do CT-e para este item. |
chCTe | string (44) | Chave de acesso do CT-e ao qual o evento está vinculado. |
issuerType | string | "INBOUND" ou "OUTBOUND". Sempre "INBOUND" nesta listagem. |
eventId | string | Identificador do evento na SEFAZ. Vem do atributo Id de infEvento no XML; se ausente, é derivado como "ID" + tpEvento + chCTe + nSeqEvento (2 dígitos). |
cOrgao | string | Código IBGE do órgão autorizador do evento. |
tpAmb | short | Ambiente: 1 = Produção; 2 = Homologação. |
cnpjCpfAutor | string | CNPJ ou CPF do autor do evento (quem registrou o evento na SEFAZ). |
tpEvento | int | Código SEFAZ do tipo de evento (ex.: cancelamento, carta de correção, prestação em desacordo, comprovante de entrega e seu cancelamento, insucesso de entrega e seu cancelamento, informações da GTV, registro multimodal, vinculação de pagamento). Não há catálogo fechado no backend — o parser aceita qualquer tpEvento que a Distribuição DF-e entregue; a lista de tipos válidos é definida pela SEFAZ, não pelo MI. |
dhEvento | long (epoch ms) | Data/hora do evento, informada pelo autor. |
nSeqEvento | short | Número sequencial do evento para aquele (chCTe, tpEvento). |
cStat | short, nullable | Código de status do protocolo SEFAZ do evento. |
xMotivo | string, nullable | Motivo/mensagem do protocolo SEFAZ. |
xEvento | string, nullable | Descrição textual do evento no protocolo de retorno. |
cnpjCpfDest | string, nullable | CNPJ/CPF de destino, quando o tipo de evento carrega essa informação no protocolo de retorno (ex.: comprovante de entrega). |
emailDest | string, nullable | Email de destino. Ausente do JSON nesta listagem — ver nota abaixo. |
dhRegEvento | long (epoch ms), nullable | Data/hora de registro do evento na SEFAZ (protocolo de retorno). |
nProt | long, nullable | Número do protocolo SEFAZ do evento. |
username | string, nullable | Usuário que originou o evento no MI. Ausente do JSON nesta listagem (só é preenchido no fluxo OUTBOUND). |
createdAt | long (epoch ms) | Quando o registro foi persistido no MI. |
updatedAt | long (epoch ms) | Última atualização do registro. |
2. Nota: emailDest e username não aparecem em eventos inbound
O repositório (CteEventMetadataRepository.upsertReceivedEvent) grava explicitamente null para emailDest em todo evento persistido como INBOUND; username só é populado no fluxo OUTBOUND — quando o próprio MI transmite um evento à SEFAZ e depois atualiza o registro com o retorno (updateEvent, chamado por CteTransmitEventService). Como esta listagem filtra apenas issuerType = INBOUND, nenhum dos dois campos aparece preenchido aqui — e como o serializador do projeto omite qualquer campo null da resposta (não serializa "campo": null), a chave simplesmente não existe no JSON, não apenas o valor.
Corrigido em DFE-2683 (2026-08-24): o exemplo de resposta no OpenAPI (
ListInboundCteEventDocumentation) chegou a mostrar um valor fake paraemailDest, depoisnullliteral para os dois campos — nenhuma das duas formas reflete o comportamento real. O código-fonte já foi corrigido para omitir as duas linhas do exemplo, e o exemplo abaixo (§4) segue a mesma correção.
3. Multiplicidade por empresa
Assim como na listagem de documentos, um mesmo evento SEFAZ pode aparecer mais de uma vez quando várias empresas do tenant são partes do CT-e afetado (ex.: tomador e destinatário) — cada empresa recebe sua própria cópia do evento, com companyId distinto e o mesmo chCTe/eventId.
4. Exemplo
{
"eventDatePart": "2026-01-01T00:00:00",
"id": "0198c0de-0000-7000-8000-000000000003",
"customerId": "0198c0de-0000-7000-8000-000000000001",
"companyId": "0198c0de-0000-7000-8000-000000000002",
"chCTe": "35260111111111111111570010000000011000000015",
"issuerType": "INBOUND",
"eventId": "ID1101113526011111111111111157001000000001100000001501",
"cOrgao": "35",
"tpAmb": 2,
"cnpjCpfAutor": "11111111111111",
"tpEvento": 110111,
"dhEvento": 1768469400000,
"nSeqEvento": 1,
"cStat": 135,
"xMotivo": "Evento registrado e vinculado a CT-e",
"xEvento": "Cancelamento registrado",
"cnpjCpfDest": "22222222222222",
"dhRegEvento": 1768471200000,
"nProt": 135260000000002,
"createdAt": 1768478400000,
"updatedAt": 1768478700000
}