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
- Fluxos de integração — movimentações, abonos, lançamentos manuais e tempo real.
- Convenções da API — formatos de data, erros, paginação e limites.
Updated 7 days ago