Skip to main content
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.
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 (preparingreadydispatched) 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 escopo webhooks: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 eventId que não referencie um evento do Fire para esse pedido é rejeitado com 400 antes do 202.
  • Um eventId para toda a jornada. Envie o mesmo eventId para preparing, ready e dispatched desse dispatch — são distinguidos por eventType. (Cada dispatch a um device diferente carrega seu próprio eventId, 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 um eventId (o do dispatch) e diferem apenas no eventType e providerEventId:
order.preparing
order.ready
order.dispatched

Resposta

Em caso de sucesso o endpoint responde 202 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 — queuedprocessingprocessed (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, o 202 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: queuedprocessingprocessed (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.
Um 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 (preparingreadydispatched) — 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.ready depois de order.preparing) é registrado como o novo status.
  • Um evento que não avança — uma regressão (ex. order.preparing chegando depois de order.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.
Isso torna o endpoint seguro contra entregas fora de ordem ou atrasadas: envie os eventos em qualquer ordem e o Fire mantém o pedido no seu estágio mais avançado.

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.