Primeiros passos

Este guia percorre o caminho mínimo para uma integração funcional: autenticar, garantir os cadastros base e criar o primeiro funcionário.

Pré-requisitos

  • O subdomínio do tenant (ex.: minhaempresa).
  • Credenciais de um usuário com permissão nos módulos que a integração vai usar.

1. Autentique-se

curl -L -X POST https://<tenant>.api.blueponto.com.br/accounts/login/ \
  --header "Content-Type: application/json" \
  --data '{"username": "[email protected]", "password": "********"}'

Guarde o token e envie-o em todas as próximas chamadas: Authorization: JWT <token>. Detalhes em Autenticação.

2. Garanta os cadastros base

Um funcionário referencia empresa, departamento, cargo, horário, convenção coletiva e calendário (e, opcionalmente, vínculo empregatício e local) — crie ou consulte esses registros antes.

Departamento — POST /v2/departaments/

{ "name": "Operações" }

Cargo — POST /v2/departaments/positions/ (vincula ao departamento pelo id retornado acima)

{ "name": "Analista de Operações", "departament": 7 }

Horário/escala — POST /v2/schedules/ (exemplo de jornada semanal 44h; o detalhamento dos dias vai em page_of_schedule — consulte o schema completo na Referência)

{
  "name": "Comercial 08h-18h",
  "description": "Seg a sex, 1h de almoço",
  "status": true,
  "is_active": true,
  "weekly_journey_str": "44:00",
  "nigth_begin": "22:00",
  "nigth_end": "05:00",
  "page_of_schedule": []
}

Calendário — POST /v2/calendars/ (obrigatórios: name, percentage, increase_percentage e no_show_overtime_in_report)

{
  "name": "Calendário SP 2026",
  "percentage": 100,
  "increase_percentage": false,
  "no_show_overtime_in_report": false
}

Feriados — POST /v2/calendars/holidays/ (obrigatórios: calendarDate, date, name, kind e kind_drive).

Empresa e convenção coletiva — cadastradas no sistema web do tenant; pela API, consulte os ids:

curl -L "https://<tenant>.api.blueponto.com.br/enterprises/all/active/" \
  --header "Authorization: JWT <token>"
curl -L "https://<tenant>.api.blueponto.com.br/collectiveAgreements/all/active/" \
  --header "Authorization: JWT <token>"

Nas duas respostas, o campo value de cada item é o id usado no payload do funcionário (enterprise e collective_agreement).

3. Crie o funcionário

Funcionário — POST /employees/create/ (payload resumido; schema completo na Referência)

{
  "name": "Maria da Silva",
  "gender": 1,
  "cpf": "70123456789",
  "date_of_birth": "1992-04-15",
  "admission_date": "2026-09-01",
  "kind_journey": "Mensalista",
  "enrollment": "00123",
  "city": "São Paulo",
  "state": "SP",
  "enterprise": 1,
  "departament": 7,
  "position": 12,
  "schedule": 3,
  "collective_agreement": 2,
  "calendar_date": 5
}

São obrigatórios: name, cpf, gender, date_of_birth, admission_date, kind_journey, enterprise, departament, position, schedule, collective_agreement e calendar_date — os seis últimos recebem os ids obtidos no passo 2. Se algum faltar, a API responde 400 com o erro no próprio campo. pis é opcional: se omitido, é gerado a partir do CPF. kind_journey aceita "Horista" ou "Mensalista"; gender aceita 0 (masculino), 1 (feminino) ou 2 (não informar).

Usuário de acesso — POST /v2/users/mobile/create/ (colaborador que bate ponto pelo app). O username deve ser o CPF do colaborador, somente números (sem máscara).

{
  "name": "Maria da Silva",
  "employee": 315,
  "enterprise": 1,
  "email": "[email protected]",
  "username": "70123456789",
  "password": "SenhaForte#2026",
  "confirm_password": "SenhaForte#2026",
  "requires_update_password": true,
  "active_mobile": true,
  "active_tablet": false,
  "active_portal": false,
  "active_portal_consult": true,
  "double_verification": false,
  "require_unique_device": true
}

Para gestores/administradores, use POST /v2/users/manager/create/.

4. Valide

Confira no sistema web do tenant (https://<tenant>.blueponto.com.br) se o funcionário aparece com departamento, cargo e horário corretos — e, se criou o usuário mobile, faça um login de teste no app.

Próximos passos


Did this page help you?