> ## Documentation Index > Fetch the complete documentation index at: https://developers.pontua.com.br/llms.txt > Use this file to discover all available pages before exploring further. # Estrutura Organizacional > Hierarquia de Unidades de Negócio, Departamentos, Equipes, Cargos, Centros de Custo e Locais de Trabalho — base para alocação de colaboradores e relatórios gerenciais. 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](/referencia/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 /` — lista * `GET //{id}` — detalhe * `POST /` — criar * `PATCH //{id}` — atualizar * `DELETE //{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](/api-reference). ## 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: ```javascript theme={null} // 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) ```javascript theme={null} 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) ```javascript theme={null} // 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 * [Colaboradores](/referencia/colaboradores) — alocação depende dessa estrutura * [Turnos e Calendário](/referencia/turnos-e-calendario) — turnos são vinculados por cargo ou colaborador * [Folha de Pagamento](/referencia/folha-de-pagamento) — Centro de Custo alimenta apropriação contábil