- v2.2 · atual
- v2.1 · anterior
- v2 · descontinuado
- v1 · descontinuada
- v0 · descontinuada
Você está lendo o contrato atual (v2.2) de
order.cancelled. v2.2 adiciona data.fiscalRepresentation: a numeração fiscal que o ponto de venda obteve antes de injetar o pedido. Viaja sempre: em null quando não se tentou numerar, e preenchido quando sim — numberingStatus diz como terminou. Trazer conteúdo não significa que o comprovante esteja autorizado. Apenas aditivo — nada do que você já lia mudou.O bloco carrega o documento fiscal vigente do pedido: os campos que significam o mesmo em qualquer país no topo, os identificadores do órgão dentro de countryData no vocabulário do seu país, e os documentos anteriores em history. Quando um cancelamento numera, a nota de crédito passa ao topo e a de venda desce para o histórico — com compensates apontando para ela.order.cancelled dispara quando um pedido previamente injetado é cancelado — pela UI do backoffice do Fire, um adaptador externo ou uma chamada à API de cancelamento. 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 o status de um pedido transiciona para CANCELLED, independente do estado de pagamento anterior. O cancelamento é registrado com contexto completo de auditoria (quem, quando, por quê, fonte).
O que tem em trigger.data
Mesmo snapshot V4 que order.completed — todos os campos documentados lá estão presentes aqui, com três diferenças:
statusé"CANCELLED"(não"COMPLETED").paymentStatuspermanece igual a quando o pedido foi completado (tipicamente"SUCCEEDED"se o pedido tinha sido pago antes do cancelamento).- Um novo bloco top-level
cancellationcarrega a metadata de auditoria.
Exemplo — payload real de produção (BR, sanitizado)
Referência de data.cancellation
object
Bloco de auditoria que descreve como, quando e por quem o pedido foi cancelado.
Lifecycle relativo a outros eventos
Para um pedido brasileiro fiscal-enabled que é cancelado, espere esta sequência:order.cancelledé emitido imediatamente quando o cancelamento acontece, antes de contatar qualquer autoridade fiscal externa.order.reversedé emitido depois — uma vez que a SEFAZ confirma via seu provedor fiscal. Pode chegar segundos ou minutos apósorder.cancelled, dependendo do tempo de resposta da SEFAZ.- Para pedidos não brasileiros ou lojas sem emissão fiscal, apenas
order.cancelleddispara.
Variações por país
order.cancelled é global — dispara para todos os países e todos os canais quando um pedido é cancelado (Argentina, Brasil, Chile, Colômbia, Equador, Venezuela e qualquer outro país com Integration Flows ativos). O bloco de auditoria de cancelamento (cancellation.{cancellationId, cancelledAt, cancelledBy, cancellationReason, cancellationSource}) é idêntico em todos os países.
O único campo específico por país é cancellation.metadata.fiscal, que é populado apenas para lojas brasileiras que tinham um documento fiscal previamente autorizado (ou seja, um order.invoiced foi emitido para este pedido antes). Para todos os demais países — e para pedidos BR cancelados antes da autorização fiscal — cancellation.metadata.fiscal é null e nenhum evento order.reversed seguirá.
Para lojas não-BR (Argentina, Chile, Colômbia, Equador, Venezuela, outras), o bloco cancellation fica assim:
Cancelamento não-BR
data.store variam por país — veja order.completed → Variações por país para country.code, currencyCode e storeFiscalConfig.govIdType (CNPJ / CUIT / RUT / NIT / RUC / RIF) por país.
Handler de exemplo
data.policy e data.lastKnown
Todos os eventos de pedido carregam estes dois blocos, não só este. Foram
adicionados junto com o ciclo de pagamento diferido e são adicionados na v2.1, aditivos:
consumidores existentes continuam funcionando sem alteração.
order.opened,
o evento onde estes blocos mais importam.
Erros comuns
status === "CANCELLED", nãopaymentStatus. Pedidos pagos cancelados mantêmpaymentStatus === "SUCCEEDED"; o cancelamento vive no campostatusmais o blococancellation.order.cancelled≠ refund. O Fire reporta o cancelamento; o refund (se houver) é iniciado pelo canal/processador e não está neste payload.- Não assuma que
order.completedchegou primeiro. Entrega fora de ordem é possível — seu handler deveria tolerar receberorder.cancelledpara umorderIdque ainda não conhece (ex.: log + cria um placeholder; reconcilia quandoorder.completedchegar). cancellation.metadata.fiscalé o doc original, não o resultado do cancelamento. Para a confirmação SEFAZ, escuteorder.reversed.
Eventos relacionados
order.completed
O evento que você verá para o mesmo pedido antes do cancelamento.
order.reversed
Apenas Brasil — dispara quando a SEFAZ confirma o cancelamento.
data.fiscalRepresentation
A numeração fiscal que o ponto de venda obteve antes de injetar o pedido:
cobra, pede os identificadores, imprime o comprovante e só então injeta. Por isso
viaja no pedido e não em um evento fiscal separado — quando o pedido nasce, isso
já aconteceu.
A chave viaja sempre. Chega em null quando não se tentou numerar
— agregadores, países sem representação fiscal, ou comércios com a numeração
desativada — e traz o bloco quando houve tentativa.
Trazer o bloco significa que se tentou numerar, não que foi numerado:
numberingStatus diz como a tentativa terminou, e failure por quê quando não
terminou bem.
Ramifique pelo valor, não pela presença da chave:
lastKnown.fiscal,
que é o que de fato se move.
O que o substitui é um documento novo. O bloco carrega o documento fiscal
vigente do pedido. Enquanto houve apenas um, era sempre a nota de venda;
quando um cancelamento produz uma nota de crédito, é ela que fica no topo —
documentType diz qual é — e a nota de venda desce para history, inteira e
com seus próprios identificadores do órgão. Não se perde: se move. compensates
aponta para ela pelo número, então a relação fica explícita.
Quando a numeração falha
Uma venda pode ser cobrada e ficar sem comprovante fiscal. Esse caso também viaja, e precisa ser tratado: os identificadores vêmnull e o motivo em
failure.
failure.scope:
TECHNICAL— imprima “em trâmite” e siga. Pode se resolver sozinho.FUNCTIONAL— há um dado errado e repetir não resolve. Precisa correção. O que muda élastKnown.fiscal.
lastKnown.fiscal.sourceEvent agora informa a procedência real. Antes era
deduzida do status, e um processing semeado na injeção era reportado como
fiscal.callback sem que nenhum callback tivesse ocorrido. Esse caso agora diz
order.injected. Se você ramifica por este campo, contemple o valor novo.