Master Data

Sincronize colaboradores, gestores, departamentos, cargos e regiões com a Plataforma Fhinck.

Endpoint

POST https://integrations.fhinck.com/masterData

Cria ou atualiza dados de estrutura organizacional. Operação idempotente — enviar o mesmo registro duas vezes não gera duplicidade.

Envio recomendado: Envie deltas diários — apenas registros criados, atualizados ou desativados desde o último envio. Não é necessário enviar a base completa a cada dia (dump full). Dumps frequentes aumentam latência e consumo de quota sem benefício.

Request body

Campo	Tipo	Obrigatório	Descrição
`key`	string	Sim	Chave criptografada de autenticação da empresa.
`data`	object	Não*	Objeto contendo as listas de entidades a gravar. *Obrigatório se `read` não for enviado.
`read`	array	Não*	O que devolver na resposta: `"employees"` (consulta por `ids`) e/ou `"shifts"` (todos os turnos da empresa). *Obrigatório se `data` não for enviado.
`ids`	array	Não	Logins a consultar. Obrigatório quando `read` inclui `"employees"`. Máximo 5.000 itens por chamada.
`data.employees`	array	Sim	Lista de colaboradores. Pode ser vazia `[]`.
`data.managers`	array	Não	Lista de gestores.
`data.departments`	array	Não	Lista de departamentos.
`data.regions`	array	Não	Lista de regiões.
`data.roles`	array	Não	Lista de cargos.

Exemplo mínimo — apenas colaboradores

Começar com o envio mínimo é a forma mais rápida de validar a integração. Apenas key + data.employees com campos obrigatórios:

cURL — mínimo

curl -X POST https://integrations.fhinck.com/masterData \
  -H "Content-Type: application/json" \
  -d '{
    "key": "SUA_CHAVE_DE_INTEGRACAO",
    "data": {
      "employees": [
        {
          "login": "joao.silva",
          "name": "João Silva",
          "department": "COORD",
          "role": "ANALISTA",
          "active": true
        }
      ]
    }
  }'

JavaScript (fetch)

const res = await fetch('https://integrations.fhinck.com/masterData', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    key: process.env.FHINCK_KEY,
    data: {
      employees: [
        { login: 'joao.silva', name: 'João Silva', department: 'COORD', role: 'ANALISTA', active: true },
      ],
    },
  }),
});

const data = await res.json();
if (data.err) throw new Error(data.message);
console.log('Atualização concluída');

Python (requests)

import os, requests

payload = {
    'key': os.environ['FHINCK_KEY'],
    'data': {
        'employees': [
            {
                'login': 'joao.silva',
                'name': 'João Silva',
                'department': 'COORD',
                'role': 'ANALISTA',
                'active': True,
            },
        ],
    },
}

resp = requests.post('https://integrations.fhinck.com/masterData', json=payload, timeout=30)
body = resp.json()
if body.get('err'):
    raise RuntimeError(body['message'])
print('Atualização concluída')

Schema: Employee

Campo	Tipo	Obrigatório	Descrição
`login`	string	Sim	Identificador único do colaborador.
`name`	string	Sim	Nome completo.
`department`	string	Sim	Código do departamento folha.
`department_path`	string	Não	Cadeia hierárquica de códigos separados por `_`. Ex.: `DIR_GER_SUP`.
`role`	string	Sim	Código do cargo.
`region`	string	Não	Código da região.
`active`	boolean	Sim	`true` para colaborador ativo.
`vacation`	boolean	Não	`true` se em férias. Default: `false`.
`vacation_date_in`	string (date)	Não	Início das férias. Formato `YYYY-MM-DD`.
`vacation_date_out`	string (date)	Não	Fim das férias. Formato `YYYY-MM-DD`.
`interface`	object	Não	Configurações de jornada e controle de ponto. Ver schema detalhado.

Configuração detalhada de `interface`

O objeto interface em cada Employee controla jornada, controle de ponto e comportamento do coletor no dispositivo. Todos os campos têm default — envie apenas os que quiser sobrescrever.

Jornada

