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). 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, o fue despachada (entregada / retirada). 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.
Los valores son minúscula, con punto (
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 — una orden se prepara antes de estar lista, y está lista antes de ser despachada:eventType | Significado | Rank |
|---|---|---|
order.preparing | La cocina comenzó a preparar la orden | 1 |
order.ready | La orden está preparada y lista para entrega / retiro | 2 |
order.dispatched | La orden salió de la cocina (entregada o retirada) — terminal | 3 |
order.preparing, no ORDER_PREPARING).
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.
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.Bearer <token> opcional — aceptado como alternativa legacy a x-api-key. Enviá uno u otro.Cuerpo de la solicitud
El evento de ciclo de vida del KDS.
order.preparing, order.ready u order.dispatched (minúscula, con punto).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.Timestamp ISO 8601 UTC de cuándo ocurrió el evento en el KDS — no cuándo se envió.
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.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.)
Estación del KDS de origen, opcional (ej.
Cocina caliente, Despacho 1). Se guarda para observabilidad.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
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.
Siempre
true cuando la solicitud fue aceptada y encolada.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).Echo del
eventId que enviaste (el event.id del dispatch).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.Estado actual en la cola —
queued → processing → processed (y retry / failed / dead / ignored).Timestamp ISO 8601 UTC de cuándo Fire recibió por primera vez este reporte. Estable entre reintentos.
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:
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).Intentos de procesamiento hasta ahora.
En éxito, el resultado del worker — ej.
{ "kind": "recorded" } (avanzó la orden) o { "kind": "ignored" } (no-avanzante).{ "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:
| Escenario | Resultado |
|---|---|
preparing, luego ready, luego dispatched — mismo eventId, distinto eventType | cada uno es un paso nuevo → 202 duplicate:false. El mismo eventId es esperado, no un conflicto |
El mismo reporte reenviado — misma (orderId, eventId, eventType) | 202 duplicate:true — registro existente devuelto, no reprocesado |
eventId no emitido por Fire para ese orderId | 400 |
| Orden/evento fuera de la cuenta + vendor de tu API key | 403 |
| Auth store momentáneamente inalcanzable | 503 — transitorio, reintentá |
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 (order.dispatched > order.ready > order.preparing) 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 (ej.
order.preparingque llega después deorder.ready) o una repetición del mismo estado — igual se registra para observabilidad, pero marcado como no-avanzante con un motivo, y no retrocede la orden.
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.