Saltar al contenido principal
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

​
event
object
Identifica esta entrega.

​
data

​
data
object
Payload específico del evento. La forma varía por evento:
EventoQué hay en data
order.completedSnapshot V4 de la orden — order, store (con storeFiscalConfig opcional), customer, payments, fulfillment, KDS, lines
order.cancelledSnapshot V4 + bloque cancellation de auditoría
order.invoicedSnapshot V4 con order.fiscal (chave, protocolo, número…) + storeFiscalConfig
order.reversedSnapshot V4 + xmlCancelamento + sefazCancellation
order.status_updatedSnapshot V4 + bloque kitchen (status, previousStatus, history del recorrido)

​
_meta

​
_meta
object
Trazabilidad a nivel de ejecución. Loguéalo junto al evento para debuggear problemas de entrega y correlacionar reintentos.
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

CampoDefault
MétodoPOST (configurable por flow)
Content-Typeapplication/json (lo setean los headers del nodo HTTP de tu flow)
Timeout30 segundos (configurable, 1–60s)
AuthNone / Bearer / x-api-key / OAuth2 client credentials — se elige por flow
FirmaHMAC-SHA256 opcional (nodo Webhook) — X-Fire-Signature + X-Fire-Timestamp
ReintentosHasta 5 con backoff exponencial
Dead letterDespué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);
1

Confirma rápido

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

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.
3

Deduplica

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

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.
5

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.

​
Próximo

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.