Guia da API Kronus

Autenticação

Toda chamada leva a chave no header X-API-Key. A chave é emitida em Configurações › Integrações e o texto pleno aparece uma única vez — o banco guarda só o hash.

curl https://kronus.online/api/v1/conta/ \
  -H "X-API-Key: kr_12_xxxxxxxxxxxxxxxxxxxxxxxx"

Comece sempre por GET /api/v1/conta/: ele diz o que a chave alcança e qual é a sua cota horária. Descobrir a cota estourando o limite em produção é o caminho caro.

Sincronizando marcações

Use o NSR, não a data. O NSR é sequencial e imutável por empresa. Guarde o último que você recebeu e peça os seguintes:

GET /api/v1/pontos/?nsr_maior_que=48213

Paginar por data parece equivalente, mas não é: quando o RH lança um ajuste retroativo, a marcação nova recebe uma data antiga e um NSR novo. Quem sincroniza por data já passou daquele dia e nunca mais volta — a marcação some da integração. Quem sincroniza por NSR a recebe na próxima chamada.

Conferindo integridade

Cada marcação carrega hash_registro e hash_anterior, formando uma cadeia. Para conferir uma marcação sem acesso ao banco:

GET /api/v1/pontos/{uuid}/verificar/

{
  "nsr": 48214,
  "hash_gravado":     "a3f2…",
  "hash_recalculado": "a3f2…",
  "integro": true
}

É o que sustenta a apresentação a uma fiscalização: o hash prova que o conteúdo do registro não mudou depois de gravado.

Levando para a folha

GET /api/v1/banco-horas/resumo/ entrega os totais do período por colaborador. Cada total vem em minutos (para calcular) e em HH:MM (para exibir).

GET /api/v1/banco-horas/resumo/?data_inicio=2026-07-01&data_fim=2026-07-31

[{
  "colaborador_nome": "João da Silva Souza",
  "minutos_trabalhados": 10230,
  "minutos_extras": 420,
  "saldo_anterior": -120,
  "saldo_periodo":   300,
  "saldo_final":     180,
  "saldo_final_formatado": "+03:00",
  "dias_falta": 1
}]

saldo_anterior e saldo_final vêm juntos de propósito: a folha precisa saber quanto o mês movimentou, não só onde o banco parou. Ao converter para horas decimais, lembre que 1h30 = 1,50, não 1,30.

Recebendo eventos

Em vez de perguntar de minuto em minuto, deixe o Kronus avisar. Cadastre um webhook HTTPS em Configurações › Webhooks e trate o POST:

POST https://seu-erp.com/kronus/
X-Kronus-Event: ponto.registrado
X-Kronus-Delivery: 8f3a…            # deduplique por este id
X-Kronus-Timestamp: 1787000000
X-Kronus-Signature: sha256=abc123…

{"evento": "...", "empresa": {...}, "dados": {...}}

Validando a assinatura

import hmac, hashlib, time

def confere(corpo: bytes, segredo: str, ts: str, assinatura: str) -> bool:
    # Recuse o que for velho demais — protege contra reenvio.
    if abs(time.time() - int(ts)) > 300:
        return False
    esperada = "sha256=" + hmac.new(
        segredo.encode(), f"{ts}.".encode() + corpo, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(esperada, assinatura)

Limites e erros

O 404 é deliberadamente ambíguo entre "não existe" e "existe em outra conta": distinguir permitiria descobrir UUIDs válidos de terceiros.

O que a API nunca devolve

• Embedding facial. Dado biométrico é sensível (LGPD, Art. 11) e nenhuma integração tem finalidade que o justifique. Você recebe apenas face_registrada: true/false.
• CID do atestado. Dado de saúde (Art. 5º, II). O que a folha precisa — período, dias e status — vem completo.