Saltar para o conteúdo principal
O Fire emite eventos sempre que ocorre uma transição de negócio relevante — um pedido é completado, um pedido é cancelado, um documento fiscal é autorizado pela autoridade tributária, a cozinha avança um pedido. Cada evento é entregue ao seu endpoint por um Integration Flow que você configura no dashboard do Fire.
O Fire emite cinco tipos de evento de pedido hoje: order.completed, order.cancelled, order.invoiced, order.reversed e order.status_updated, mais o evento agendado store.business_day_closed no fechamento do dia.

​
O Fire é a fonte da verdade do ciclo de vida

Um pedido pode nascer em qualquer canal — POS, kiosk, app, agregador — mas a partir do momento em que entra, o Fire o normaliza e assume o controle de todo o seu ciclo de vida. Tudo o que acontece em torno desse pedido se centraliza no Fire: o pagamento o completa, a cozinha o avança, o provedor fiscal o fatura ou estorna, e o fechamento do dia o consolida. Cada um desses marcos chega aos seus sistemas como um evento com o mesmo snapshot canônico do pedido. Essa centralização funciona em ambas as direções: sistemas externos nunca escrevem estado por conta própria — eles reportam ao Fire por webhooks de entrada, e cada reporte deve referenciar um evento que o Fire emitiu (o eventId do envelope que você recebeu). O Fire valida essa referência antes de aceitar o reporte; um callback que não aponte para um evento emitido pelo Fire para esse pedido é rejeitado com 400. Assim, a linha do tempo de um pedido tem uma única fonte de verdade e nunca se bifurca.
O diagrama de sequência mostra o ciclo de vida no tempo — incluindo os dois round-trips em que o provedor fiscal e o KDS resolvem e reportam de volta ao Fire. O diagrama estrutural resume em quem fala com quem.

​
Ciclo de vida no tempo

​
Quem fala com quem

Repare nos dois circuitos de ida e volta: o Fire avisa o faturador (②), o faturador resolve com a autoridade (③) e responde ao Fire pelo callback (④) — só então o Fire emite order.invoiced / order.reversed (⑤). O mesmo com a cozinha: o Fire despacha o pedido ao KDS (⑥), o KDS reporta o avanço ao Fire (⑦) e o Fire emite order.status_updated (⑧). Nada fica sabendo “por conta própria”: tudo passa pelo Fire e sai do Fire — incluindo o store.business_day_closed (⑨) no fechamento do dia.

​
Uma ação, um evento

Cada ação de negócio é seu próprio evento com seu próprio event.id — order.invoiced para uma autorização fiscal, order.reversed para um cancelamento, cada order.status_updated para uma transição de cozinha. Eles nunca são colapsados: autorizar um pedido e depois cancelá-lo são dois eventos distintos com dois ids distintos. Isso define como o Fire faz o match dos reportes inbound que disparam essas ações:
  • Um reporte referencia o evento daquela ação. Ao reportar um cancelamento ao Fire, ecoe o event.id do evento de cancelamento — não o da autorização. Cada (orderId, eventId) é ingerido exatamente uma vez.
  • Reenviar o mesmo reporte é seguro. O mesmo (orderId, eventId) com o mesmo tipo é um replay idempotente — o Fire retorna o registro existente e não processa nada duas vezes (202, duplicate: true). Você pode regenerar seu próprio id de provedor livremente.
  • Você não pode pendurar uma ação no evento de outra. Reportar um cancelamento reusando o eventId da autorização é rejeitado com 409 — aceitá-lo diria que o cancelamento teve sucesso enquanto o Fire nunca cancelou. Cada ação deve referenciar seu próprio evento emitido pelo Fire.
Uma exceção — a jornada da cozinha. O KDS reporta preparing → ready → dispatched contra um eventId (o do dispatch), distinguidos por eventType — então o mesmo eventId com um type diferente é um passo novo, não um conflito. A regra acima (um eventId por ação) vale para o fiscal (uma ação = um evento); a jornada do KDS compartilha um evento de dispatch entre seus passos. Em ambos os casos, um reporte deve referenciar um evento emitido pelo Fire, e a mesma (orderId, eventId, eventType) é ingerida uma vez.
Veja o callback fiscal e o endpoint KDS para as matrizes completas de comportamento inbound.

​
Como funciona

Quando ocorre um evento de negócio relevante, o Fire o despacha através de um flow que você configurou no dashboard. O flow renderiza um body de requisição HTTP e faz POST para o seu endpoint. Você confirma com uma resposta 2xx. A mecânica interna (filas, retentativas, resolução de templates) está em Entrega e retentativas. O modelo de configuração de flows está em Integration Flows.

​
O que seu endpoint recebe

Quando um flow dispara, seu endpoint recebe um POST HTTP. O body tem três campos top-level — event, data e _meta: 
{
  "event": {
    "id": "0d6e8a1c-1e7a-4b4f-8a3a-74ab0e9a9b21",
    "type": "order.completed",
    "createdAt": "2026-05-06T13:42:11.812Z"
  },
  "data": {
    /* snapshot V4 específico do evento — veja cada referência */
  },
  "_meta": {
    "executionId":     "0d6e8a1c-1e7a-4b4f-8a3a-74ab0e9a9b21",
    "flowId":          "9a2b3c4d-7e8f-4a1b-9c2d-3e4f5a6b7c8d",
    "flowName":        "Integração ERP",
    "attempt":         "1",
    "triggerEntityId": "f1e2d3c4-b5a6-4789-9012-3456789abcde"
  }
}

​
event

​
event
object
Identifica esta entrega.

