Estado de orden KDS
APIs de partner
Estado de orden KDS
Endpoint entrante al que tu KDS hace POST cuando una orden de cocina cambia de estado (preparando, lista, despachada, cancelada). Fire registra el evento, lo deduplica y aplica anti-regresión para que el estado de la orden nunca retroceda.
POST
Estado de orden KDS
Este endpoint es entrante — tu Sistema de Pantallas de Cocina (KDS) le hace POST cada vez que una orden avanza en la cocina: la cocina empezó a prepararla, quedó lista para entrega, fue despachada (entregada / retirada), o fue cancelada. Fire autentica la solicitud, la correlaciona con la orden, aplica idempotencia y una compuerta anti-regresión, y registra el evento en su log de eventos KDS para observabilidad.
Se devuelve
Este endpoint es asíncrono. Fire autentica, corre el guard de source-of-truth + tenancy, deduplica y encola el evento — luego responde
202 Accepted con un webhookEventId (típicamente en menos de 100 ms). El evento se registra un instante después en un worker en segundo plano (normalmente en ~2 segundos). Para verificar el resultado, consultá GET /v1/webhooks/events/{webhookEventId}. Los problemas corregibles por el cliente (payload inválido, eventId equivocado, tenant equivocado) se rechazan síncronamente con 4xx antes del 202.Un evento de dispatch, varios reportes de estado. A diferencia del callback fiscal — donde cada acción lleva su propio
eventId — el KDS reporta todo el recorrido (preparing → ready → dispatched) contra un eventId: el que Fire emitió al despachar la orden a tu device. Se distinguen por eventType, no por eventId. Ver Idempotencia y el recorrido.Tipos de evento
El ciclo de vida del KDS tiene un orden estricto:
Los valores son minúscula, con punto (
order.preparing, no ORDER_PREPARING).
order.cancelled es el estado terminal. Envialo cuando tu KDS procesa la cancelación de una orden (iniciada desde Fire). Una vez registrado, cualquier evento posterior (preparing, ready, dispatched) se ignora como no-avanzante — la orden queda en cancelled permanentemente.Autenticación
Este endpoint requiere una API key vendor-scoped con el scopewebhooks:kds (binding de cuenta + vendor). Fire valida que la orden pertenezca a esa cuenta y vendor. Las keys sin el scope, o sin binding de vendor, se rechazan con 403 Forbidden.
string
requerido
Tu API key vendor-scoped de Fire con scope
webhooks:kds. Generá una desde Developers → Gestión de API para la cuenta/vendor cuyas órdenes reportará esta key.string
Bearer <token> opcional — aceptado como alternativa legacy a x-api-key. Enviá uno u otro.Cuerpo de la solicitud
string
requerido
El evento de ciclo de vida del KDS.
order.preparing, order.ready, order.dispatched u order.cancelled (minúscula, con punto). Ver Tipos de evento.string
requerido
El id propio de tu KDS para esta entrega. Se guarda para auditoría/forense — no es la llave de idempotencia. Fire deduplica por
(orderId, eventId, eventType), así que podés enviar un providerEventId nuevo en cada reintento. Usá el id de evento nativo de tu KDS si lo tenés; si no, un UUID.string
requerido
Timestamp ISO 8601 UTC de cuándo ocurrió el evento en el KDS — no cuándo se envió.
string
requerido
UUID de la orden en Fire. Coincide con
data.orderId de los eventos de orden. Fire correlaciona el evento con esta orden; debe existir previamente.string
requerido
UUID de correlación — el
event.id del envelope que Fire emitió al despachar la orden a tu device. Ecoalo exacto; nunca lo inventes.- Chequeo de fuente de verdad. Un
eventIdque no referencie un evento de Fire para esa orden se rechaza con400antes del202. - Un eventId para todo el recorrido. Enviá el mismo
eventIdparapreparing,readyydispatchedde ese dispatch — se distinguen poreventType. (Cada dispatch a un device distinto lleva su propioeventId, así que dos devices nunca colisionan.)
string
Estación del KDS de origen, opcional (ej.
Cocina caliente, Despacho 1). Se guarda para observabilidad.object
Bolsa libre opcional de campos extra. Se guarda tal cual, sin validar.
Ejemplos
Los tres reportes del mismo dispatch comparten uneventId (el del dispatch) y difieren solo en eventType y providerEventId:
order.preparing
order.ready
order.dispatched
order.cancelled
Respuesta
En éxito el endpoint responde202 Accepted — el evento fue autenticado, validado, deduplicado y encolado. Un 202 no significa que el evento ya se registró; eso ocurre de forma asíncrona. Usá el endpoint de estado para confirmar.
El body trae dos ids distintos: eventId es el id que vos enviaste (echo), webhookEventId es el id de Fire para el registro encolado. Misma forma que el callback fiscal.
boolean
Siempre
true cuando la solicitud fue aceptada y encolada.boolean
true cuando esta tripla exacta (orderId, eventId, eventType) ya se ingresó — se devuelve el registro existente y no se re-encola nada. false para un reporte nuevo (incluido un eventType distinto del mismo dispatch — eso es un paso nuevo, no un duplicado).string
Echo del
eventId que enviaste (el event.id del dispatch).string
El id de Fire para el registro encolado. Pasalo a
GET /v1/webhooks/events/{webhookEventId} para consultar el resultado. En un duplicado es el mismo id que se devolvió la primera vez.string
Estado actual en la cola —
queued → processing → processed (y retry / failed / dead / ignored).string
Timestamp ISO 8601 UTC de cuándo Fire recibió por primera vez este reporte. Estable entre reintentos.
string
Resumen legible.
Verificar el resultado
Como el procesamiento es asíncrono, el202 solo confirma que el evento fue encolado. Para ver si se registró, consultá el endpoint de estado con el webhookEventId que devolvió el 202:
string
Ciclo de vida de la cola:
queued → processing → processed (listo) · failed / dead (se rindió tras reintentos) · retry (esperando el próximo intento) · ignored (manejado, sin acción — ej. un duplicado o un evento no-avanzante).number
Intentos de procesamiento hasta ahora.
object | null
En éxito, el resultado del worker — ej.
{ "kind": "recorded" } (avanzó la orden) o { "kind": "ignored" } (no-avanzante).object | null
{ "message": "…" } cuando el último intento falló; null si no.404 para ids desconocidos — o ids de otro tenant — sin filtrar existencia. Autenticá con la misma key webhooks:kds que usaste para el evento.
Idempotencia y el recorrido
Fire deduplica por la tripla(orderId, eventId, eventType) — no por providerEventId (que podés regenerar libremente). Esto es lo que hace funcionar el recorrido:
Esta es la diferencia clave con el callback fiscal. Allá, un
eventId lleva exactamente una acción, así que reusarlo para otro eventType es un conflicto (409). Acá, un eventId de dispatch lleva legítimamente todo el recorrido (preparing → ready → dispatched) — el eventType es lo que distingue los pasos. Devices distintos reciben eventIds de dispatch distintos, así que sus reportes nunca colisionan.Anti-regresión
El estado de la orden nunca debe retroceder. Fire rastrea la etapa máxima alcanzada por la orden y compara cada evento entrante contra ella:- Un evento que avanza la orden (ej.
order.readydespués deorder.preparing) se registra como el nuevo estado. - Un evento que no avanza — una regresión o una repetición — igual se registra para observabilidad, marcado como no-avanzante, y no retrocede la orden.
order.cancelledtiene rank 4: avanza sobre cualquier estado previo. Una vez registrado, es irreversible — cualquier evento posterior (inclusoorder.dispatched) se trata como no-avanzante.
Relacionado
Inyectar orden
El endpoint de inyección que crea la orden que referencia este evento.
Callback fiscal
El webhook entrante hermano — mismo modelo async + idempotencia + correlación.
Autenticación
Cómo funcionan las API keys, scopes y el binding de partner y vendor.

