- v3 · atual
- v2.2 · descontinuado
- v1 · descontinuado
- v0 · descontinuado
Você está lendo o contrato atual (v3) de
order.cancelled. v3 é uma mudança incompatível apenas no contexto fiscal: cancellation.metadata.fiscal passa a ser cancellation.fiscal, estruturado como { status, authority }, e agora se aplica a todo país com um documento autorizado, não só ao Brasil. cancellation.metadata não é mais emitido. O resto do evento não muda. Veja Mudanças de caminho em relação à versão anterior.order.cancelled dispara quando um pedido previamente injetado é cancelado — pelo backoffice do Fire (cancellationSource: backoffice), ou por um adaptador ou a API de cancelamento (cancellationSource: adapter). Não retrai um order.completed anterior do mesmo pedido; ambos os eventos são emitidos independentes.
Condição de disparo
O Fire emiteorder.cancelled uma vez quando um pedido transiciona para CANCELLED, independente do estado de pagamento anterior, com contexto completo de auditoria.
O que tem em trigger.data
O mesmo snapshot V4 do pedido que order.completed, com quatro diferenças:
statusé"CANCELLED".paymentStatusnão muda (tipicamente"SUCCEEDED"se o pedido tinha sido pago).- Um bloco top-level
cancellationcarrega a metadata de auditoria e, quando aplicável, o documento fiscal. - Não há
data.fiscalna raiz. Neste evento o documento do órgão vive só emcancellation.fiscal.
policy e lastKnown viajam exatamente como em order.completed. fiscalRepresentation tem a mesma forma, mas se para o cancelamento foi numerada uma nota de crédito, traz essa nota no topo e a fatura em history. No Brasil (PlugNotas) fiscalRepresentation é null: não há etapa de numeração. authority.providerIdentity e authority.providerMetadata aparecem nos documentos guardados sob este contrato; em pedidos anteriores as chaves podem faltar — trate a chave ausente como null.
Exemplo — Brasil, com documento autorizado (sanitizado)
Exemplo — sem documento autorizado
Quando o pedido não tinha documento autorizado (o órgão ainda não tinha respondido, a loja não emite documentos, ou o documento não tem id do provedor), a chavefiscal está ausente — não null. Aqui, uma loja que não numera no caixa, cancelada antes de o órgão responder: fiscalRepresentation é null, lastKnown.fiscal ainda diz processing e cancellation não tem fiscal. Nenhum order.reversed vem depois.
Nos países que numeram no caixa, um pedido não pode ser cancelado enquanto a sua fatura estiver vigente: o Fire responde 409 (FISCAL_REPRESENTATION_NOT_VOIDED) até que a nota de crédito seja pedida. Depois disso, o evento traz fiscalRepresentation com a CREDIT_NOTE no topo e a fatura em history.
if (data.cancellation.fiscal).
Os blocos omitidos como igual a
order.completed são byte a byte o snapshot que order.completed carrega. Veja a referência de campos de order.completed.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.Referência de data.cancellation
object
Bloco de auditoria que descreve como, quando e por quem o pedido foi cancelado.
O bloco fiscal
Para ver como cada campo do callback fiscal chega aqui, veja Do callback aos eventos. O bloco fiscal deorder.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
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.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.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.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:
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
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 relativo a outros eventos
order.cancelledé emitido imediatamente, antes de contatar o órgão.order.reversedvem em seguida quando o órgão confirma — segundos ou minutos depois.- Sem documento autorizado, só dispara
order.cancelled.
Handler de exemplo
Erros comuns
- Leia
cancellation.fiscal, nãocancellation.metadata.fiscal. O caminho anterior vem vazio na v3. cancellation.fiscalé o documento antes da anulação. Para a confirmação do órgão, escuteorder.reversed.- Ausente, não
null. Teste a presença da chave; não compare comnull. order.cancellednão é um reembolso. O reembolso, se houver, é iniciado pelo canal ou processador.- Não assuma que
order.completedchegou primeiro. Tolere umorder.cancelledde um pedido que você ainda não conhece.
Eventos relacionados
order.completed
O evento que você verá para o mesmo pedido antes do cancelamento.
order.reversed
Dispara quando o órgão confirma o cancelamento do documento.
data.fiscalRepresentation
Sem mudanças na v3. É a numeração fiscal impressa no caixa, um bloco diferente de cancellation.fiscal: nunca diz que o documento foi autorizado. Quando um cancelamento numera uma nota de crédito, essa nota fica no topo e a fatura desce para fiscalRepresentation.history. É o mesmo bloco de order.completed — referência de campos em order.completed → data.fiscalRepresentation.
data.policy e data.lastKnown
Sem mudanças na v3 e iguais em todos os eventos de pedido. lastKnown.fiscal.status é o estado fiscal atual do pedido e é orientativo — nunca condicione uma ação irreversível a ele. Referência em order.completed → data.policy e data.lastKnown.