APIs de parceiro
Saúde de componentes
Batimento que um quiosque, uma tela KDS ou um caixa POS envia para informar que está vivo. O Fire infere a queda pela ausência do batimento.
POST
Um equipamento só pode informar que está vivo. Ninguém anuncia a própria morte: a queda é
inferida pela ausência do batimento. Por isso o contrato é um batimento periódico e não um alerta —
você faz POST neste endpoint a cada ciclo (a frota roda a 600 s) e o painel de disponibilidade
do Fire lê o silêncio.
A conta e o vendor são derivados da key, nunca do corpo. Não envie
1. Um
Tem que sobreviver a reinícios, atualizações e reinstalações. Um id que muda faz a frota parecer que
se renova sozinha e impede o uptime de estabilizar.
3. Obedecer ao
Cada 4. Enviar
A hora de emissão do equipamento, não a de chegada. O porquê está no campo acima: muda o que é
contado como downtime.
5. Combinar o vocabulário de
Não é preciso registrar nada antes. Um componente que o Fire não conhece é criado no seu
primeiro batimento e entra em período de teste: ele não é vigiado até ter reportado em 2
horas distintas. É aí que o erro de digitação morre: um
componentId errado reporta uma vez,
nunca volta e nunca chega a alertar.Autenticação
Este endpoint exige uma API key com escopocomponent-health:write e vínculo de vendor (conta +
vendor). Keys sem o escopo, ou sem vínculo de vendor, são rejeitadas com 403.
string
obrigatório
Sua API key do Fire com vínculo de vendor e escopo
component-health:write. Gere uma em
Developers → API Management.accountId.
Corpo da requisição
string
obrigatório
Que tipo de equipamento está batendo. Um de
kiosk, kds_station ou pos.string
obrigatório
Seu identificador do equipamento, de 1 a 120 caracteres. Precisa ser estável: tem que sobreviver
a reinícios, atualizações e reinstalações. Se mudar, para o Fire é um componente diferente: o
antigo para de bater e é baixado após 7 dias, e o novo começa sem histórico e volta ao período de
teste. Use o serial do equipamento, um id de instalação persistido em disco ou o id do terminal.
Nunca um nome editável pelo usuário (
Cozinha 1) nem um id regerado a cada boot.string
obrigatório
UUID da loja à qual o componente pertence. Validado contra suas lojas: precisa existir e ser da
conta da API key. É obrigatório porque um componente sem loja fica fora do cálculo de
disponibilidade, e uma loja com 3 totens onde um está mal configurado seria calculada sobre 2 —
dizendo “2 de 2, tudo certo” enquanto um está caído.
string
obrigatório
online ou degraded. Não existe down: um equipamento não pode se declarar morto, isso o
Fire infere pela ausência do batimento. degraded significa que o equipamento está vivo mas algo
de que ele precisa não está — e quem decide isso é o próprio equipamento, não o Fire.string
Timestamp ISO 8601 com offset do momento em que o equipamento emitiu o batimento, não de
quando ele chegou. Sem esse dado tudo é datado pelo momento em que a requisição tocou o servidor,
então um batimento atrasado pela rede que chega depois de a queda já ter sido declarada a alonga
artificialmente. Também serve para descartar batimentos fora de ordem: um
sentAt anterior ao
último processado é ignorado. É opcional, mas envie.integer
A cadência que o equipamento acredita ter, de 60 a 86400. É informativa: a cadência vigente é a
que o Fire devolve em
X-Heartbeat-Interval.string | null
Timestamp ISO 8601 com offset do momento em que o equipamento perdeu conectividade, informado ao
recuperá-la. Com isso a queda é datada quando de fato aconteceu e não quando ficamos sabendo: um
quiosque sem rede segue vendendo com sua fila offline, e sem esse campo lhe cobraríamos um downtime
que ele não teve.
string
Por que o equipamento não está
online, como código normalizado (1 a 60 caracteres,
snake_case, sem espaços). É o que torna analisável um detalhe que por projeto é livre — veja o
vocabulário comum mais abaixo.string
Versão do app do equipamento, de 1 a 40 caracteres. Tem campo próprio — em vez de viver dentro de
details — porque é o único dado universal aos três tipos, e “esta versão falha mais” é a
correlação mais comum de uma frota.object
Contexto livre. É guardado como veio: o Fire não interpreta nenhuma chave, deliberadamente,
para que uma release sua nunca quebre a ingestão. As chaves são por tipo de componente: uma
tela KDS não tem impressora nem pinpad, um caixa POS tem. Veja o contrato de chaves mais abaixo.
Resposta
Em caso de sucesso o endpoint devolve204 No Content, sem corpo. Um batimento não cria um
recurso que você vá consultar depois, e um aceite com corpo só somaria bytes a uma requisição que
cada equipamento faz a cada ciclo.
integer
Header de resposta com a cadência vigente, em segundos. Se ela diferir da que você está usando,
adote-a no próximo ciclo. O intervalo é configurável por equipamento do nosso lado; se os
equipamentos ignoram o header, esse controle é nosso apenas no papel — mudaríamos o número no banco
e a frota seguiria no ritmo antigo até a sua próxima release.
O que precisamos de cada equipamento
São cinco coisas. Nenhuma é opcional na prática: sem elas o sistema funciona, mas com dados piores, e em dois casos ele mente para o lado do otimismo, que é o pior lado para um monitor.1. Um componentId estável
Tem que sobreviver a reinícios, atualizações e reinstalações. Um id que muda faz a frota parecer que
se renova sozinha e impede o uptime de estabilizar.
2. Jitter na inicialização
Não bater no mesmo segundo que todos os outros. Some um deslocamento aleatório de até um intervalo inteiro antes do primeiro batimento, e mantenha-o. Dez mil equipamentos com a mesma cadência, todos reiniciados após uma queda de energia regional, batem sincronizados para sempre — o problema não é a carga média, é aquele segundo exato.3. Obedecer ao X-Heartbeat-Interval
Cada 204 traz a cadência vigente. Adote-a no próximo ciclo. A largura das barras do painel deriva
desse valor, então um equipamento que o ignora faz a tela afirmar uma precisão que o dado não tem.
4. Enviar sentAt
A hora de emissão do equipamento, não a de chegada. O porquê está no campo acima: muda o que é
contado como downtime.
5. Combinar o vocabulário de degradedReason — e o que um KDS reporta
details é livre de propósito: o equipamento sabe que hardware tem, o Fire não. Mas para responder
“o que falha mais?” os motivos precisam de um vocabulário comum.
Chaves de
details por tipo de componente:
kiosk→printer,pinpad,queuedOrderspos→printer,pinpadkds_station→ ainda a combinar com o time de KDS. Uma tela não tem periféricos de venda; os candidatos são a conexão com o próprio backend e os pedidos não despachados na fila. Até isso ser fechado, não assuma nenhuma chave aqui.
Como o Fire lê isso
- Cadastro automático e período de teste. O primeiro batimento cria o componente. Ele não é vigiado até ter reportado em 2 horas distintas. Um id digitado errado e um equipamento que foi instalado e morreu na hora são idênticos: nenhum alerta. Os que reportam uma única vez ficam listados para alguém olhar, sem sujar o painel.
- A queda é declarada após 2 intervalos perdidos, não no primeiro. Um batimento perdido na rede não é uma queda.
- Baixa automática em 7 dias sem bater: o componente sai sozinho do painel. Se voltar a ligar, reaparece com todo o seu histórico.
- Fora do horário da loja não conta. Os trechos são recortados pelo dia operacional real daquela loja — quando ela de fato abriu e fechou, não o horário declarado. Um totem desligado à noite não soma downtime.
Erros
Uma loja de outra conta volta como
400, não como 404: do ponto de vista do contrato é um
corpo inválido, e um 404 confirmaria a uma key que aquele uuid existe na conta de outro.
Sobre repetir a chamada: um batimento perdido não se recupera. Reenviar o de dez minutos atrás
não acrescenta nada, e com um sentAt correto ele é descartado por estar fora de ordem. Diante de um
5xx, espere o próximo ciclo — nunca acumule batimentos antigos.
Relacionado
Status do pedido KDS
O outro endpoint que seus equipamentos de cozinha chamam — ciclo de vida do pedido em vez de
disponibilidade.
Introdução
URLs base, API keys, escopos e formato de erros.