Resumen de eventos

Fire emite eventos cada vez que ocurre una transición de negocio relevante — una orden se completa, una orden se cancela, un documento fiscal es autorizado por la autoridad tributaria, la cocina avanza un pedido. Cada evento se entrega a tu endpoint por un Integration Flow que configuras en el dashboard de Fire.

Fire emite cinco tipos de evento de orden hoy: order.completed, order.cancelled, order.invoiced, order.reversed y order.status_updated, más el evento programado store.business_day_closed al cierre del día.

Fire es la fuente de verdad del ciclo de vida

Una orden puede nacer en cualquier canal — POS, kiosk, app, agregador — pero desde que entra, Fire la normaliza y toma control de su ciclo de vida completo. Todo lo que pasa alrededor de esa orden se centraliza en Fire: el pago la completa, la cocina la avanza, el proveedor fiscal la factura o la reversa, y el cierre del día la consolida. Cada uno de esos hitos sale hacia tus sistemas como un evento con el mismo snapshot canónico de la orden. Esa centralización funciona en ambas direcciones: los sistemas externos no escriben estado por su cuenta — reportan a Fire por webhooks entrantes, y cada reporte debe referenciar un evento que Fire emitió (el eventId del envelope que recibiste). Fire valida esa referencia antes de aceptar el reporte; un callback que no apunte a un evento emitido por Fire para esa orden se rechaza con 400. Así, la línea de tiempo de una orden tiene una sola fuente de verdad y nunca se bifurca.

El diagrama de secuencia muestra el ciclo de vida en el tiempo — incluyendo los dos round-trips donde el proveedor fiscal y el KDS resuelven y reportan de vuelta a Fire. El diagrama estructural lo resume en quién habla con quién.

Ciclo de vida en el tiempo

Quién habla con quién

Fíjate en los dos circuitos de ida y vuelta: Fire le avisa al facturador (②), el facturador resuelve con la autoridad (③) y le responde a Fire por el callback (④) — recién entonces Fire emite order.invoiced / order.reversed (⑤). Lo mismo con cocina: Fire despacha la orden al KDS (⑥), el KDS reporta el avance a Fire (⑦) y Fire emite order.status_updated (⑧). Nada se entera “por su cuenta”: todo pasa por Fire y sale de Fire — incluido el store.business_day_closed (⑨) al cierre del día.

Una acción, un evento

Cada acción de negocio es su propio evento con su propio event.id — order.invoiced para una autorización fiscal, order.reversed para una cancelación, cada order.status_updated para una transición de cocina. Nunca se colapsan: autorizar una orden y luego cancelarla son dos eventos distintos con dos ids distintos. Esto define cómo Fire matchea los reportes inbound que disparan esas acciones:

Un reporte referencia el evento de esa acción. Cuando le reportás una cancelación a Fire, ecoa el event.id del evento de cancelación — no el de la autorización. Cada (orderId, eventId) se ingresa exactamente una vez.
Reenviar el mismo reporte es seguro. El mismo (orderId, eventId) con el mismo tipo es un replay idempotente — Fire devuelve el registro existente y no procesa nada dos veces (202, duplicate: true). Podés regenerar tu propio id de proveedor libremente.
No podés colgar una acción del evento de otra. Reportar una cancelación reusando el eventId de la autorización se rechaza con 409 — aceptarlo te diría que la cancelación tuvo éxito mientras Fire nunca canceló. Cada acción debe referenciar su propio evento emitido por Fire.

Una excepción — el recorrido de cocina. El KDS reporta preparing → ready → dispatched contra un eventId (el del dispatch), distinguidos por eventType — así que el mismo eventId con un type distinto es un paso nuevo, no un conflicto. La regla de arriba (un eventId por acción) aplica para fiscal (una acción = un evento); el recorrido del KDS comparte un evento de dispatch entre sus pasos. En ambos casos, un reporte debe referenciar un evento emitido por Fire, y la misma (orderId, eventId, eventType) se ingresa una vez.

Ver el callback fiscal y el endpoint KDS para las matrices completas de comportamiento inbound.

