T2Mark Docs
Painel
Docs / API Reference / POST /api/heartbeat

POST /api/heartbeat

POST /api/heartbeat

Envia um sinal de “estou vivo” para o servidor. Marca a máquina como “Online” no painel. Requer autenticação via X-API-Key.

Quando é Chamado

Agente rodando continuamente:

1. A cada ~1 segundo (ou quando há evento)
2. Diz ao servidor: "Estou aqui"
3. Servidor marca timestamp: "último visto agora"
4. No painel, máquina mostra: "Online"

Requisição

curl -X POST https://t2mark.setor9.net/api/heartbeat \
  -H "X-API-Key: ak_5f1b3c8e9d2a4b6c7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b" \
  -H "Content-Type: application/json" \
  -d '{
    "timestamp": "2026-05-05T14:30:00Z",
    "status": "running",
    "currentUser": "joao.silva",
    "policyVersion": 2
  }'

Parâmetros (todos opcionais)

Campo Tipo Descrição
timestamp string Data/hora do agente (ISO 8601)
status string "running" ou "idle"
currentUser string Usuário logado na máquina
policyVersion integer Versão de política atual

Nota: Você pode enviar um POST vazio também:

curl -X POST https://t2mark.setor9.net/api/heartbeat \
  -H "X-API-Key: ak_5f1b3c8e..." \
  -H "Content-Type: application/json" \
  -d '{}'

Resposta — 200 OK

{
  "status": "acknowledged",
  "serverTime": "2026-05-05T14:30:00Z",
  "message": "Heartbeat received"
}

Campos

Campo Tipo Significado
status string "acknowledged" = recebido
serverTime string Hora do servidor (sincronização)
message string Mensagem descritiva

O Que o Servidor Faz

Recebe heartbeat da máquina:
  1. Valida ApiKey
  2. Encontra máquina no banco
  3. Atualiza: "last_heartbeat = agora"
  4. Marca status: "online"
  5. No painel, máquina mostra status 🟢 verde

Monitoramento no Painel

Status das máquinas:

Status Significado Heartbeat
🟢 Online Agente respondendo < 1 minuto atrás
🟡 Inativo Sem contato 1-5 minutos atrás
🔴 Offline Sem contato há horas > 5 minutos atrás

Exemplo:

Máquina: PC-VENDAS-001
Status: 🟢 Online
Última sincronização: Agora (35 segundos atrás)
Política: Restrito v2

Frequência Recomendada

Intervalo Propósito
1 segundo Ideal (agente sabe que está vivo)
5 segundos Aceitável
10 segundos Funcionará, mas menos responsivo
30+ segundos Não recomendado (status fica impreciso)

Padrão T2Mark: 1 segundo

Timings

Operação Tempo
POST /api/heartbeat → Resposta 50-200 ms
Atualização no painel 5-10 segundos
Status muda para 🟡 Inativo > 1 minuto sem heartbeat
Status muda para 🔴 Offline > 5 minutos sem heartbeat

Falhas e Retry

Se heartbeat falhar:

Tentativa 1: POST /api/heartbeat → Falha (timeout)
Aguarda: 5 segundos
Tentativa 2: POST /api/heartbeat → Falha (404)
Aguarda: 10 segundos
Tentativa 3: POST /api/heartbeat → Sucesso ✓

Máquina continua no status anterior até sucesso

Resumo Rápido

FREQUÊNCIA:
  A cada ~1 segundo

ENVIA:
  POST /api/heartbeat
  Header: X-API-Key: ak_...
  
  Body (opcional):
  {
    "status": "running",
    "currentUser": "usuario",
    "policyVersion": 2
  }

RECEBE:
  200 OK
  {
    "status": "acknowledged"
  }

EFEITO:
  No painel: Status = 🟢 Online
  Próxima atualização: ~5-10s depois