Campo	Tipo	Default	Descrição
`journey_type`	string	`flex`	`classic` (jornada fixa) ou `flex` (flexível).
`begin_journey`	object	—	Horário de início por dia da semana (`monday..sunday`). Ex.: `{"monday": "08:00:00"}`.
`end_journey`	object	—	Horário de fim por dia da semana. Formato `HH:MM:SS`.
`begin_lunch_time`	object	—	Horário de início do almoço por dia da semana.
`end_lunch_time`	object	—	Horário de fim do almoço por dia da semana.
`journey_time`	object	—	Duração total da jornada em minutos por dia. Ex.: `{"monday": 540}` (9h).
`journey_first_period_time`	integer	`0`	Duração do primeiro período em minutos (antes do almoço).
`journey_interval_time`	integer	`0`	Duração do intervalo de almoço em minutos.
`margin_for_time_limits`	integer	`0`	Tolerância em minutos para limites de horário.
`journey_edit_enabled`	boolean	`false`	Permite que o colaborador edite a jornada registrada.
`journey_max_history`	integer	`31`	Dias máximos de histórico de jornada acessível ao colaborador.

Controle de ponto

Campo	Tipo	Default	Descrição
`punch_clock_active`	boolean	`true`	Controle de ponto ativado para o colaborador.
`lock_by_punch`	boolean	`true`	Bloqueia a estação entre batidas (ex.: durante almoço).
`lock_by_punch_delay`	integer	`0`	Atraso em segundos antes do bloqueio automático.
`lock_out_of_journey`	boolean	`false`	Bloqueia a estação fora do horário de jornada.
`collector_control_disabled`	boolean	`true`	Desabilita controles manuais do coletor.
`ask_journey_extension_timeout`	integer	`0`	Timeout em segundos para solicitar extensão automaticamente.

Extra time e justificativas

Campo	Tipo	Default	Descrição
`extra_time.allowed`	boolean	`true`	Permite solicitação de horas extras.
`justification_list`	array	—	Lista de justificativas pré-aprovadas. Cada item: `{ "activity": "Reunião externa" }`.

Autenticação do coletor

Campo	Tipo	Default	Descrição
`auth.token_period`	string	—	Período de validade do token (ex.: `"24h"`, `"7d"`).
`auth.token_scope`	string	—	Escopo do token do coletor.

Schema: Manager

Campo	Tipo	Obrigatório	Descrição
`email`	string	Sim	Email corporativo do gestor.
`name`	string	Sim	Nome completo.
`department`	string	Sim	Código do departamento.
`department_path`	string	Não	Cadeia hierárquica. Ex.: `DIR_GER`.
`role`	string	Sim	Código do cargo.
`region`	string	Não	Código da região.
`active`	boolean	Sim	`true` para gestor ativo.
`profile`	string	Sim	`admin`, `analytics`, `approver2`, `ti` ou `approver6`. `approver6` identifica o sócio: tem o mesmo acesso de `approver2` e é quem aprova extensões acima de 2 horas.

Schemas: Department, Region, Role

Entidade	Campos obrigatórios	Campos opcionais
Department	`code`, `name`	`department_level` (integer)
Region	`code`, `name`	—
Role	`code`, `name`	—

Exemplo completo — todas as entidades

cURL

curl -X POST https://integrations.fhinck.com/masterData \
  -H "Content-Type: application/json" \
  -d '{
    "key": "SUA_CHAVE_DE_INTEGRACAO",
    "data": {
      "employees": [
        {
          "login": "joao.silva",
          "name": "João Silva",
          "department": "COORD",
          "department_path": "DIR_GER_COORD",
          "role": "ANALISTA",
          "region": "SP",
          "active": true,
          "interface": {
            "punch_clock_active": true,
            "journey_type": "flex",
            "begin_journey": { "monday": "08:00:00", "tuesday": "08:00:00" },
            "journey_time": { "monday": 540, "tuesday": 540 }
          }
        }
      ],
      "managers": [
        {
          "email": "maria.gestora@empresa.com",
          "name": "Maria Gestora",
          "department": "GER",
          "department_path": "DIR_GER",
          "role": "GERENTE",
          "region": "SP",
          "active": true,
          "profile": "approver2"
        }
      ],
      "departments": [
        { "code": "DIR", "name": "Diretoria", "department_level": 1 },
        { "code": "GER", "name": "Gerência", "department_level": 2 },
        { "code": "COORD", "name": "Coordenação", "department_level": 3 }
      ],
      "regions": [
        { "code": "SP", "name": "São Paulo" }
      ],
      "roles": [
        { "code": "ANALISTA", "name": "Analista" },
        { "code": "GERENTE", "name": "Gerente" }
      ]
    }
  }'

