Status do pedido KDS
APIs de parceiro
Status do pedido KDS
Endpoint de entrada para o qual seu KDS faz POST quando um pedido da cozinha muda de status (preparando, pronto, despachado). O Fire registra o evento, deduplica e aplica anti-regressão para que o status do pedido nunca retroceda.
POST
Status do pedido KDS
Este endpoint é de entrada — seu Sistema de Tela de Cozinha (KDS) faz POST nele sempre que um pedido avança na cozinha: a cozinha começou a prepará-lo, ficou pronto para entrega, ou foi despachado (entregue / retirado). O Fire autentica a requisição, correlaciona com o pedido, aplica idempotência e um guard anti-regressão, e registra o evento no seu log de eventos KDS para observabilidade.
Um
Este endpoint é assíncrono. O Fire autentica, roda o guard de source-of-truth + tenancy, deduplica e enfileira o evento — então responde
202 Accepted com um webhookEventId (tipicamente em menos de 100 ms). O evento é registrado um instante depois por um worker em segundo plano (normalmente em ~2 segundos). Para verificar o resultado, consulte GET /v1/webhooks/events/{webhookEventId}. Problemas corrigíveis pelo cliente (payload inválido, eventId errado, tenant errado) são rejeitados sincronamente com 4xx antes do 202.Um evento de dispatch, vários reportes de status. Diferente do callback fiscal — onde cada ação carrega seu próprio
eventId — o KDS reporta toda a jornada (preparing → ready → dispatched) contra um eventId: o que o Fire emitiu ao despachar o pedido ao seu device. São distinguidos por eventType, não por eventId. Veja Idempotência e a jornada.Tipos de evento
O ciclo de vida do KDS tem uma ordem estrita — um pedido é preparado antes de ficar pronto, e fica pronto antes de ser despachado:
Os valores são minúsculos, com ponto (
order.preparing, não ORDER_PREPARING).
Autenticação
Este endpoint requer uma API key vendor-scoped com o escopowebhooks:kds (binding de conta + vendor). O Fire valida que o pedido pertença a essa conta e vendor. Keys sem o escopo, ou sem binding de vendor, são rejeitadas com 403 Forbidden.
string
obrigatório
Sua API key vendor-scoped do Fire com escopo
webhooks:kds. Gere uma em Developers → Gestão de API para a conta/vendor cujos pedidos esta key vai reportar.string
Bearer <token> opcional — aceito como alternativa legada ao x-api-key. Envie um ou outro.Corpo da requisição
string
obrigatório
O evento de ciclo de vida do KDS.
order.preparing, order.ready ou order.dispatched (minúsculo, com ponto).string
obrigatório
O id próprio do seu KDS para esta entrega. Armazenado para auditoria/forense — não é a chave de idempotência. O Fire deduplica por
(orderId, eventId, eventType), então você pode enviar um providerEventId novo a cada retentativa. Use o id de evento nativo do seu KDS se tiver; senão, um UUID.string
obrigatório
Timestamp ISO 8601 UTC de quando o evento ocorreu no KDS — não quando foi enviado.
string
obrigatório
UUID do pedido no Fire. Corresponde a
data.orderId nos eventos de pedido. O Fire correlaciona o evento com este pedido; ele deve existir previamente.string
obrigatório
UUID de correlação — o
event.id do envelope que o Fire emitiu ao despachar o pedido ao seu device. Ecoe-o exato; nunca o invente.- Verificação de fonte da verdade. Um
eventIdque não referencie um evento do Fire para esse pedido é rejeitado com400antes do202. - Um eventId para toda a jornada. Envie o mesmo
eventIdparapreparing,readyedispatcheddesse dispatch — são distinguidos poreventType. (Cada dispatch a um device diferente carrega seu próprioeventId, então dois devices nunca colidem.)
string
Estação do KDS de origem, opcional (ex.
Cozinha quente, Despacho 1). Armazenada para observabilidade.object
Saco livre opcional de campos extras. Armazenado como está, sem validação.
Exemplos
Os três reportes do mesmo dispatch compartilham umeventId (o do dispatch) e diferem apenas no eventType e providerEventId:
order.preparing
order.ready
order.dispatched
Resposta
Em caso de sucesso o endpoint responde202 Accepted — o evento foi autenticado, validado, deduplicado e enfileirado. Um 202 não significa que o evento já foi registrado; isso acontece de forma assíncrona. Use o endpoint de status para confirmar.
O body traz dois ids distintos: eventId é o id que você enviou (echo), webhookEventId é o id do Fire para o registro enfileirado. Mesma forma que o callback fiscal.
boolean
Sempre
true quando a requisição foi aceita e enfileirada.boolean
true quando esta tripla exata (orderId, eventId, eventType) já foi ingerida — o registro existente é retornado e nada é re-enfileirado. false para um reporte novo (incluindo um eventType diferente do mesmo dispatch — isso é um passo novo, não uma duplicata).string
Echo do
eventId que você enviou (o event.id do dispatch).string
O id do Fire para o registro enfileirado. Passe-o para
GET /v1/webhooks/events/{webhookEventId} para consultar o resultado. Em uma duplicata é o mesmo id retornado na primeira vez.string
Status atual na fila —
queued → processing → processed (e retry / failed / dead / ignored).string
Timestamp ISO 8601 UTC de quando o Fire recebeu pela primeira vez este reporte. Estável entre retentativas.
string
Resumo legível.
Verificar o resultado
Como o processamento é assíncrono, o202 apenas confirma que o evento foi enfileirado. Para ver se foi registrado, consulte o endpoint de status com o webhookEventId retornado pelo 202:
string
Ciclo de vida da fila:
queued → processing → processed (concluído) · failed / dead (desistiu após retentativas) · retry (aguardando a próxima tentativa) · ignored (tratado, sem ação — ex. um duplicado ou um evento não-avançante).number
Tentativas de processamento até agora.
object | null
Em caso de sucesso, o resultado do worker — ex.
{ "kind": "recorded" } (avançou o pedido) ou { "kind": "ignored" } (não-avançante).object | null
{ "message": "…" } quando a última tentativa falhou; null caso contrário.404 é retornado para ids desconhecidos — ou ids de outro tenant — sem vazar existência. Autentique com a mesma key webhooks:kds que usou para o evento.
Idempotência e a jornada
O Fire deduplica pela tripla(orderId, eventId, eventType) — não por providerEventId (que você pode regenerar livremente). É isso que faz a jornada funcionar:
Esta é a diferença chave em relação ao callback fiscal. Lá, um
eventId carrega exatamente uma ação, então reusá-lo para outro eventType é um conflito (409). Aqui, um eventId de dispatch carrega legitimamente toda a jornada (preparing → ready → dispatched) — o eventType é o que distingue os passos. Devices diferentes recebem eventIds de dispatch diferentes, então seus reportes nunca colidem.Anti-regressão
O status do pedido nunca deve retroceder. O Fire rastreia o estágio máximo alcançado pelo pedido (order.dispatched > order.ready > order.preparing) e compara cada evento de entrada com ele:
- Um evento que avança o pedido (ex.
order.readydepois deorder.preparing) é registrado como o novo status. - Um evento que não avança — uma regressão (ex.
order.preparingchegando depois deorder.ready) ou uma repetição do mesmo status — ainda é registrado para observabilidade, mas marcado como não-avançante com um motivo, e não retrocede o pedido.
Relacionado
Injetar pedido
O endpoint de injeção que cria o pedido que este evento referencia.
Callback fiscal
O webhook de entrada irmão — mesmo modelo async + idempotência + correlação.
Autenticação
Como funcionam as API keys, escopos e o binding de parceiro e vendor.

