NF-e authority events (NT 2025.002-RTC)

NT 2025.002-RTC (Brazilian Consumption Tax Reform) introduced, for NF-e (model 55), a set of issuer authority events that record facts occurring after the invoice is authorized (spoilage, integral payment, delivery-forecast update, etc.). This guide describes the functional contract of those events in the Product NF-e issuance API.

Currently unavailable

The entire events surface is implemented in the API but protected by a feature flag (DFeEvents) that has not been enabled yet — by product decision. Until it is released, any call returns:

503 Service Unavailable
{ "errors": [ { "message": "DFe events surface is currently disabled in this environment." } ] }

The contract is published here to give predictability to customers and pilot customers; until release (which will be announced), details may change.

info

NFC-e (model 65) is out of scope for this Technical Note — the events apply only to NF-e (model 55).

Endpoints

A single endpoint registers all 7 events; the type is chosen by the type field (case-sensitive), and the event fields go at the root of the body (there is no nested detail).

Method	Route	Purpose
POST	/v2/companies/:companyId/productinvoices/:invoiceId/authority-events	Register an event (including cancellation)
GET	/v2/companies/:companyId/productinvoices/:invoiceId/authority-events	List the events actually registered at SEFAZ
GET	/v2/companies/:companyId/productinvoices/:invoiceId/authority-events/:authorityEventId	Fetch a single event in any state
GET	/v2/companies/:companyId/productinvoices/:invoiceId/authority-events/:authorityEventId/xml	Get the event XML URL

The full contract (request/response schemas, examples and status codes) is in the API reference: Product Invoice issuance API (NFe/NFCe) - RTC.

The 7 events

type	tpEvento	Use
ExpectedDeliveryUpdate	112150	Update the expected delivery date
IntegralPayment	112110	Report integral payment (releases the buyer's presumed credit)
Spoilage	112130	Spoilage, loss, robbery or theft in transport contracted by the supplier (CIF)
UnfulfilledSupply	112140	Items paid in advance that were not supplied
AlcZfmImport	112120	ALC/ZFM import not converted into exemption
PersonalUseAllocation	211120	Allocation of an imported NF-e item to personal use
CancelDFeEvent	110001	Cancel a previously registered event

Single-field events

ExpectedDeliveryUpdate, IntegralPayment and AlcZfmImport carry a few scalar fields at the body root (e.g., the new expected delivery date). See the API reference for the exact fields of each type.

Item-list events

Spoilage, UnfulfilledSupply and PersonalUseAllocation reference items of the original NF-e. Each item provides, at minimum, the item number (itemNumber > 0) and the affected quantity (> 0), validated against the referenced invoice.

Cancellation

Cancelling an event uses the same POST endpoint with type: "CancelDFeEvent" — there is no /cancel route. You must provide:

• targetEventId — the id of the event to cancel (from the original POST or from a query);
• the justification (15 to 1000 characters).

An event can only be cancelled when its status equals Merged (registered at SEFAZ) and it has not been cancelled yet.

Life cycle (asynchronous)

Submission to SEFAZ is asynchronous. The POST returns 202 confirming only the registration and enqueue — the final result arrives via WebHook or by querying the event by id.

• Event status: Pending → XmlSigned → Sent → Merged (registered); or Failed / Cancelled.
• WebHooks: dfe_event_successfully, dfe_event_error, dfe_event_failed, dfe_event_cancelled.
• GET .../authority-events (list) returns only the events actually registered at SEFAZ (protocols 135, 136 or 155). Events still processing or that failed do not appear in the list — to track them, query by id.

Do not confuse this with GET /productinvoices/{invoiceId}/events, which returns the invoice's internal processing history (platform flow), not the NT authority events.

Status codes

Code	Meaning
202	Event registered and enqueued for submission to SEFAZ
200	Successful query (event, list or XML URL)
400	Invalid body or invoice in an incompatible state
404	Invoice (or event) not found
422	Incompatible event type or detail
503	Feature disabled in this environment (DFeEvents feature flag)