Cómo funciona

Cuando ocurre un evento de negocio relevante, Fire lo despacha a través de un flow que configuraste en el dashboard. El flow renderiza un body de petición HTTP y la hace POST a tu endpoint. Tú confirmas con una respuesta 2xx. La mecánica interna (queues, reintentos, resolución de templates) está en Entrega y reintentos. El modelo de configuración de flows está en Integration Flows.

Qué recibe tu endpoint

Cuando dispara un flow, tu endpoint recibe un POST HTTP. El body tiene tres campos top-level — event, data y _meta:

{
  "event": {
    "id": "0d6e8a1c-1e7a-4b4f-8a3a-74ab0e9a9b21",
    "type": "order.completed",
    "createdAt": "2026-05-06T13:42:11.812Z"
  },
  "data": {
    /* snapshot V4 específico del evento — ver cada referencia */
  },
  "_meta": {
    "executionId":     "0d6e8a1c-1e7a-4b4f-8a3a-74ab0e9a9b21",
    "flowId":          "9a2b3c4d-7e8f-4a1b-9c2d-3e4f5a6b7c8d",
    "flowName":        "Integración ERP",
    "attempt":         "1",
    "triggerEntityId": "f1e2d3c4-b5a6-4789-9012-3456789abcde"
  }
}

`event`

object

Identifica esta entrega.

Mostrar event

string

Identificador único de esta entrega (el ID de ejecución del flow). Úsalo como llave de idempotencia — Fire puede entregar el mismo evento más de una vez en reintentos.

string

Tipo de evento. Uno de: order.completed, order.cancelled, order.invoiced, order.reversed, order.status_updated, store.business_day_closed.

string

Timestamp ISO 8601 UTC del momento en que el evento se materializó dentro de Fire (no el momento en que llegó a tu endpoint).

`data`

object

Payload específico del evento. La forma varía por evento:

Evento	Qué hay en `data`
`order.completed`	Snapshot V4 de la orden — order, store (con `storeFiscalConfig` opcional), customer, payments, fulfillment, KDS, lines
`order.cancelled`	Snapshot V4 + bloque `cancellation` de auditoría
`order.invoiced`	Snapshot V4 con `order.fiscal` (chave, protocolo, número…) + `storeFiscalConfig`
`order.reversed`	Snapshot V4 + `xmlCancelamento` + `sefazCancellation`
`order.status_updated`	Snapshot V4 + bloque `kitchen` (status, previousStatus, history del recorrido)

`_meta`

object

Trazabilidad a nivel de ejecución. Loguéalo junto al evento para debuggear problemas de entrega y correlacionar reintentos.

Mostrar _meta

string

ID interno de ejecución del flow. Espeja event.id.

string

UUID del Integration Flow que produjo esta entrega.

string

Nombre legible del flow (tal como está en el dashboard).

string

Número de intento de entrega, empezando en "1". Incrementa con cada reintento.

string

ID de la entidad de negocio que originó el evento (típicamente el UUID de la orden, mismo que data.orderId).

Las claves event, data y _meta vienen del template canónico de body que trae el dashboard de Fire. Son una convención, no un envelope Fire fijo — si el nodo HTTP de tu flow define otro template, la forma del wire cambia. Ver Customizando el body más abajo.

Entrega HTTP por defecto

Campo	Default
Método	`POST` (configurable por flow)
`Content-Type`	`application/json` (lo setean los headers del nodo HTTP de tu flow)
Timeout	30 segundos (configurable, 1–60s)
Auth	None / `Bearer` / `x-api-key` / OAuth2 client credentials — se elige por flow
Firma	HMAC-SHA256 opcional (nodo Webhook) — `X-Fire-Signature` + `X-Fire-Timestamp`
Reintentos	Hasta 5 con backoff exponencial
Dead letter	Después de los reintentos, la ejecución cae en `flow_dead_letter`

