Controle de Ponto

Registro de batidas de ponto, consulta por dia, eventos de calendário e solicitações de extensão.

Endpoints disponíveis

Endpoint	Método	Descrição
`/recordPunch`	POST	Registra uma ação de ponto unitária (ex.: BEGIN_DAY).
`/sendPunchClock`	POST	Envia jornada completa ou parcial do dia.
`/listPunchClockByDay`	POST	Lista batidas de ponto por data.
`/getEvents`	POST	Retorna eventos de calendário por range de datas.
`/setEvent`	POST	Cria ou atualiza evento(s) de calendário.
`/listExtensionRequests`	POST	Lista solicitações de extensão pendentes.
`/approveRequest`	POST	Aprova ou rejeita uma solicitação de extensão.

Shape padrão de resposta: sucesso retorna { "err": false, "result": { ... } }; erro retorna { "err": true, "message": "..." }. Sempre verifique o campo err antes de consumir result.

POST /recordPunch

Registra uma ação unitária de ponto (ex.: início do dia, fim do dia). Use /sendPunchClock para enviar múltiplas marcações em uma única chamada.

Request body

Campo	Tipo	Obrigatório	Descrição
`key`	string	Sim	Chave criptografada da empresa.
`username`	string	Sim	Login do colaborador.
`actionType`	enum	Sim	Tipo de batida: `BEGIN_DAY`, `BEGIN_LUNCH`, `END_LUNCH` ou `END_DAY`.
`actionDatetimeSent`	string ISO-8601	Sim	Data/hora da batida. Formato `YYYY-MM-DDTHH:mm:ssZ`.
`hostname`	string	Sim	Nome da máquina ou dispositivo que registrou a batida.
`locationType`	string	Sim	`office`, `home` ou `field`.
`source`	string	Não	Origem do registro. Default: `integration`.

cURL

curl -X POST https://integrations.fhinck.com/recordPunch \
  -H "Content-Type: application/json" \
  -d '{
    "key": "SUA_CHAVE_DE_INTEGRACAO",
    "username": "joao.silva",
    "actionType": "BEGIN_DAY",
    "actionDatetimeSent": "2026-04-24T08:00:00Z",
    "hostname": "WORKSTATION-01",
    "locationType": "office"
  }'

JavaScript (fetch)

await fetch('https://integrations.fhinck.com/recordPunch', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    key: process.env.FHINCK_KEY,
    username: 'joao.silva',
    actionType: 'BEGIN_DAY',
    actionDatetimeSent: '2026-04-24T08:00:00Z',
    hostname: 'WORKSTATION-01',
    locationType: 'office',
  }),
});

Python (requests)

import os, requests

requests.post(
    'https://integrations.fhinck.com/recordPunch',
    json={
        'key': os.environ['FHINCK_KEY'],
        'username': 'joao.silva',
        'actionType': 'BEGIN_DAY',
        'actionDatetimeSent': '2026-04-24T08:00:00Z',
        'hostname': 'WORKSTATION-01',
        'locationType': 'office',
    },
    timeout=30,
)

POST /sendPunchClock

Envia uma ou mais marcações de ponto de um colaborador em uma única chamada. Pelo menos um dos campos beginDay, beginLunch, endLunch ou endDay é obrigatório. Formato ISO-8601: YYYY-MM-DDTHH:mm:ssZ.

Request body

Campo	Tipo	Obrigatório	Descrição
`key`	string	Sim	Chave criptografada da empresa.
`username`	string	Sim	Login do colaborador.
`date`	string	Sim	Data da batida. Formato `YYYY-MM-DD`.
`beginDay`	string ISO-8601	Condicional	Timestamp de início do dia.
`beginLunch`	string ISO-8601	Condicional	Timestamp de início do almoço.
`endLunch`	string ISO-8601	Condicional	Timestamp de fim do almoço.
`endDay`	string ISO-8601	Condicional	Timestamp de fim do dia.
`hostname`	string	Sim	Nome da máquina ou dispositivo.
`locationType`	string	Sim	`office`, `home` ou `field`.
`source`	string	Não	Origem. Default: `integration`.

cURL — jornada completa

curl -X POST https://integrations.fhinck.com/sendPunchClock \
  -H "Content-Type: application/json" \
  -d '{
    "key": "SUA_CHAVE_DE_INTEGRACAO",
    "username": "joao.silva",
    "date": "2026-04-24",
    "beginDay": "2026-04-24T08:00:00Z",
    "beginLunch": "2026-04-24T12:00:00Z",
    "endLunch": "2026-04-24T13:00:00Z",
    "endDay": "2026-04-24T17:00:00Z",
    "hostname": "PC-JOAO",
    "locationType": "office"
  }'

Response 200

{
  "err": false,
  "result": {
    "success": true,
    "action_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "action_date": "2026-04-24",
    "username": "joao.silva"
  }
}

POST /listPunchClockByDay

Retorna todas as batidas de uma empresa em um dia específico, com filtro opcional por usuários.

