order.reversed

v3 · atual
v2 · descontinuado
v1 · descontinuado

Você está lendo o contrato atual (v3) de order.reversed. v3 é uma mudança incompatível apenas no bloco fiscal: ele passa de cancellation.metadata.fiscal para cancellation.fiscal, fica estruturado (authority, history, compensates) e sefazCancellation não é mais emitido. Os campos de auditoria de cancellation adicionados na v2 (cancellationType, cancellationGroup, cancellationNote) não mudam. Veja Mudanças de caminho em relação à versão anterior.

order.reversed dispara quando o órgão fiscal confirma o cancelamento de um documento que tinha autorizado previamente. É o resultado fiscal de order.cancelled: o pedido é cancelado primeiro dentro do Fire (order.cancelled), o cancelamento é solicitado ao órgão por meio do seu provedor fiscal, e order.reversed dispara apenas quando o órgão o aprova.

Se você precisa saber que o documento está anulado no órgão, escute este evento — não order.cancelled. order.cancelled é emitido quando o pedido é cancelado, antes de o órgão responder: seu bloco fiscal ainda descreve a fatura autorizada. Em um caso real brasileiro, order.cancelled saiu às 05:06:45, a SEFAZ aprovou às 05:06:51 e order.reversed saiu às 05:08:12.

Condição de disparo

O Fire emite order.reversed quando um documento fiscal do pedido chega a cancelled — pela integração nativa com o provedor ou pelo callback fiscal com eventType: "cancelled" — e o pedido tem um registro operacional de cancelamento no Fire. Sem esse registro o evento não é emitido: o bloco cancellation é o que diz aos consumidores que se trata de uma anulação e não de uma venda.


Cobertura	Todos os países — o país viaja em `cancellation.fiscal.countryCode`
Chave de idempotência	`event.id`
Dispara mais de uma vez	Uma vez por Integration Flow ativo inscrito no evento; com retentativa em falha de entrega
Latência em relação a `order.cancelled`	Normalmente segundos; minutos se o órgão estiver degradado
Pré-condição	Um documento autorizado anterior para o mesmo `orderId`

O que tem em `trigger.data`

O mesmo snapshot V4 do pedido que order.completed, com status: "CANCELLED", mais o bloco cancellation: os mesmos campos de auditoria de order.cancelled e, dentro dele, o bloco fiscal com o documento cancelado.

Campos de dinheiro em payments.paymentMethods[]. customerCashAmount e changeAmount são números. Os pedidos injetados antes de 24 de setembro de 2026 trazem customerCashAmount como o texto "0" e sem changeAmount: se você reenviar ou reprocessar eventos antigos, leia o campo como número. Veja a referência de campos de order.completed.

Exemplo — Brasil (NFC-e, sanitizado)