Las peticiones salientes pueden ir firmadas con HMAC si tu flow usa el nodo Webhook: Fire agrega X-Fire-Signature (v1=hex(HMAC-SHA256(secret, "{timestamp}.{body}"))) y X-Fire-Timestamp (Unix seconds). La firma es opcional y complementa al auth de transporte (Bearer / API key / OAuth2). Detalle y verificación en el nodo Webhook firmado.

Recibiendo eventos

import express from "express";

const app = express();
const seen = new Map(); // reemplaza por Redis / DB en producción

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. Confirma primero para liberar la conexión de Fire
  res.status(200).end();

  // 2. Deduplica por event.id (el ID de ejecución del flow)
  if (seen.has(event.id)) return;
  seen.set(event.id, Date.now());

  // 3. Loggea _meta para trazabilidad — invaluable al debuggear
  console.log("Evento Fire", { eventId: event.id, type: event.type, _meta });

  // 4. Despacha 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 desconocido", event.type);
  }
});

app.listen(8080);

Confirma rápido

Devuelve 200 OK (o cualquier 2xx) en menos de 30 segundos — idealmente bajo 1 segundo. Confirma antes de hacer trabajo pesado.

Autentica la petición

Valida la credencial de auth que envía el flow (Bearer token, API key u OAuth2 access token). Rechaza cualquier petición que no haga match.

Deduplica

Busca event.id en un store de TTL corto (Redis con expiración de 24 horas funciona). Si ya lo procesaste, salta.

Valida el payload

Chequea que event.type sea lo que esperas y que el bloque data tenga los campos esperados. Devuelve 400 ante inputs malformados para que no entren en tu cola de retry desde Fire.

Procesa y persiste

Aplica tu lógica de negocio, persiste el resultado por event.id para trazabilidad. Devuelve 5xx para errores transitorios (Fire reintenta); devuelve 4xx para input malo no recuperable (Fire lo manda a dead letter).

Customizando el body

El body que Fire entrega a tu endpoint es lo que renderice el template del body del nodo HTTP de tu flow. El template canónico (arriba) es el default recomendado, pero puedes escribir cualquier template JSON válido que referencie el trigger context del runtime:

{
  trigger: {
    event: { id, type, createdAt },
    data: V4Snapshot,         // payload específico del evento
  },
  execution: { id, ... },     // metadata de ejecución
  flow:      { id, name },    // identidad de tu flow
  queue:     { id, attempt, triggerEntityId },
}

El template canónico usa estos 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}}"
  }
}

Puedes escribir otro template que omita _meta, aplane data, renombre claves, envíe solo campos específicos, etc. Consulta Integration Flows para la referencia completa.

Integration Flows

Cómo tu sistema se suscribe a eventos a través de flows configurados en el dashboard.

Entrega y reintentos

Política de retry, comportamiento de dead-letter, idempotencia y garantías de orden.

order.completed

El evento más común — snapshot V4 completo de la orden.

order.invoiced

Autorización fiscal brasileña vía tu proveedor fiscal.

Conceptos

Catálogo

Resumen de eventos

Fire es la fuente de verdad del ciclo de vida

Ciclo de vida en el tiempo

Quién habla con quién

Una acción, un evento

Cómo funciona

Qué recibe tu endpoint

`event`

`data`

`_meta`

Entrega HTTP por defecto

Recibiendo eventos

Customizando el body

Próximo

Integration Flows

Entrega y reintentos

order.completed

order.invoiced

​Fire es la fuente de verdad del ciclo de vida

​Ciclo de vida en el tiempo

​Quién habla con quién

​Una acción, un evento

​Cómo funciona

​Qué recibe tu endpoint

​event

​data

​_meta

​Entrega HTTP por defecto

​Recibiendo eventos

​Customizando el body

​Próximo

Integration Flows

Entrega y reintentos

order.completed

order.invoiced

Fire es la fuente de verdad del ciclo de vida

Ciclo de vida en el tiempo

Quién habla con quién

Una acción, un evento

Cómo funciona

Qué recibe tu endpoint

`event`

`data`

`_meta`

Entrega HTTP por defecto

Recibiendo eventos

Customizando el body

Próximo