order.status_updated

Evento novo (junho 2026). Nasce diretamente na v1 — não existe forma v0.

order.status_updated dispara quando o KDS (Kitchen Display System) reporta que um pedido avançou de status na cozinha: começou a ser preparado (preparing), está pronto (ready) ou foi despachado (dispatched). O Fire recebe o reporte do KDS pelo webhook de status de entrada, valida que ele referencia um evento emitido pelo Fire para esse pedido, aplica um gate anti-regressão (um status nunca retrocede: dispatched não volta para ready) e só então emite este evento. Por isso você recebe um evento por avanço real — sem duplicados, sem retrocessos.

Condição de disparo

O Fire emite order.status_updated quando tudo a seguir é verdadeiro:

O KDS reportou um status de cozinha para um pedido existente
O status avança o percurso (gate anti-regressão: preparing → ready → dispatched)
O reporte passou na validação de origem (referencia um evento que o Fire emitiu para esse pedido)


Cobertura	Todos os países
Status	`preparing` → `ready` → `dispatched` (monotônico)
Chave de idempotência	`event.id`
Dispara mais de uma vez	Uma vez por avanço de status (máx. 3 por pedido); retentativas compartilham `event.id`
Origem do dado	`kitchen.source` — apenas `kds` hoje; o campo fica aberto a fontes futuras

O que vem em `data`

É um payload leve (thin) — diferente de order.completed, não carrega o pedido completo. Carrega o necessário para agir sobre uma mudança de status: a identidade do pedido, refs mínimas de canal / loja, o tipo de fulfillment, e o bloco kitchen (o avanço + o percurso). Omite de propósito orderLines, payments, taxes, client, device e o endereço de entrega — você já recebeu isso em order.completed; faça o match por orderId / externalOrderId e aplique a mudança.

{
  "event": {
    "id": "7f3c2a1b-9d4e-4f6a-8b2c-1e5d3a7f9c0b",
    "type": "order.status_updated",
    "createdAt": "2026-06-10T18:24:31.000Z"
  },
  "data": {
    "orderId": "443bb714-fb69-4538-9ecb-de0acad7b88f",
    "orderCode": "OC-br-001",
    "externalOrderId": "f3bf9fa1-baa8-4050-9e37-4e6d905ee308",
    "businessDayDate": "2026-05-25",
    "status": "COMPLETED",
    "channel": { "code": "99", "uid": "6bac8d41-..." },
    "store": {
      "code": "BR-SP-001",
      "name": "Lab Store BR",
      "account": { "uid": "100", "name": "Sandbox" },
      "vendor":  { "uid": "100.2.1", "name": "Deli Burger BR" }
    },
    "fulfillment": { "service": { "code": "DELIVERY" } },
    "kitchen": {
      "status": "ready",
      "previousStatus": "preparing",
      "rank": 2,
      "occurredAt": "2026-06-10T18:24:29.000Z",
      "stationName": "Cozinha quente",
      "providerEventId": "kds-evt-8842",
      "kdsEventLogId": "1a2b3c4d-...",
      "source": "kds",
      "history": [
        { "status": "preparing", "rank": 1, "occurredAt": "2026-06-10T18:12:02.000Z", "stationName": "Cozinha quente" },
        { "status": "ready",     "rank": 2, "occurredAt": "2026-06-10T18:24:29.000Z", "stationName": "Cozinha quente" }
      ]
    }
  }
}

Identidade e contexto

orderId

string

UUID do pedido no Fire — faça o match com o order.completed que você recebeu.

orderCode

string

Código legível do pedido.

externalOrderId

string

O id do pedido no canal/agregador — use-o para fazer o match do lado deles.

status

string

Status de negócio do pedido (COMPLETED / CANCELLED). Contexto — o percurso da cozinha é paralelo.

channel

object

code (canônico, sempre presente — ex. 99) e uid. O nome legível do canal vem do seu catálogo de channels, não deste evento.

store

object

Ref mínima da loja: code, name, mais account { uid, name } e vendor { uid, name }.

fulfillment

object

service.code — DELIVERY ou PICKUP. Dá sentido ao status (um ready para delivery vs pickup).

O bloco `kitchen`

kitchen

object

O avanço que disparou o evento + o percurso completo. Distinto do bloco kds (dados estáticos do pedido capturados na injeção).

Mostrar kitchen

status

string

Status que disparou o evento: preparing | ready | dispatched.

previousStatus

string | null

Status anterior. null no primeiro avanço.

rank

number

Sequência do percurso: preparing=1 < ready=2 < dispatched=3. Webhooks não chegam ordenados — use isto para detectar eventos antigos/fora de ordem (ignore um rank menor que o último que você aplicou).

occurredAt

string

ISO 8601 — quando ocorreu no KDS (relógio do cliente).

stationName

string | null

Estação que reportou, se o KDS enviar.

providerEventId

string

Chave de dedup do reporte de entrada do KDS.

kdsEventLogId

string

O id do recibo do Fire para o evento KDS de entrada (cross-audit).

source

string

Quem reportou. Apenas kds hoje.

history

array

Percurso completo até agora — uma entrada por marco (status, rank, occurredAt, stationName), ordenado por rank. Permite reconstruir todo o caminho a partir de um único evento e reconciliar se chegarem fora de ordem.

Casos de uso típicos

Acompanhamento do pedido para o cliente — “seu pedido está pronto” no app ou tela de retirada
Notificar o agregador — avisar iFood/Rappi/99food que o pedido está pronto para o entregador
Métricas de cozinha — tempos preparing→ready por loja/estação a partir de history

O que NÃO faz

Não muda o status do pedido. data.status continua "COMPLETED" — o percurso de cozinha é paralelo ao ciclo de pagamento/faturamento.
Nunca retrocede. Se o KDS reportar ready depois de dispatched, o Fire descarta (gate anti-regressão) e não emite nada.
Não substitui order.completed. Assine os dois: order.completed para o fato de negócio, order.status_updated para o progresso físico.

​Condição de disparo

​O que vem em data

​Identidade e contexto

​O bloco kitchen

​Casos de uso típicos

​O que NÃO faz

Condição de disparo

O que vem em `data`

Identidade e contexto

O bloco `kitchen`

Casos de uso típicos

O que NÃO faz