{
  "event": { "id": "…", "type": "order.reversed", "createdAt": "2026-09-15T05:08:12.359Z" },
  "data": {
    "orderId": "15801bd1-83d3-4d70-bb1b-793fd30b7bec",
    "orderCode": "OC-br-001",
    "status": "CANCELLED",
    "paymentStatus": "SUCCEEDED",
    "store": { /* igual a order.completed */ },
    "orderLines": [ /* igual a order.completed */ ],

    "cancellation": {
      "cancellationId": "6fcb0a30-cfde-4ffe-96ef-545dde3fa87c",
      "cancelledAt": "2026-09-15T05:06:44.359Z",
      "cancelledBy": "4fadc5f3-d9da-4756-978d-5a8cffc25d40",
      "cancellationType": "OTHER",
      "cancellationGroup": "Other",
      "cancellationReason": "Customer requested cancellation",
      "cancellationNote": null,
      "cancellationSource": "backoffice",

      "fiscal": {
        "status": "cancelled",
        "countryCode": "BR",
        "providerCode": "plugnotas",
        "occurredAt": "2026-09-15T05:08:11.702Z",
        "authority": {
          "documentType": "CREDIT_NOTE",
          "docSubtype": "nfce",
          "documentNumber": "12388",
          "issuedAt": "2026-09-15T05:00:48.003Z",
          "authorizedAt": "2026-09-15T03:00:00.000Z",
          "cancelledAt": "2026-09-15T05:06:51.603Z",
          "authorizationMode": "ONLINE",
          "providerDocId": "6aa8d10117b687522d90ae0a",
          "pdfUrl": "https://api.fiscal-provider.example/nfce/6aa8d10117b687522d90ae0a/pdf",
          "xmlUrl": "https://api.fiscal-provider.example/nfce/6aa8d10117b687522d90ae0a/xml",
          "amounts": { "total": 11.9, "tax": 1.65, "currencyCode": "BRL" },
          "countryData": {
            "chaveAcesso": "41201008187168000160558050010000131609769080",
            "numero": "12388",
            "serie": "2",
            "modelo": 65,
            "protocolo": "135266298552102",
            "cStat": "135"
          },
          "graphic": { "qr": "41201008187168000160558050010000131609769080" },
          "providerIdentity": null,
          "providerMetadata": null
        },
        "history": [
          {
            "status": "authorized",
            "occurredAt": "2026-09-15T05:00:48.003Z",
            "providerCode": "plugnotas",
            "authority": { /* a fatura: documentType SALE_INVOICE, cancelledAt null */ }
          },
          {
            "status": "cancelled",
            "occurredAt": "2026-09-15T05:08:11.702Z",
            "providerCode": "plugnotas",
            "authority": { /* idêntico a authority acima */ }
          }
        ],
        "compensates": {
          "documentNumber": "12388",
          "issuedAt": "2026-09-15T05:00:48.003Z"
        }
      }
    }
  },
  "_meta": { "executionId": "…", "flowId": "…", "attempt": "1" }
}

Repare que no Brasil authority.documentNumber e compensates.documentNumber são iguais (12388): a SEFAZ anula o documento em vez de emitir um novo. Em regimes onde um cancelamento é uma nota de crédito separada, eles diferem.

Referência de `data.cancellation`

Os campos de auditoria são os mesmos de order.cancelled — incluindo cancellationId, que ambos os eventos compartilham para o mesmo cancelamento e que você pode usar como chave de junção. O bloco fiscal está documentado abaixo.

O bloco fiscal

Para ver como cada campo do callback fiscal chega aqui, veja Do callback aos eventos. O bloco fiscal de order.invoiced, order.cancelled e order.reversed é o que o Fire guardou no pedido, com a mesma forma. Ele não é reconstruído por emissor: seja o documento vindo pela integração nativa do seu provedor fiscal ou pelo callback fiscal, você lê os mesmos campos na mesma profundidade.

Onde fica em cada evento

Evento	Caminho	O que carrega
`order.invoiced`	`data.fiscal`	`status`, `countryCode`, `providerCode`, `occurredAt`, `authority`, `history`, `compensates`
`order.cancelled`	`data.cancellation.fiscal`	Apenas `status` e `authority` — sem `history`, sem `compensates`. Presente só se o pedido tinha um documento `authorized` ou `cancelling` com `providerDocId`; caso contrário a chave não aparece
`order.reversed`	`data.cancellation.fiscal`	`status`, `countryCode`, `providerCode`, `occurredAt`, `authority`, `history`, `compensates`

Em um cancelamento o bloco fica em cancellation.fiscal, não em cancellation.metadata.fiscal. Ele subiu um nível. Se seus flows ou handlers leem cancellation.metadata.fiscal.*, leem undefined no contrato atual.

Campos do bloco

string | null

O status fiscal do pedido, não de um documento: awaiting_payment, not_issued, pending, processing, fiscal_graphic, authorized, cancelling, cancelled, rejected, denied, error. Na prática order.invoiced leva authorized, order.reversed leva cancelled e order.cancelled leva authorized ou cancelling.

string | null

Código ISO 3166-1 alpha-2 do regime que emitiu o documento (BR, CO, EC, CL, AR, VE). O país não vive mais no nome do evento: filtre por este campo.

string | null

Identificador do Fire para o adaptador que processou o documento (plugnotas, generic). É nosso, não o nome do provedor.

