Skip to main content
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:
  1. App captura GPS atual
  2. API valida: posição está dentro do raio de pelo menos um Local permitido para esse colaborador?
  3. Se NÃO: registro fica REJEITADO com motivo FORA_DO_CERCO
  4. 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