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

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)
EntidadeFunçãoVinculado a quem
Unidade de NegócioEmpresa/CNPJ ou filial. Cada UN é um tenant.Colaboradores, departamentos, todo o resto
DepartamentoEstrutura funcional (TI, RH, Comercial).Colaborador (1:N)
EquipeSubdivisão dentro do departamento (opcional).Colaborador (1:N), Departamento (N:1)
CargoFunção/CBO (Desenvolvedor, Vendedor).Colaborador (1:N)
Centro de CustoConta contábil para apropriação de folha.Colaborador (1:N)
Local de TrabalhoGeolocalização para cerco de batida.Colaborador (M:N) — pode trabalhar em múltiplos

Endpoints por entidade

Unidade de Negócio

MétodoRotaDescrição
GET/unidade-negocioLista UNs
GET/unidade-negocio/{id}Detalhe de uma UN
GET/unidade-negocio/{id}/dadosDados cadastrais (CNPJ, IE, endereço)
PATCH/unidade-negocio/{id}/dadosAtualizar dados cadastrais
GET/unidade-negocio/{id}/contatoContatos da UN
PATCH/unidade-negocio/{id}/contatoAtualizar contatos
GET/unidade-negocio/{id}/personalizacaoLogos, cores
PATCH/unidade-negocio/{id}/personalizacaoAtualizar personalização
POST/unidade-negocioCria nova UN
PATCH/unidade-negocio/{id}/ativarAtiva UN
PATCH/unidade-negocio/{id}/inativarInativa UN
DELETE/unidade-negocio/{id}Remove UN
GET/unidade-negocio/filtrosValores possíveis para filtros (segmento, etc.)

Departamento

MétodoRotaDescrição
GET/departamentosLista 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/importImport 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:
  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)

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