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
Unidade de Negócio (UN)
├── Departamento
│ └── Equipe (opcional)
│ └── Colaborador
│
├── Cargo (catálogo da UN, vinculado por colaborador)
├── Centro de Custo (catálogo da UN, vinculado por colaborador)
└── Local de Trabalho (catálogo da UN, vinculado por colaborador via cerco geográfico)
| Entidade | Função | Vinculado a quem |
|---|
| Unidade de Negócio | Empresa/CNPJ ou filial. Cada UN é um tenant. | Colaboradores, departamentos, todo o resto |
| Departamento | Estrutura funcional (TI, RH, Comercial). | Colaborador (1:N) |
| Equipe | Subdivisão dentro do departamento (opcional). | Colaborador (1:N), Departamento (N:1) |
| Cargo | Função/CBO (Desenvolvedor, Vendedor). | Colaborador (1:N) |
| Centro de Custo | Conta contábil para apropriação de folha. | Colaborador (1:N) |
| Local de Trabalho | Geolocalização para cerco de batida. | Colaborador (M:N) — pode trabalhar em múltiplos |
Endpoints por entidade
Unidade de Negócio
| Método | Rota | Descrição |
|---|
| GET | /unidade-negocio | Lista UNs |
| GET | /unidade-negocio/{id} | Detalhe de uma UN |
| GET | /unidade-negocio/{id}/dados | Dados cadastrais (CNPJ, IE, endereço) |
| PATCH | /unidade-negocio/{id}/dados | Atualizar dados cadastrais |
| GET | /unidade-negocio/{id}/contato | Contatos da UN |
| PATCH | /unidade-negocio/{id}/contato | Atualizar contatos |
| GET | /unidade-negocio/{id}/personalizacao | Logos, cores |
| PATCH | /unidade-negocio/{id}/personalizacao | Atualizar personalização |
| POST | /unidade-negocio | Cria nova UN |
| PATCH | /unidade-negocio/{id}/ativar | Ativa UN |
| PATCH | /unidade-negocio/{id}/inativar | Inativa UN |
| DELETE | /unidade-negocio/{id} | Remove UN |
| GET | /unidade-negocio/filtros | Valores possíveis para filtros (segmento, etc.) |
Departamento
| Método | Rota | Descrição |
|---|
| GET | /departamentos | Lista departamentos |
| GET | /departamentos/{id} | Detalhe |
| POST | /departamentos/{unidadeNegocioId} | Cria dentro de uma UN |
| PATCH | /departamentos/{id} | Atualiza |
| DELETE | /departamentos/{id} | Remove (apenas se não houver colaboradores vinculados) |
| POST | /departamentos/import | Import CSV |
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:
// Listar todos os CBOs reconhecidos
const cbos = await fetch(
'https://api.pontua.com.br/cargos/codigos-cbo',
{ headers: { Authorization: `Bearer ${TOKEN}` } },
).then((r) => r.json())
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)
async function syncEstruturaInicial(token, dadosErp) {
const headers = { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' }
// Ordem de criação importa (dependências):
// 1. Departamentos (não depende de nada além da UN)
for (const dept of dadosErp.departamentos) {
await fetch(
`https://api.pontua.com.br/departamentos/${dept.unidadeNegocioId}`,
{ method: 'POST', headers, body: JSON.stringify(dept) },
)
}
// 2. Cargos (precisam CBO válido)
for (const cargo of dadosErp.cargos) {
await fetch('https://api.pontua.com.br/cargos', {
method: 'POST', headers, body: JSON.stringify(cargo),
})
}
// 3. Centros de Custo
for (const cc of dadosErp.centrosCusto) {
await fetch('https://api.pontua.com.br/minha-empresa/centro-custo', {
method: 'POST', headers, body: JSON.stringify(cc),
})
}
// 4. Equipes (dependem de departamentos)
for (const equipe of dadosErp.equipes) {
await fetch('https://api.pontua.com.br/equipe', {
method: 'POST', headers, body: JSON.stringify(equipe),
})
}
// 5. Locais de Trabalho (independentes)
for (const local of dadosErp.locais) {
await fetch('https://api.pontua.com.br/gestao-ponto/local-trabalho', {
method: 'POST', headers, body: JSON.stringify(local),
})
}
// 6. Colaboradores (dependem de TUDO acima — ver guia separado)
// ...
}
Migração de departamento (reorg)
// Cenário: dois departamentos vão se fundir
async function fundirDepartamentos(token, oldDept1Id, oldDept2Id, newDeptId) {
// 1. Listar colaboradores dos dois departamentos antigos
const { resultados } = await fetch(
`https://api.pontua.com.br/colaborador?` +
`departamentoId=${oldDept1Id}&limite=100`,
{ headers: { Authorization: `Bearer ${token}` } },
).then((r) => r.json())
// 2. Mover cada um para o novo departamento via PATCH unificado
for (const colab of resultados) {
await fetch(`https://api.pontua.com.br/colaborador/${colab.id}`, {
method: 'PATCH',
headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
body: JSON.stringify({ departamentoId: newDeptId }),
})
}
// 3. Após mover todos, remover departamentos antigos
await fetch(`https://api.pontua.com.br/departamentos/${oldDept1Id}`, {
method: 'DELETE', headers: { Authorization: `Bearer ${token}` },
})
}
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