string | null

Timestamp ISO 8601 UTC do fato fiscal que disparou o evento, conforme reportado pelo provedor.

object | null

O veredito do órgão sobre o documento vigente. Os campos que significam o mesmo em todos os países ficam no topo; os identificadores próprios do órgão ficam em countryData, no vocabulário daquele país.

Mostrar authority

"SALE_INVOICE" | "CREDIT_NOTE" | null

O que o documento é. Mesmo vocabulário da numeração fiscal. Substitui o antigo docType: "invoice" | "cancellation", que não é mais emitido.No Brasil um cancelamento não emite um novo documento: o mesmo documento muda de estado, então depois de order.reversed este campo diz CREDIT_NOTE com o mesmo documentNumber e a mesma chave de acesso.

string | null

O instrumento do regime: nfce, nfe, factura, boleta, factura_a. Aberto e referencial — nunca ramifique por ele.

string | null

O número visível do documento, como o órgão o compõe (12388, 001-020-000000123, C012001).

string | null

Quando o documento foi emitido. Presente nos documentos armazenados sob este contrato; null quando desconhecido.

string | null

Quando o órgão o aprovou — um fato diferente de issuedAt. Presente nos documentos armazenados sob este contrato; null quando o órgão não o reportou.

No Brasil o dia é exato e a hora é uma convenção. A SEFAZ reporta a autorização como uma data sem hora (15/09/2026) em praticamente todos os documentos. O Fire a preenche com meia-noite no fuso horário da loja, então authorizedAt pode ficar antes de issuedAt (2026-09-15T03:00:00Z contra 2026-09-15T05:00:48Z). Não o use em nenhum cálculo que precise de precisão de hora.

string | null

Quando o órgão aprovou o cancelamento. Presente nos documentos armazenados sob este contrato; null enquanto o documento não estiver cancelado.

"ONLINE" | "OFFLINE" | "BATCH" | null

Como foi emitido. OFFLINE é contingência. Nem todo provedor tem essa noção.

string | null

Link para a representação legível (DANFE, RIDE…). Baixe e armazene: os provedores podem expirá-lo.

string | null

Link para o XML legal do órgão. Mesma hospedagem que pdfUrl.

string | null

O id do documento no sistema do seu provedor fiscal. É por ele que se buscam o PDF, o XML e um cancelamento.

object

Os valores do documento, em decimais reais (não escalados). Nos documentos armazenados sob este contrato as três chaves estão presentes, com null quando o órgão não reportou o valor. Pedidos armazenados antes dele podem não trazer alguma chave — trate uma chave ausente como null.

Mostrar amounts

number | null

Total bruto.

number | null

Imposto total.

string | null

ISO 4217 (BRL, COP, USD).

object | null

Os identificadores próprios do órgão, literais, com os nomes do próprio país — e apenas os daquele país. Veja countryData e o callback fiscal abaixo.

object | null

O que se imprime: chave → string exata a codificar (qr, ted). A chave nomeia o propósito; a simbologia é escolha do seu template. null quando não há.

object | null

Quem emitiu o documento, como o provedor o reportou (provider no callback fiscal). Quando presente, as suas três chaves estão sempre lá. null quando o provedor não se identificou.

Mostrar providerIdentity

string | null

Nome do provedor (hio.fiscalization).

string | null

Versão do emissor.

string | null

A referência própria do provedor para este documento — o que você cita ao provedor quando pergunta sobre ele.

object | null

Os extras livres do provedor (metadata no callback fiscal), tal como vieram e opacos: o Fire não os interpreta, então não ramifique por eles. null quando ausente ou vazio.

O PlugNotas (Brasil) nunca envia providerIdentity nem providerMetadata, então são null. Em um cancelamento o bloco mantém os valores do documento anterior. Documentos guardados antes deste contrato podem não trazer as duas chaves — trate a chave ausente como null.

object[]

Cada parada da jornada fiscal do pedido que descreve um documento, da mais antiga para a mais recente — incluindo a atual. Em order.invoiced normalmente tem uma entrada, igual a authority; em order.reversed tem a fatura e depois o cancelamento. Paradas sem bloco de documento não aparecem — por exemplo o cancelling que o Fire registra antes de consultar o órgão; um processing que já traz a numeração do caixa aparece.

