API do Ponto

Controle de ponto da Melquides & Pinheiro. As batidas vêm do leitor de digital da recepção; esta API guarda e devolve os dados para qualquer integração (site, planilhas, relatórios).

Autenticação

Toda rota em /api/v1 exige uma chave no cabeçalho Authorization: Bearer <chave> (ou X-API-Key).

Tipo	Pode
leitura	consultar funcionários, presença, batidas e relatórios. É a chave para integrar com o site.
quiosque	registrar batida e ler funcionários/presença. Fica só no PC da recepção.
admin	tudo, inclusive corrigir/anular batidas e cadastrar funcionários.

Não coloque a chave em JavaScript do navegador: chame a API pelo servidor do site e repasse só o que for exibir.

Datas no formato AAAA-MM-DD, no horário de Brasília. Horários em ISO 8601 (UTC) no campo at e já formatados (HH:MM, Brasília) no campo time.

Presença

GET/api/v1/status leitura

Quem está no escritório agora e o resumo de hoje de cada um.

{
  "date": "2026-11-09",
  "present": ["gabriella"],
  "team": [{
    "slug": "gabriella", "name": "Gabriella",
    "photo_url": ".../photos/gabriella.webp", "avatar_url": ".../photos/gabriella-avatar.webp",
    "schedule": { "weekdays": [1,2,3,4,5], "start": "09:00", "end": "17:00" },
    "present": true,
    "today": { "status": "working", "worked": "3h12", "late_minutes": 0, "punches": [...] }
  }]
}

status do dia: working (dentro agora), done (saiu), scheduled (ainda vai chegar), absent (falta), off (folga), incomplete (batida faltando).

Funcionários

GET/api/v1/employees leitura

Lista os ativos (?all=1 inclui inativos).

GET/api/v1/employees/:slug leitura

POST/api/v1/employees admin

{ "slug": "maria", "name": "Maria", "role": "Estagiária",
  "schedule": { "weekdays": [1,2,3,4,5], "start": "13:00", "end": "19:00" } }

PATCH/api/v1/employees/:slug admin

Altera qualquer campo acima, ou {"active": false} para desligar.

Batidas

GET/api/v1/punches?from=&to=&employee= leitura

Uma linha por batida. Aceita date, from/to ou month=AAAA-MM. voided=1 inclui as anuladas.

POST/api/v1/punches quiosque / admin

{ "employee": "jonathan" }                         // quiosque: entrada/saída é deduzida
{ "employee": "jonathan", "kind": "out",
  "at": "2026-11-09T18:02:00-03:00", "note": "esqueceu de bater" }   // admin

Batidas repetidas em menos de 90 s devolvem a anterior com "duplicate": true.

PATCH/api/v1/punches/:id admin

Corrige at, kind ou note.

DELETE/api/v1/punches/:id?reason= admin

Anula a batida. Nada é apagado de verdade, ela só deixa de contar.

Espelho de ponto

GET/api/v1/report?month=2026-11&employee= leitura

Um resumo por funcionário e por dia, com totais do período (também aceita from/to).

{
  "from": "2026-11-01", "to": "2026-11-30", "tolerance_minutes": 10,
  "report": [{
    "employee": { "slug": "juliana", ... },
    "totals": { "worked": "84h10", "expected": "84h00", "balance": "0h10",
                "days_worked": 14, "days_late": 1, "absences": 0, "incomplete_days": 0, ... },
    "days": [{ "date": "2026-11-09", "status": "done", "worked_minutes": 361,
               "expected_minutes": 360, "late_minutes": 0, "early_leave_minutes": 0,
               "first_in": "...", "last_out": "...", "issues": [], "punches": [...] }]
  }]
}

Atraso e saída antecipada só contam acima da tolerância de 10 minutos (CLT, art. 58, §1º).

Fotos

/photos/<slug>.webp (retrato 720×960) e /photos/<slug>-avatar.webp (400×400) são públicas.

Exemplo

curl -H "Authorization: Bearer $PONTO_KEY" \
  "https://ponto.melquidesepinheiro.adv.br/api/v1/report?month=2026-11"