A estrutura organizacional do Pontua define onde e como cada
colaborador está alocado. Ela alimenta filtros de listagem, agrupamentos
em relatórios, hierarquia de gestão (gestor vê subordinados) e regras
de folha (centro de custo vai para razão contábil).
Sincronizar a estrutura é pré-requisito para sincronizar colaboradores —
ver Colaboradores.
Modelo hierárquico
Endpoints por entidade
Unidade de Negócio
Departamento
Equipe, Cargo, Centro de Custo, Local de Trabalho
Cada um segue padrão CRUD similar:
GET /<entidade> — lista
GET /<entidade>/{id} — detalhe
POST /<entidade> — criar
PATCH /<entidade>/{id} — atualizar
DELETE /<entidade>/{id} — remover
Cargo tem extras: GET /cargos/codigos-cbo (catálogo CBO oficial),
GET /cargos/cards (totais por status), GET /cargos/export/csv.
Local de Trabalho tem /gestao-ponto/local-trabalho/todos-locais
para listar sem agrupar por UN.
Schema completo em Referência da API.
Contexto eSocial / CBO
A integração com folha (eSocial) exige códigos CBO (Classificação
Brasileira de Ocupações) válidos no campo cargo. O Pontua mantém
catálogo:
Use os códigos CBO desse catálogo ao criar Cargo. Códigos inválidos
não são bloqueados pela API mas podem causar rejeição no eSocial
mensal.
Local de Trabalho e cerco geográfico
Local de Trabalho carrega coordenadas GPS + raio. Quando colaborador
bate ponto pelo app:
- App captura GPS atual
- API valida: posição está dentro do raio de pelo menos um Local
permitido para esse colaborador?
- Se NÃO: registro fica
REJEITADO com motivo FORA_DO_CERCO
- Se SIM: registro entra normal
Configurar Locais corretamente é crítico para empresas com trabalho
remoto/híbrido — colaborador pode ter 3 Locais permitidos (escritório,
casa, cliente X).
A Portaria 671 reconhece geolocalização como prova de presença válida
desde que o colaborador consinta.
Fluxos típicos
Sync inicial de estrutura (onboarding)
Migração de departamento (reorg)
Gotchas conhecidos
Tentar DELETE em departamento/cargo/CC com colaboradores vinculados
retorna 409 Conflict. Migre os colaboradores primeiro (PATCH unificado).
Cargo, Centro de Custo e Local de Trabalho têm rotas legacy
PUT /:id marcadas como deprecated. Use sempre PATCH /:id em
integração nova.
Alguns endpoints estão em prefixos diferentes do esperado:
Cargo → /cargos (plural)
Centro de Custo → /minha-empresa/centro-custo
Local de Trabalho → /gestao-ponto/local-trabalho
Mantemos por compatibilidade. Esteja atento ao montar URLs.
Se você cadastrar Local sem latitude/longitude, o cerco “sempre passa”
para colaboradores vinculados. Em ambientes com cobrança rigorosa de
presença, valide GPS antes de salvar.
Veja também