Mostrar history[]

string | null

O status fiscal do pedido naquela parada.

string | null

Quando aquela parada aconteceu.

string | null

Adaptador que a processou.

object

O documento naquela parada, exatamente com a forma de authority acima.

Não é fiscalRepresentation.history. Aquele lista apenas os documentos anteriores da numeração; este é a jornada completa e termina com o documento atual.

object | null

Um ponteiro para o documento que o atual substitui. Presente quando o status fiscal do pedido é cancelled; null caso contrário. Aponta para a última parada de history que não é ela mesma um cancelamento — procure lá o seu documentNumber para ter o documento inteiro.

Mostrar compensates

string | null

Número visível do documento substituído.

string | null

Quando aquele documento foi emitido.

Não carrega reason, ao contrário de fiscalRepresentation.compensates. O motivo já viaja no mesmo evento, com mais detalhe: cancellation.cancellationType, cancellationGroup, cancellationReason, cancellationNote e cancellationSource. O Fire não emite order.reversed sem um registro operacional de cancelamento, então esse bloco está sempre presente quando compensates está. Um código fixo ORDER_CANCELLATION aqui diria o mesmo com menos informação. O bloco de numeração carrega sim um reason: é onde o código canônico é resolvido no texto impresso na nota de crédito, que precisa do texto próprio da empresa.

No Brasil o ponteiro se refere ao mesmo número. A SEFAZ não numera um novo documento para cancelar um, então compensates.documentNumber é igual a authority.documentNumber. Isso está correto, não é um bug.

`countryData` e o callback fiscal

countryData é um bloco com três nomes, dependendo de qual lado do Fire você olha:

Onde	Nome	Direção
Numeração fiscal	`countryData`	Fire → ponto de venda
Callback fiscal	`document`	Seu provedor → Fire
Eventos de pedido	`authority.countryData`	Fire → você

O que seu provedor envia no document do callback é o que você recebe em authority.countryData, com os mesmos nomes de chave. A regra que separa os dois é a exclusão: toda chave do callback que não é um campo canônico cai em countryData intacta. É por isso que um novo identificador de um país viaja sem nenhuma mudança do lado do Fire. Os campos raiz do callback se tornam os campos de topo de authority com os mesmos nomes, exceto os três valores, que se agrupam em amounts. provider e metadata viram providerIdentity e providerMetadata (null se ausentes ou vazios). A tabela campo a campo está em Do callback aos eventos.

O protocolo do Brasil fica em countryData, não no topo. Só a SEFAZ o tem — o Chile tem trackId, a Argentina o cae — então é vocabulário do órgão, não um campo canônico. Pedidos armazenados antes deste contrato o tinham no topo como authorizationProtocol; o Fire o emite como countryData.protocolo também para esses.

Mudanças de caminho em relação à versão anterior

Caminho anterior	Caminho atual
`fiscal.docType` (`invoice` / `cancellation`)	`fiscal.authority.documentType` (`SALE_INVOICE` / `CREDIT_NOTE`)
`fiscal.docSubtype`, `.documentNumber`, `.providerDocId`, `.pdfUrl`, `.xmlUrl`, `.issuedAt`, `.cancelledAt`, `.authorizationMode`	`fiscal.authority.<mesmo nome>`
`fiscal.dataAutorizacao`	`fiscal.authority.authorizedAt`
`fiscal.emittedAt`	`fiscal.authority.issuedAt`
`fiscal.totalAmount` / `.taxAmount` / `.currencyCode`	`fiscal.authority.amounts.total` / `.tax` / `.currencyCode`
`fiscal.protocolo`	`fiscal.authority.countryData.protocolo`
`fiscal.chaveAcesso`, `.numero`, `.serie`, `.modelo` (BR) · `.claveAcceso`, `.establecimiento`, `.puntoEmision`, `.secuencial`, `.ambiente` (EC) · `.cufe`, `.prefijo`, `.numeroDian` (CO) · `.folio`, `.ted`, `.tipoDte`, `.trackId` (CL) · `.cae`, `.fechaVtoCae`, `.puntoVenta`, `.tipoComprobante` (AR) · `.numeroControl`, `.numeroFactura` (VE)	`fiscal.authority.countryData.<mesmo nome>`
`cancellation.metadata.fiscal.*`	`cancellation.fiscal.*` (mesmas regras acima)
`fiscal.cStat`, `cancellation.metadata.fiscal.sefazCancellation.*`	não emitido