O mesmo endpoint devolve o que está armazenado. Envie read: ["employees"] e ids com a lista de logins: a resposta traz o registro mais recente de cada um, com todos os campos do cadastro. É somente leitura — não cria nem altera nada.

cURL — consulta

curl -X POST https://integrations.fhinck.com/masterData \
  -H "Content-Type: application/json" \
  -d '{
    "key": "SUA_CHAVE_DE_INTEGRACAO",
    "read": ["employees"],
    "ids": ["maria.silva", "joao.souza", "ana.pereira"]
  }'

JavaScript — consulta

const resposta = await fetch('https://integrations.fhinck.com/masterData', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    key: 'SUA_CHAVE_DE_INTEGRACAO',
    read: ['employees'],
    ids: ['maria.silva', 'joao.souza', 'ana.pereira'],
  }),
})

const { employees, notFound } = await resposta.json()

Python — consulta

import requests

resposta = requests.post(
    "https://integrations.fhinck.com/masterData",
    json={
        "key": "SUA_CHAVE_DE_INTEGRACAO",
        "read": ["employees"],
        "ids": ["maria.silva", "joao.souza", "ana.pereira"],
    },
)

dados = resposta.json()
print(dados["employees"], dados["notFound"])

Resposta — 2 encontrados, 1 ausente

{
  "err": false,
  "employees": [
    {
      "employee": "maria.silva",
      "employee_alias": "MARIA SILVA",
      "employee_id": "10482",
      "fk_department_code": "OPS03",
      "department_path": "RAIZ_OPS03",
      "fk_role_code": "ROLE12",
      "fk_region_code": "REG01",
      "active": true,
      "vacation_active": false,
      "vacation_date_in": null,
      "vacation_date_out": null,
      "Entry_Weekday": "09:00:00",
      "Exit_Weekday": "18:00:00",
      "Entry_Saturday": null,
      "Exit_Saturday": null,
      "Entry_Sunday": null,
      "Exit_Sunday": null,
      "creation_user": "integracao-rh",
      "creation_date": { "value": "2026-09-16T13:02:11.000000Z" },
      "search_date":   { "value": "2026-09-16T00:00:00.000000Z" }
    },
    { "employee": "joao.souza", "...": "demais campos" }
  ],
  "read": { "entity": "employees", "requested": 3, "found": 2, "notFound": 1 },
  "notFound": ["ana.pereira"]
}

Comportamento	Detalhe
Login inexistente	Volta nomeado em `notFound`, com a lista dos que faltaram — não some em silêncio.
Caixa e espaços	Maiúsculas, minúsculas e espaços nas pontas são ignorados; login repetido volta uma vez só no resultado.
Limite	5.000 itens por chamada, contados na lista como ela chega: repetição conta. Uma lista com 6.000 entradas do mesmo login é recusada com 422, mesmo virando um único registro depois.
Datas	`creation_date` e `search_date` vêm como objeto `{"value": "<ISO-8601 UTC>"}`, não como string. Leia o `.value` de cada um.
Bloco `summary`	Conta o que foi gravado; numa consulta pura vem zerado. As contagens da consulta ficam em `read`.
Entidades	Hoje a consulta por `ids` cobre colaboradores. Outras entidades retornam 422 explícito.
Gravar e conferir	`data`, `read` e `ids` podem ir na mesma chamada: grava primeiro, e a resposta traz o que ficou gravado.

Response

Sucesso 200 — gravação

{
  "err": false,
  "message": "Atualização concluída com sucesso!"
}

Quando a chamada inclui read, a resposta ganha os blocos correspondentes: employees, read e notFound (consulta por ids) e/ou shifts (todos os turnos da empresa).

Erros

Status	Causa
400	Campo `key` ausente ou inválido.
422	Nenhum dos dois enviado: `data` (gravação) e `read` (consulta).
422	`read` inclui `"employees"` mas `ids` está ausente ou vazio.
422	`ids` acima de 5.000 itens. A mensagem traz a contagem recebida.
422	Entidade em `read` ainda não disponível para consulta por `ids`.
500	Erro interno ao processar os dados.

Master Data

Endpoint

Request body

Exemplo mínimo — apenas colaboradores

Schema: Employee

Configuração detalhada de interface

Jornada

Controle de ponto

Extra time e justificativas

Autenticação do coletor

Schema: Manager

Schemas: Department, Region, Role

Exemplo completo — todas as entidades

Consulta — buscar o cadastro por login

Response

Erros

Configuração detalhada de `interface`