Espelhar a estrutura organizacional

A estrutura da TAI tem três níveis — setor → departamento → time — mais os cargos de cada departamento e os centros de custo de cada empresa. Ela decide duas coisas que as integrações costumam precisar: quem é o gestor de cada pessoa e onde cada pessoa aparece nos relatórios. Esta jornada espelha o organograma do ERP na TAI, ou faz o caminho contrário, para o BI.

Quando usar	O organograma nasce em outro sistema; ou o BI precisa da estrutura e dos gestores
Porta	REST · Webhook
Você vai precisar	Módulo ORGANIZACAO. Para escrever: permissões SETOR, DEPARTAMENTO, SUBDEPARTAMENTO, CARGO e CENTRO_CUSTO com edição. Para ler setores, departamentos, times e cargos basta estar autenticado

Como funciona

Não existe campo “gestor” no colaborador. O gestor é o responsável da unidade: cada setor, departamento e time tem um campo colaborador, e a cadeia de gestão de uma pessoa é o responsável do time dela, depois o do departamento, depois o do setor. É essa cadeia que dá o gestorId dos eventos, as aprovações do gestor e o que cada líder enxerga da equipe.

empresa ─► setor (responsável) ─► departamento (responsável) ─► time (responsável)
                                        └─► cargo ─► faixas salariais
empresa ─► centro de custo

A ordem da carga é de cima para baixo. Como o responsável é um colaborador, ele só pode ser apontado depois que os colaboradores existem.

Passo a passo

1. Crie os setores de cada empresa. Grave o identificador do seu sistema em codigo — é a chave de correspondência da estrutura.

   POST /setor
   Content-Type: application/json
   
   { "nome": "Operações", "codigo": "OPS", "empresa": { "id": 3 } }

2. Crie os departamentos e os times.

   POST /departamento
   { "nome": "Logística", "codigo": "OPS-LOG", "setor": { "id": 21 } }
   
   POST /sub-departamento
   { "nome": "Expedição", "codigo": "OPS-LOG-EXP", "departamento": { "id": 40 } }

3. Crie os cargos no departamento. O CBO entra por cboId: procure a ocupação em GET /cbo?termo=almoxarife e use o id dela.

   POST /cargo
   {
     "nome": "Conferente de Expedição",
     "codigo": "C-208",
     "nivelHierarquico": "PLENO",
     "departamento": { "id": 40 },
     "cboId": 1873
   }

   As faixas salariais do cargo, quando a sua política usa faixas, vão em POST /faixa-salarial com cargo, nivelHierarquico, salarioMinimo e salarioMaximo.

4. Crie os centros de custo, se a sua contabilidade os usa.

   POST /centro-custo
   { "nome": "Expedição SP", "codigo": "4.1.02", "empresa": { "id": 3 } }

5. Carregue os colaboradores apontando para essas unidades — veja Sincronizar colaboradores.

6. Aponte os gestores. Com os colaboradores criados, preencha o responsável de cada unidade.

   PATCH /departamento
   Content-Type: application/json
   
   { "id": 40, "colaborador": { "id": 1043 } }

   O mesmo vale para PATCH /setor e PATCH /sub-departamento. Trocar o responsável troca o gestor da equipe na hora.

Extrair a estrutura para o BI

Leia cada nível paginado e monte a árvore no seu lado pelos ids de pai:

GET /setor/page?page=0&size=200
GET /departamento/page?page=0&size=200      → cada item traz o setor
GET /sub-departamento/page?page=0&size=200  → cada item traz o departamento
GET /cargo/page?page=0&size=200             → cada item traz o departamento

Cada unidade traz colaborador com o id e o nome do responsável. Para o tamanho das equipes, GET /colaborador/contagem-por-departamento devolve o número de colaboradores ativos por departamento, com o setor de cada um, numa única consulta.

Nota

As respostas trazem objetos aninhados até o segundo nível — veja Padrão das rotas. Monte a árvore pelos id, não pelo objeto completo.

Saber quando a estrutura muda

Em vez de reler tudo a cada hora, assine num webhook os eventos de cadastro da estrutura: é cadastrado, é alterado (inclui ativar e desativar) e é excluído de departamento (DEPARTAMENTO_*), cargo (CARGO_*), centro de custo (CENTRO_CUSTO_*) e empresa (EMPRESA_*). Tudo de Organização assina todos de uma vez. O id vem como <entidade>Id:

{
  "id": "evt_53418",
  "tipo": "CARGO_ALTERADO",
  "descricao": "Um cargo é alterado",
  "versao": 1,
  "ocorridoEm": "2026-10-06T15:40:02.371Z",
  "empresa": { "id": 12, "nome": "Sua Empresa Ltda" },
  "dados": {
    "cargoId": 79,
    "nome": "Conferente de Expedição",
    "codigo": "C-208",
    "departamento_id": 40,
    "ativo": true
  }
}

Setores, times e faixas salariais não têm evento, e os dados do departamento não trazem o responsável: para o gestor de cada unidade, leia o registro pela API ou mantenha a releitura paginada acima de tempos em tempos.

Carga por planilha

Para uma carga única grande, POST /estrutura/importar/{tipo} recebe um .xlsx (até 1.000 linhas) para setor, departamento, subdepartamento, cargo ou centro-custo, e POST /estrutura/importar/{tipo}/previa mostra o resultado sem gravar. A planilha casa o pai pelo nome e ignora nomes que já existem — reimportar não duplica. O modelo sai em GET /estrutura/importar/{tipo}/modelo. Na tela, o caminho é Organização → Cadastros.

Pelo seu agente de IA

“Quem é o gestor da equipe de Expedição?” e “quantas pessoas tem cada departamento?” são leituras que o agente conectado por MCP responde. “Coloque a Ana Ribeiro como responsável pelo departamento de Logística” é uma escrita: exige escopo de escrita e a sua aprovação no cliente de IA.

Cuidados

• Nomes não são únicos. Nada impede dois cargos ou dois departamentos com o mesmo nome. Case pelo codigo (o seu identificador) ou pelo id guardado, nunca pelo nome. Para cargos, GET /cargo/codigo/{codigo} acha direto.
• search é por trecho e procura no nome e no código: confira o codigo exato na resposta.
• Responsável de si mesmo sobe um nível. Quando o responsável do time é a própria pessoa, o gestor dela é o responsável do departamento.
• Responsável desligado não conta: a cadeia pula para o nível de cima. Ao desligar um gestor, aponte o substituto.
• Ser gestor não depende do cargo. Um cargo de nível GERENTE não dá equipe a ninguém; o que dá é ser o responsável da unidade.
• Corpo até 8 KB por chamada (limites).