Eventos de autoridade da NF-e (NT 2025.002-RTC)

A NT 2025.002-RTC (Reforma Tributária do Consumo) introduziu, para a NF-e (modelo 55), um conjunto de eventos de autoria do emitente que registram fatos ocorridos após a autorização da nota (perecimento, pagamento integral, atualização de previsão de entrega etc.). Este guia descreve o contrato funcional desses eventos na API de emissão de NF-e de produto.

Indisponível no momento

Todo o recurso de eventos está implementado na API, porém protegido por uma feature flag (DFeEvents) que ainda não foi habilitada — por decisão de produto. Enquanto não for liberado, qualquer chamada responde:

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

O contrato é publicado aqui para dar previsibilidade aos clientes e clientes piloto; até a liberação (que será comunicada), os detalhes podem mudar.

info

NFC-e (modelo 65) está fora do escopo desta Nota Técnica — os eventos valem apenas para NF-e (modelo 55).

Endpoints

Um único endpoint registra os 7 eventos; o tipo é escolhido pelo campo type (case-sensitive), e os campos do evento vão na raiz do body (não há detail aninhado).

Método	Rota	Finalidade
POST	/v2/companies/:companyId/productinvoices/:invoiceId/authority-events	Registrar um evento (inclui o cancelamento)
GET	/v2/companies/:companyId/productinvoices/:invoiceId/authority-events	Listar os eventos efetivamente registrados no SEFAZ
GET	/v2/companies/:companyId/productinvoices/:invoiceId/authority-events/:authorityEventId	Consultar um evento em qualquer estado
GET	/v2/companies/:companyId/productinvoices/:invoiceId/authority-events/:authorityEventId/xml	Obter a URL do XML do evento

O contrato completo (schemas de request/response, exemplos e códigos de retorno) está na referência de API: API de Emissão de Nota Fiscal de Produto (NFe/NFCe) - RTC.

Os 7 eventos

type	tpEvento	Uso
ExpectedDeliveryUpdate	112150	Atualizar a data de previsão de entrega
IntegralPayment	112110	Informar pagamento integral (libera crédito presumido do adquirente)
Spoilage	112130	Perecimento, perda, roubo ou furto em transporte contratado pelo fornecedor (CIF)
UnfulfilledSupply	112140	Itens pagos antecipadamente que não foram fornecidos
AlcZfmImport	112120	Importação em ALC/ZFM não convertida em isenção
PersonalUseAllocation	211120	Destinação de item de NF-e de importação para consumo pessoal
CancelDFeEvent	110001	Cancelar um evento já registrado

Eventos de campo único

ExpectedDeliveryUpdate, IntegralPayment e AlcZfmImport carregam poucos campos escalares na raiz do body (por exemplo, a nova data de previsão de entrega). Consulte a referência de API para os campos exatos de cada tipo.

Eventos com lista de itens

Spoilage, UnfulfilledSupply e PersonalUseAllocation referenciam itens da NF-e original. Cada item informa, no mínimo, o número do item (itemNumber > 0) e a quantidade afetada (> 0), validados contra a nota referenciada.

Cancelamento

O cancelamento de um evento usa o mesmo endpoint POST com type: "CancelDFeEvent" — não existe rota /cancel. É necessário informar:

• targetEventId — o id do evento a cancelar (obtido no POST original ou na consulta);
• a justificativa (15 a 1000 caracteres).

Só é possível cancelar um evento com status igual a Merged (registrado no SEFAZ) e que ainda não tenha sido cancelado.

Ciclo de vida (assíncrono)

O envio ao SEFAZ é assíncrono. O POST retorna 202 confirmando apenas o registro e o enfileiramento — o resultado final chega por WebHook ou por consulta ao evento por id.

• Status do evento: Pending → XmlSigned → Sent → Merged (registrado); ou Failed / Cancelled.
• WebHooks: dfe_event_successfully, dfe_event_error, dfe_event_failed, dfe_event_cancelled.
• GET .../authority-events (lista) retorna apenas os eventos efetivamente registrados no SEFAZ (protocolos 135, 136 ou 155). Eventos em processamento ou que falharam não aparecem na lista — para acompanhá-los, consulte por id.

Não confundir com GET /productinvoices/{invoiceId}/events, que retorna o histórico interno de processamento da nota (fluxo da plataforma), e não os eventos de autoridade da NT.

Códigos de retorno

Código	Significado
202	Evento registrado e enfileirado para envio ao SEFAZ
200	Consulta bem-sucedida (evento, lista ou URL do XML)
400	Body inválido ou nota em estado incompatível
404	Nota (ou evento) não encontrada
422	Tipo de evento ou detalhe incompatível
503	Recurso desabilitado neste ambiente (feature flag DFeEvents)