Machine translation, not yet reviewed.
CT-e events JSON — field reference
Endpoint: GET /api/integration/dfe/cte/inbound/eventos · OpenAPI reference: CT-e Public API.
Reference document — Field-by-field dictionary of the
metadataobject returned by the inbound CT-e events endpoint. The same object, compressed (Gzip+Base64), is the content of thejsonfield whenjson=true.
Endpoint: GET /api/integration/dfe/cte/inbound/eventos · OpenAPI reference: CT-e Public API.
Conventions used in this document
eventDatePartis the event's date partition (derived from thechCTekey), not an instant — it is returned as an ISO string. The other dates (dhEvento,dhRegEvento,createdAt,updatedAt) are returned as epoch milliseconds UTC.issuerTypeis always"INBOUND"in this listing — the same data model also storesOUTBOUNDevents (transmitted by MI itself), but they do not appear here.detEvento(the full signed event detail) is not serialized in this object — obtain it viaxml=true.- The API omits any field whose value is
nullfrom the response (it does not serialize"campo": null) — a field marked nullable in this table may simply not appear in the JSON. Do not assume the key always exists.
1. Fields
| Field | Type | Description |
|---|---|---|
eventDatePart | string (ISO datetime) | Event date partition (derived from chCTe), not an instant. |
id | UUID | Internal identifier of the event record. |
customerId | UUID | Tenant that owns the record. |
companyId | UUID | Company (of the tenant) that is a party to the CT-e for this item. |
chCTe | string (44) | Access key of the CT-e to which the event is linked. |
issuerType | string | "INBOUND" or "OUTBOUND". Always "INBOUND" in this listing. |
eventId | string | Event identifier at SEFAZ. Comes from the Id attribute of infEvento in the XML; if absent, it is derived as "ID" + tpEvento + chCTe + nSeqEvento (2 digits). |
cOrgao | string | IBGE code of the authority that authorized the event. |
tpAmb | short | Environment: 1 = Production; 2 = Staging (Homologação). |
cnpjCpfAutor | string | CNPJ or CPF of the event author (who registered the event at SEFAZ). |
tpEvento | int | SEFAZ event type code (e.g., cancellation, correction letter, service provision in disagreement, proof of delivery and its cancellation, failed delivery and its cancellation, GTV information, multimodal registration, payment linkage). There is no closed catalog in the backend — the parser accepts any tpEvento that DF-e Distribution delivers; the list of valid types is defined by SEFAZ, not by MI. |
dhEvento | long (epoch ms) | Event date/time, as provided by the author. |
nSeqEvento | short | Sequence number of the event for that (chCTe, tpEvento). |
cStat | short, nullable | Status code of the event's SEFAZ protocol. |
xMotivo | string, nullable | Reason/message of the SEFAZ protocol. |
xEvento | string, nullable | Textual description of the event in the return protocol. |
cnpjCpfDest | string, nullable | Destination CNPJ/CPF, when the event type carries this information in the return protocol (e.g., proof of delivery). |
emailDest | string, nullable | Destination email. Absent from the JSON in this listing — see note below. |
dhRegEvento | long (epoch ms), nullable | Date/time the event was registered at SEFAZ (return protocol). |
nProt | long, nullable | SEFAZ protocol number of the event. |
username | string, nullable | User who originated the event in MI. Absent from the JSON in this listing (only populated in the OUTBOUND flow). |
createdAt | long (epoch ms) | When the record was persisted in MI. |
updatedAt | long (epoch ms) | Last update of the record. |
2. Note: emailDest and username do not appear in inbound events
The repository (CteEventMetadataRepository.upsertReceivedEvent) explicitly writes null to emailDest for every event persisted as INBOUND; username is only populated in the OUTBOUND flow — when MI itself transmits an event to SEFAZ and then updates the record with the response (updateEvent, called by CteTransmitEventService). Since this listing filters only issuerType = INBOUND, neither field appears populated here — and since the project's serializer omits any null field from the response (it does not serialize "campo": null), the key simply does not exist in the JSON, not just the value.
Fixed in DFE-2683 (2026-08-24): the response example in the OpenAPI (
ListInboundCteEventDocumentation) at one point showed a fake value foremailDest, and later a literalnullfor both fields — neither form reflects the actual behavior. The source code has already been fixed to omit both lines from the example, and the example below (§4) follows the same fix.
3. Multiplicity per company
As in the document listing, the same SEFAZ event may appear more than once when several companies of the tenant are parties to the affected CT-e (e.g., service taker and recipient) — each company receives its own copy of the event, with a distinct companyId and the same chCTe/eventId.
4. Example
{
"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
}