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 -X POST https://<tenant>.api.3pontoapp.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 departamento, cargo e horário — crie (ou confirme) 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 e feriados (se aplicável) — POST /v2/calendars/ e POST /v2/calendars/holidays/.

3. Crie o funcionário

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

{
  "name": "Maria da Silva",
  "date_of_birth": "1992-04-15",
  "pis": "12345678901",
  "enrollment": "00123",
  "city": "São Paulo",
  "state": "SP"
}

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.