Cada caminho anterior tem exatamente um caminho atual. O payload não carrega número de versão: a versão pertence a este contrato documentado.

Lifecycle

Um pedido cancelado antes de seu documento ser autorizado só dispara order.cancelled: não há nada a estornar no órgão.

Handler de exemplo

async function onOrderReversed(data) {
  const { orderId, cancellation } = data;
  const fiscal = cancellation.fiscal;
  const doc = fiscal.authority;

  await db.fiscalDocs.update({
    where: { providerDocId: doc.providerDocId },
    data: {
      status: "cancelled",
      documentType: doc.documentType,
      cancelledAt: doc.cancelledAt,
      reason: cancellation.cancellationType,
    },
  });

  // O documento substituído, inteiro, está em history.
  const replaced = fiscal.history.find(
    (e) => e.authority.documentNumber === fiscal.compensates?.documentNumber
      && e.status !== "cancelled",
  );

  await reconciliation.close(orderId, { original: replaced?.authority });
}

Erros comuns

Leia cancellation.fiscal, não cancellation.metadata.fiscal. O caminho anterior vem vazio na v3.
sefazCancellation não existe mais. A data do cancelamento é authority.cancelledAt; os identificadores do órgão estão em authority.countryData.
A entrega fora de ordem é possível. Se chegar um order.reversed de um pedido para o qual você não tem cancelamento, crie-o a partir do bloco cancellation deste evento em vez de descartar o evento.
Não há evento para um cancelamento que falhou. Se o órgão rejeitar o cancelamento, nenhum evento dispara.

Eventos relacionados

order.cancelled

Dispara antes deste evento — o próprio cancelamento do pedido.

order.invoiced

O evento que reportou o documento que aqui é cancelado.

Callback fiscal

Como um provedor reporta o cancelamento que dispara este evento.

`data.fiscalRepresentation`

Sem mudanças na v3. Guarda os números do comprovante impresso no caixa — o que está sendo anulado — e é um bloco diferente de cancellation.fiscal: fiscalRepresentation é o que foi numerado, authority é o que o órgão decidiu. A referência de campos está na página v2.

Conceitos

Catálogo

Condição de disparo

O que tem em `trigger.data`

Exemplo — Brasil (NFC-e, sanitizado)

Referência de `data.cancellation`

O bloco fiscal

Onde fica em cada evento

Campos do bloco

`countryData` e o callback fiscal

Mudanças de caminho em relação à versão anterior

Lifecycle

Handler de exemplo

Erros comuns

Eventos relacionados

order.cancelled

order.invoiced

Callback fiscal

`data.fiscalRepresentation`

​Condição de disparo

​O que tem em trigger.data

​Exemplo — Brasil (NFC-e, sanitizado)

​Referência de data.cancellation

​O bloco fiscal

​Onde fica em cada evento

​Campos do bloco

​countryData e o callback fiscal

​Mudanças de caminho em relação à versão anterior

​Lifecycle

​Handler de exemplo

​Erros comuns

​Eventos relacionados

order.cancelled

order.invoiced

Callback fiscal

​data.fiscalRepresentation

Condição de disparo

O que tem em `trigger.data`

Exemplo — Brasil (NFC-e, sanitizado)

Referência de `data.cancellation`

O bloco fiscal

Onde fica em cada evento

Campos do bloco

`countryData` e o callback fiscal

Mudanças de caminho em relação à versão anterior

Lifecycle

Handler de exemplo

Erros comuns

Eventos relacionados

`data.fiscalRepresentation`