> ## Documentation Index > Fetch the complete documentation index at: https://docs.fire.rest/llms.txt > Use this file to discover all available pages before exploring further. # order.cancelled > Um pedido injetado foi cancelado. Carrega o snapshot V4 completo mais um bloco de auditoria de cancelamento com quem, quando, por quê e o contexto fiscal original. 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. O contrato **v2.1** continua válido: v2.2 apenas soma um bloco, nada do anterior mudou. O contrato **v2** está **descontinuado** — mantido como referência histórica. Abra aqui: [`order.cancelled` — v2](/pt/events-v2/order-cancelled). O contrato **v1** está **descontinuado**. Abra aqui: [order-cancelled — v1](/pt/events-v1/order-cancelled). O contrato **v0** está **descontinuado**. Abra aqui: [order-cancelled — v0](/pt/events-v0/order-cancelled). `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 emite `order.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). | | | | -------------------------- | -------------------------------------------------------------------------------------------------------------- | | Cobertura | Global (todos os países, todos os canais) | | Chave de idempotência | `event.id` | | Dispara mais de uma vez | Não, salvo em retentativas | | Ordem | Não garantida contra `order.completed` para o mesmo pedido — ordene por timestamps se precisar | | Retentativas | Até 5 tentativas com backoff exponencial (quando `retryOnFailure` está habilitado) | | Contexto fiscal brasileiro | Inclui dados fiscais originais em `cancellation.metadata.fiscal` se o pedido tinha sido fiscalmente autorizado | ## O que tem em `trigger.data` Mesmo snapshot V4 que [`order.completed`](/pt/events/order-completed) — todos os campos documentados lá estão presentes aqui, com três diferenças: 1. `status` é **`"CANCELLED"`** (não `"COMPLETED"`). 2. `paymentStatus` permanece igual a quando o pedido foi completado (tipicamente `"SUCCEEDED"` se o pedido tinha sido pago antes do cancelamento). 3. Um novo bloco top-level **`cancellation`** carrega a metadata de auditoria. ## Exemplo — payload real de produção (BR, sanitizado) ```json theme={null} { "event": { "id": "abcf3781-c327-4df1-84ef-5efbacc1d387", "type": "order.cancelled", "createdAt": "2026-05-05T23:06:08.883Z" }, "data": { "orderId": "e98f5725-0d1e-4f93-ac18-40f1068cae89", "orderCode": "OC-br-001", "businessDayDate": "2026-03-31", "externalOrderId": "ac331b68-66fb-48ee-b110-a40181bfb379", "status": "CANCELLED", "paymentStatus": "SUCCEEDED", "redeemPoints": false, "accumulatePoints": false, "discount": false, "createdAt": "2026-05-05T23:05:00.438Z", "orderComment": "Comentário de teste do pedido", "marketing": null, "store": { /* igual a order.completed — veja /pt/events/order-completed */ }, "device": { /* ... */ }, "channel": { /* ... */ }, "operator": { /* ... */ }, "client": { /* ... */ }, "payments": { /* ... */ }, "kds": { /* ... */ }, "metadata": {}, "orderLines": [ /* ... */ ], "fulfillment": { /* ... */ }, "cancellation": { "cancellationId": "abcf3781-c327-4df1-84ef-5efbacc1d387", "cancelledAt": "2026-05-05T23:06:08.883Z", "cancelledBy": "00000000-0000-0000-0000-000000000000", "cancellationReason": "Cliente solicitou cancelamento", "cancellationType": "CUSTOMER_REQUESTED", "cancellationGroup": "Cliente", "cancellationNote": "cliente pidió cancelar", "cancellationSource": "backoffice", "metadata": { "fiscal": { "numero": "1000013", "pdfUrl": "https://api.fiscal-provider.example/nfce//pdf", "xmlUrl": "https://api.fiscal-provider.example/nfce//xml", "protocolo": "141200000956123", "docSubtype": "nfce", "chaveAcesso": "41201008187168000160558050010000131609769080", "providerDocId": "69fa77aa2a48c20329be4604", "dataAutorizacao": "2026-05-05T23:05:15.590Z" } } } }, "_meta": { "executionId": "...", "flowId": "...", "attempt": "1" } } ``` ## Referência de `data.cancellation` Bloco de auditoria que descreve como, quando e por quem o pedido foi cancelado. UUID para este evento de cancelamento. Estável através de retentativas. Timestamp ISO 8601 UTC do cancelamento. UUID do operador/usuário que cancelou o pedido. `null` para cancelamentos iniciados pelo sistema (ex.: um flow automatizado). Razão free-text capturada no momento do cancelamento. Pode ser empty ou `null`. Onde o cancelamento se originou. Valores incluem `backoffice`, `adapter`, `api`. Use para ramificar a lógica do handler. Código estável do motivo. Catálogo interno (ex. `ITEM_OUT_OF_STOCK`) ou código numérico de agregador/SAG (ex. `1010`). **Sempre presente** — `null` quando nenhum motivo estruturado foi definido. Categoria do motivo. Interno (ex. `Inventario`, `Cliente`) ou agregador (ex. `SAG (KEETA)`, `SAG (IFOOD)`). **Sempre presente** — `null` quando nenhum motivo estruturado foi definido. Nota de texto livre opcional inserida no cancelamento. **Sempre presente** — `null` quando nenhuma nota foi inserida. Contexto extra. Hoje só inclui `fiscal` (quando aplica). **Apenas Brasil — presente quando o pedido tinha sido fiscalmente autorizado antes do cancelamento.** Contém o contexto do documento fiscal original para que seu sistema downstream possa reconciliar contra o documento previamente emitido. Campos: `serie`, `numero`, `pdfUrl`, `xmlUrl`, `protocolo`, `docSubtype` (ex.: `nfce`, `nfe`), `chaveAcesso` (chave de acesso SEFAZ de 44 dígitos), `providerDocId` (ID interno do seu provedor fiscal), `dataAutorizacao` (ISO 8601 UTC da autorização original). Este é o dado fiscal **original** no momento do cancelamento, **não** o resultado do cancelamento SEFAZ. O resultado SEFAZ chega em um evento separado [`order.reversed`](/pt/events/order-reversed) com `cancellation.metadata.fiscal.sefazCancellation` populado. ## Lifecycle relativo a outros eventos Para um pedido brasileiro fiscal-enabled que é cancelado, espere esta sequência: ```mermaid theme={null} flowchart LR A([pedido pago]) --> B([order.completed]) B --> C([order.invoiced]) C --> D([usuário cancela]) D --> E([order.cancelled]) E --> F([SEFAZ confirma]) F --> G([order.reversed]) ``` * `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ós `order.cancelled`, dependendo do tempo de resposta da SEFAZ. * Para pedidos não brasileiros ou lojas sem emissão fiscal, apenas `order.cancelled` dispara. ## 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`](/pt/events/order-reversed) seguirá. Para lojas não-BR (Argentina, Chile, Colômbia, Equador, Venezuela, outras), o bloco cancellation fica assim: ```json Cancelamento não-BR theme={null} { "cancellation": { "cancellationId": "abcf3781-c327-4df1-84ef-5efbacc1d387", "cancelledAt": "2026-05-05T23:06:08.883Z", "cancelledBy": "00000000-0000-0000-0000-000000000000", "cancellationReason": "Cliente solicitou cancelamento", "cancellationType": "CUSTOMER_REQUESTED", "cancellationGroup": "Cliente", "cancellationNote": "cliente pidió cancelar", "cancellationSource": "backoffice", "metadata": { "fiscal": null } } } ``` Os identificadores a nível de loja em `data.store` variam por país — veja [`order.completed` → Variações por país](/pt/events/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 ```js theme={null} async function onOrderCancelled(data) { const { orderId, store, cancellation } = data; // 1. Marque o pedido como cancelado no seu sistema (idempotente) await db.orders.update({ where: { fireOrderId: orderId }, data: { status: "CANCELLED", cancelledAt: new Date(cancellation.cancelledAt), cancellationReason: cancellation.cancellationReason, cancellationSource: cancellation.cancellationSource, }, }); // 2. Se a loja tem fiscal habilitado e havia um doc fiscal, // abra um ticket de reconciliação — o cancelamento SEFAZ // seguirá em order.reversed. if (cancellation.metadata?.fiscal) { await reconciliation.open({ orderId, country: store.locationInfo.country.code, originalDoc: cancellation.metadata.fiscal, pendingSefazCancel: true, }); } // 3. Reverta side-effects downstream (libera estoque, refund, etc.) await downstream.rollback(orderId); } ``` ## `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. | Bloco | O que é | Confiar? | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | | `policy.deferredPayment` | Se o pedido pode ser trabalhado **antes** do pagamento. Resolvido uma vez na injeção e carimbado imutável — todos os eventos seguintes repetem o mesmo valor. | Sim. É uma decisão, não um estado. | | `lastKnown` | Foto orientativa do estado de cozinha (`kds`) e fiscal na emissão do evento. Pode vir `null` ou desatualizado. | **Não.** Nunca condicione uma ação irreversível a isto. | ```json theme={null} "policy": { "deferredPayment": { "eligible": true, "resolvedAt": "2026-08-02T15:55:42.407Z", "configVersion": "fnv1a:3144c6fb", "resolvedFrom": { "channelCode": "APP", "fulfillmentCode": "DELIVERY", "paymentMethod": "CASH" } } }, "lastKnown": { "kds": null, "fiscal": { "status": "processing", "sourceEvent": "fiscal.callback" } } ``` O detalhe campo a campo está em [`order.opened`](/pt/events/order-opened#política-de-pagamento-diferido), o evento onde estes blocos mais importam. ## Erros comuns * **`status === "CANCELLED"`, não `paymentStatus`.** Pedidos pagos cancelados mantêm `paymentStatus === "SUCCEEDED"`; o cancelamento vive no campo `status` mais o bloco `cancellation`. * **`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.completed` chegou primeiro.** Entrega fora de ordem é possível — seu handler deveria tolerar receber `order.cancelled` para um `orderId` que ainda não conhece (ex.: log + cria um placeholder; reconcilia quando `order.completed` chegar). * **`cancellation.metadata.fiscal` é o doc original, não o resultado do cancelamento.** Para a confirmação SEFAZ, escute [`order.reversed`](/pt/events/order-reversed). ## Eventos relacionados O evento que você verá para o mesmo pedido antes do cancelamento. 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 presença deste bloco NÃO significa que o comprovante esteja autorizado.** São os números impressos no caixa; o veredito do órgão está em `lastKnown.fiscal.status`. Um ticket que diga "autorizado" só porque o bloco está presente declara algo que pode não ter acontecido. **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: ```js theme={null} if (data.fiscalRepresentation) { // houve tentativa de numeração — veja numberingStatus para saber como saiu } ``` | Campo | O que é | | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `numberingStatus` | Como terminou o **ato de numerar**: `GENERATED`, `PENDING`, `FAILED_RETRYABLE`, `FAILED_FINAL`, `UNAVAILABLE`. **Não é o veredito do órgão** — esse está em `lastKnown.fiscal.status`. | | `documentNumber` | Número visível do comprovante, composto conforme o país (`005-004-000000042`). É apresentação e **quem o monta é o Fire**, não o órgão: para conciliar use `countryData`. | | `issuedAt` | Quando foi **numerado**. Não é a data de autorização. | | `authorizationMode` | `ONLINE`, `OFFLINE` ou `BATCH`. Conceito do provedor, não universal. | | `providerCode` | Identificador do adaptador que numerou. | | `countryData` | Os identificadores do órgão, no vocabulário do **país que numerou** — e só os desse país. Equador: `numeroComprobante` (o número visível do comprovante, já montado pelo provedor), `claveAcceso`, `establecimiento`, `puntoEmision`, `secuencial`, `ambiente`. Venezuela: `numeroControl`, `numeroFactura`, `serie`. **Percorra-o; não o indexe às cegas** — uma chave nova não é uma mudança que quebra. É o mesmo bloco que o endpoint de numeração devolve e que o callback do órgão traz. A referência por país, com as chaves de cada regime, está em [`countryData` por país](/pt/api-reference/fiscal-documents#countrydata-por-país). | | `graphic` | O artefato imprimível que o provedor devolveu (QR e afins), tal como veio. `null` se não devolveu nenhum. | | `failure` | Por que **não** há comprovante. `null` quando a numeração deu certo. | | `providerIdentity` | **Quem numerou, do lado do provedor**: `{ "name": "hio.fiscalization", "version": "2026.08.1", "reference": "HIO-91f3c2" }`. Diferente da bolsa abaixo, **tem forma**: os três campos estão no contrato e sempre chegam, com `null` quando não se aplicam. `reference` é **a referência de suporte do provedor** — o identificador que se cita a ele para encontrar a operação nos registros dele; não é a `Idempotency-Key` que o canal enviou. Não leva `providerCode`: esse é nosso e viaja acima. | | `providerMetadata` | **A bolsa de diagnóstico do provedor**, tal como ele a devolveu: no Equador com a HIO chega `{ "deviceUid": "4B8E…", "externalStoreCode": "K000" }`. É **opaca** — as chaves são do provedor e podem mudar sem aviso, então não programe contra elas; serve para colar num ticket, não para ramificar. **É exatamente o mesmo campo que o endpoint de numeração devolve**, com o mesmo nome e o mesmo conteúdo: os três campos do provedor se leem igual nos dois extremos. | | `environment` | Em qual ambiente o **Fire** numerou: `SANDBOX` ou `PRODUCTION`. É nosso, não do órgão — o do órgão viaja dentro de `countryData` com o código do país. | | `compensates` | Qual documento este anula. Presente **apenas** quando `documentType` é `CREDIT_NOTE`; `null` nos demais. Traz `documentNumber`, `issuedAt` e `reason` (o código canônico — o texto impresso é redigido por empresa e resolvido na resposta do endpoint de numeração). | | `history` | Os documentos **anteriores** do pedido, do mais antigo ao mais novo. Vazio enquanto houve apenas um; quando um cancelamento numera, a nota de venda desce para cá e a nota de crédito fica no topo. Cada entrada tem **a mesma forma** do bloco acima, então se leem igual. Somente documentos: uma tentativa de numeração que falhou não entra. | ```json theme={null} "fiscalRepresentation": { "numberingStatus": "GENERATED", "documentType": "CREDIT_NOTE", "documentNumber": "005-004-000000004", "countryData": { "numeroComprobante": "005-004-000000004", "claveAcceso": "1208202604000000000000110050040000000041234567816", "establecimiento": "005", "puntoEmision": "004", "secuencial": "000000004", "ambiente": "2" }, "authorizationMode": "ONLINE", "issuedAt": "2026-08-13T09:02:11.318Z", "providerCode": "hio", "graphic": { "qr": "1208202604000000000000110050040000000041234567816" }, "failure": null, "providerIdentity": { "name": "hio.fiscalization", "version": "2026.08.1", "reference": "HIO-91f3c2" }, "providerMetadata": { "deviceUid": "4B8E21F9A0D35C7A", "externalStoreCode": "K004" }, "environment": "PRODUCTION", "compensates": { "documentNumber": "005-004-000000042", "issuedAt": "2026-08-13T08:11:29.744Z", "reason": "ORDER_CANCELLATION" }, "history": [ { "numberingStatus": "GENERATED", "documentType": "SALE_INVOICE", "documentNumber": "005-004-000000042", "countryData": { "numeroComprobante": "005-004-000000042", "claveAcceso": "1208202601000000000000110050040000000421234567810", "establecimiento": "005", "puntoEmision": "004", "secuencial": "000000042", "ambiente": "2" }, "authorizationMode": "ONLINE", "issuedAt": "2026-08-13T08:11:29.744Z", "providerCode": "hio", "graphic": { "qr": "1208202601000000000000110050040000000421234567810" }, "failure": null, "providerIdentity": { "name": "hio.fiscalization", "version": "2026.08.1", "reference": "HIO-91f3c2" }, "providerMetadata": { "deviceUid": "4B8E21F9A0D35C7A", "externalStoreCode": "K004" }, "environment": "PRODUCTION", "compensates": null } ] } ``` **O veredicto do órgão não o altera.** O que o cliente levou impresso não muda porque o órgão depois autorize ou rejeite — para isso existe `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êm `null` e o motivo em `failure`. ```json theme={null} "fiscalRepresentation": { "numberingStatus": "FAILED_FINAL", "documentNumber": null, "issuedAt": null, "providerCode": "hio", "graphic": null, "failure": { "code": "RUC_INVALIDO", "scope": "FUNCTIONAL", "message": "CNPJ não habilitado" } } ``` Ramifique por `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.