Campo	Tipo	Obrigatório	Descrição
`key`	string	Sim	Chave criptografada da empresa.
`date`	string	Sim	Data. Formato `YYYY-MM-DD`.
`users`	string[]	Não	Filtra por logins. Se omitido, retorna todos.

cURL

curl -X POST https://integrations.fhinck.com/listPunchClockByDay \
  -H "Content-Type: application/json" \
  -d '{
    "key": "SUA_CHAVE_DE_INTEGRACAO",
    "date": "2026-04-24",
    "users": ["joao.silva"]
  }'

JavaScript (fetch)

const res = await fetch('https://integrations.fhinck.com/listPunchClockByDay', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    key: process.env.FHINCK_KEY,
    date: '2026-04-24',
    users: ['joao.silva'],
  }),
});
const data = await res.json();
if (data.err) throw new Error(data.message);
console.log(data.result);

Python (requests)

import os, requests

data = requests.post(
    'https://integrations.fhinck.com/listPunchClockByDay',
    json={
        'key': os.environ['FHINCK_KEY'],
        'date': '2026-04-24',
        'users': ['joao.silva'],
    },
    timeout=30,
).json()

if data['err']:
    raise RuntimeError(data['message'])
print(data['result'])

POST /getEvents

Retorna eventos de calendário (feriados, folgas, eventos especiais) por range de datas. Se users não for informado ou vier vazio, retorna todos os eventos no intervalo.

Campo	Tipo	Obrigatório	Descrição
`key`	string	Sim	Chave criptografada da empresa.
`dateBegin`	string (YYYY-MM-DD)	Sim	Data inicial do intervalo.
`dateEnd`	string (YYYY-MM-DD)	Sim	Data final do intervalo.
`users`	string[]	Não	Filtro por login. Vazio = todos.

Dois formatos de payload aceitos (equivalentes): os campos podem ficar na raiz do body ou dentro de um objeto payload. Escolha o que for mais conveniente para seu cliente HTTP.

Formato 1: payload aninhado

cURL — payload aninhado

curl -X POST https://integrations.fhinck.com/getEvents \
  -H "Content-Type: application/json" \
  -d '{
    "key": "SUA_CHAVE_DE_INTEGRACAO",
    "payload": {
      "dateBegin": "2026-04-01",
      "dateEnd": "2026-04-30",
      "users": ["joao.silva"]
    }
  }'

Formato 2: chaves na raiz

cURL — chaves na raiz

curl -X POST https://integrations.fhinck.com/getEvents \
  -H "Content-Type: application/json" \
  -d '{
    "key": "SUA_CHAVE_DE_INTEGRACAO",
    "dateBegin": "2026-04-01",
    "dateEnd": "2026-04-30",
    "users": ["joao.silva"]
  }'

Response 200

{
  "err": false,
  "result": {
    "events": [
      {
        "id": "EVT-123",
        "title": "Comunicado",
        "users": ["joao.silva"],
        "dateTimeBegin": "2026-04-01 08:00:00",
        "dateTimeEnd": "2026-04-30 18:00:00",
        "lastUpdate": "2026-04-29 01:01:00",
        "active": true
      }
    ]
  }
}

POST /setEvent

Cria ou atualiza eventos no dataset da empresa. Aceita múltiplos eventos via array events (cada item deve conter ao menos id). Quando o id não existir na base, o evento é criado com defaults (por exemplo, active: true quando não informado). Em atualizações, apenas os campos enviados são alterados.

Aceita o array events tanto na raiz do body quanto aninhado em payload.

cURL — criar/atualizar eventos

curl -X POST https://integrations.fhinck.com/setEvent \
  -H "Content-Type: application/json" \
  -d '{
    "key": "SUA_CHAVE_DE_INTEGRACAO",
    "updatedBy": "usuario@empresa.com",
    "payload": {
      "events": [
        { "id": "EVT-001", "active": true, "dateTimeBegin": "2026-04-01 08:00:00" },
        { "id": "EVT-002", "name": "Atualização", "workstation": "locked" }
      ]
    }
  }'

Response 200

{ "err": false, "message": "Eventos processados com sucesso" }

id é obrigatório em cada item de events.
Se o id não existir, o registro é criado (com active: true quando não informado).
Apenas campos existentes no schema são aceitos. Para indicar estação bloqueada use workstation: "locked".

POST /listExtensionRequests

Lista solicitações de extensão de jornada pendentes de aprovação para um gestor.

Campo	Tipo	Obrigatório
`key`	string	Sim
`email`	string	Sim

POST /approveRequest

Aprova ou rejeita uma solicitação de extensão de jornada.

Campo	Tipo	Obrigatório	Descrição
`key`	string	Sim	Chave criptografada da empresa.
`employee`	string	Sim	Login do colaborador.
`managerEmail`	string	Sim	Email do gestor aprovador.
`approved`	boolean	Sim	`true` para aprovar, `false` para rejeitar.