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	Sim	Objeto contendo as listas de entidades.
`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` ou `ti`.

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" }
      ]
    }
  }'

Response

Sucesso 200

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

Erros

Status	Causa
400	Campo `key` ausente ou inválido.
422	Campo `data` ausente ou sem a lista `employees`.
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

Response

Erros

Configuração detalhada de `interface`