​
data

​
data
object
Payload específico do evento. O formato varia por evento:
EventoO que tem em data
order.completedSnapshot V4 do pedido — order, store (com storeFiscalConfig opcional), customer, payments, fulfillment, KDS, lines
order.cancelledSnapshot V4 + bloco cancellation de auditoria
order.invoicedSnapshot V4 com order.fiscal (chave, protocolo, número…) + storeFiscalConfig
order.reversedSnapshot V4 + xmlCancelamento + sefazCancellation
order.status_updatedSnapshot V4 + bloco kitchen (status, previousStatus, history do percurso)

​
_meta

​
_meta
object
Rastreabilidade a nível de execução. Logue junto com o evento para debugar problemas de entrega e correlacionar retentativas.
As chaves event, data e _meta vêm do template canônico de body que o dashboard do Fire inclui. São uma convenção, não um envelope Fire fixo — se o nó HTTP do seu flow definir outro template, o formato do wire muda. Veja Customizando o body abaixo.

​
Entrega HTTP padrão

CampoDefault
MétodoPOST (configurável por flow)
Content-Typeapplication/json (definido pelos headers do nó HTTP do seu flow)
Timeout30 segundos (configurável, 1–60s)
AuthNone / Bearer / x-api-key / OAuth2 client credentials — escolhido por flow
AssinaturaHMAC-SHA256 opcional (nó Webhook) — X-Fire-Signature + X-Fire-Timestamp
RetentativasAté 5 com backoff exponencial
Dead letterApós as retentativas, a execução cai em flow_dead_letter
As requisições de saída podem ser assinadas com HMAC se o seu flow usar o nó Webhook: o Fire adiciona X-Fire-Signature (v1=hex(HMAC-SHA256(secret, "{timestamp}.{body}"))) e X-Fire-Timestamp (Unix seconds). A assinatura é opcional e complementa o auth de transporte (Bearer / API key / OAuth2). Detalhe e verificação no nó Webhook assinado.

​
Recebendo eventos

import express from "express";

const app = express();
const seen = new Map(); // troque por Redis / DB em produção

app.post("/fire/events", express.json(), async (req, res) => {
  const { event, data, _meta } = req.body ?? {};
  if (!event?.id || !event?.type) return res.status(400).end();

  // 1. Confirme primeiro para liberar a conexão do Fire
  res.status(200).end();

  // 2. Deduplique por event.id (o ID de execução do flow)
  if (seen.has(event.id)) return;
  seen.set(event.id, Date.now());

  // 3. Logue _meta para rastreabilidade — inestimável ao debugar
  console.log("Evento Fire", { eventId: event.id, type: event.type, _meta });

  // 4. Despache por type
  switch (event.type) {
    case "order.completed":     return onOrderCompleted(data);
    case "order.cancelled":     return onOrderCancelled(data);
    case "order.invoiced":       return onOrderInvoiced(data);
    case "order.reversed":       return onOrderReversed(data);
    case "order.status_updated": return onKitchenAdvance(data);
    default: console.warn("Tipo de evento Fire desconhecido", event.type);
  }
});

app.listen(8080);
1

Confirme rápido

Retorne 200 OK (ou qualquer 2xx) em menos de 30 segundos — idealmente em menos de 1 segundo. Confirme antes de fazer trabalho pesado.
2

Autentique a requisição

Valide a credencial de auth que o flow envia (Bearer token, API key ou OAuth2 access token). Rejeite qualquer requisição que não bata.
3

Deduplique

Procure event.id em um store de TTL curto (Redis com expiração de 24 horas funciona). Se já processou, pule.
4

Valide o payload

Verifique que event.type é o que você espera e que o bloco data tem os campos esperados. Retorne 400 para entradas malformadas para que não entrem na sua fila de retry pelo Fire.
5

Processe e persista

Aplique sua lógica de negócio, persista o resultado por event.id para rastreabilidade. Retorne 5xx para falhas transitórias (Fire faz retry); retorne 4xx para entrada ruim irrecuperável (Fire manda para dead letter).

​
Customizando o body

O body que o Fire entrega ao seu endpoint é o que o template do body do nó HTTP do seu flow renderizar. O template canônico (acima) é o default recomendado, mas você pode escrever qualquer template JSON válido que referencie o trigger context do runtime: 
{
  trigger: {
    event: { id, type, createdAt },
    data: V4Snapshot,         // payload específico do evento
  },
  execution: { id, ... },     // metadata de execução
  flow:      { id, name },    // identidade do seu flow
  queue:     { id, attempt, triggerEntityId },
}
O template canônico usa estes paths: 
{
  "event": {
    "id":        "{{trigger.event.id}}",
    "type":      "{{trigger.event.type}}",
    "createdAt": "{{trigger.event.createdAt}}"
  },
  "data": "{{trigger.data}}",
  "_meta": {
    "executionId":     "{{execution.id}}",
    "flowId":          "{{flow.id}}",
    "flowName":        "{{flow.name}}",
    "attempt":         "{{queue.attempt}}",
    "triggerEntityId": "{{queue.triggerEntityId}}"
  }
}
Você pode escrever outro template que omita _meta, achata data, renomeia chaves, envia só campos específicos, etc. Veja Integration Flows para a referência completa.

​
Próximo

Integration Flows

Como seu sistema assina eventos através de flows configurados no dashboard.

Entrega e retentativas

Política de retry, comportamento de dead-letter, idempotência e garantias de ordem.

order.completed

O evento mais comum — snapshot V4 completo do pedido.

order.invoiced

Autorização fiscal brasileira via seu provedor fiscal.