Sincronizar colaboradores com o ERP

O cadastro de pessoas mora no ERP ou na folha de outro sistema, e a TAI precisa dele para ponto, desempenho, treinamentos e processos. A jornada tem três tempos: a carga inicial (estrutura e depois colaboradores, sem disparar e-mails), a atualização incremental (só o que mudou) e a conciliação periódica, que confere os dois lados.

Quando usar	O ERP ou a folha externa é a fonte do cadastro e a TAI deve espelhá-lo
Porta	REST · Webhook (no sentido contrário)
Você vai precisar	Módulos ORGANIZACAO e PESSOAS; permissões SETOR, DEPARTAMENTO, SUBDEPARTAMENTO, CARGO e COLABORADOR com edição; um usuário de integração

Como funciona

O colaborador pertence a uma empresa e ocupa um cargo dentro de um departamento. Por isso a carga segue a ordem da estrutura, e a chave que liga os dois lados é a matrícula do seu sistema, gravada em codigoFuncionario.

ERP ──► GET /empresa                              (ids dos CNPJs)
ERP ──► POST /setor → /departamento → /cargo      (estrutura, de cima para baixo)
ERP ──► POST /colaborador  enviarEmail:false      (carga inicial, codigoFuncionario = matrícula)
ERP ──► PATCH /colaborador                        (só o que mudou)
ERP ◄── GET /colaborador/page                     (conciliação periódica)

Passo a passo

1. Descubra a empresa. Empresas são os estabelecimentos (CNPJs) da conta.

   GET /empresa

   Guarde o id da empresa de cada colaborador.

2. Monte a estrutura. Crie setores, departamentos, times e cargos de cima para baixo e guarde os ids, ou reaproveite os que já existem. O passo a passo, com responsáveis e chaves de correspondência, está em Estrutura organizacional.

   POST /setor
   { "nome": "Administrativo", "codigo": "ADM", "empresa": { "id": 3 } }
   
   POST /departamento
   { "nome": "Recursos Humanos", "codigo": "ADM-RH", "setor": { "id": 21 } }
   
   POST /cargo
   { "nome": "Analista de RH", "codigo": "C-114", "departamento": { "id": 40 } }

3. Carregue os colaboradores com "enviarEmail": false, para que ninguém receba a senha antes do lançamento. Grave a matrícula do seu sistema em codigoFuncionario.

   curl -X POST https://api.taitecnologia.com/colaborador \
     -H "Authorization: Bearer $TAI_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "nome": "Ana Ribeiro",
       "codigoFuncionario": "000123",
       "emailCorporativo": "ana.ribeiro@suaempresa.com.br",
       "cpf": "12345678909",
       "dataNascimento": "1992-04-18",
       "dataAdmissao": "2024-03-04",
       "tipoContrato": "CLT",
       "empresa": { "id": 3 },
       "departamento": { "id": 40 },
       "cargo": { "id": 77 },
       "enviarEmail": false
     }'

   A resposta traz o colaborador gravado. Guarde o id da TAI ao lado da matrícula no seu sistema: é ele que as próximas chamadas usam.

4. Atualize só o que mudou. PATCH grava apenas os campos enviados; o id vai no corpo.

   PATCH /colaborador
   Content-Type: application/json
   
   { "id": 1043, "cargo": { "id": 78 }, "telefone": "31988887777" }

   O PUT substitui o registro inteiro — um campo omitido pode ser apagado. Para integração, prefira sempre o PATCH.

5. Concilie de tempos em tempos. Leia a lista paginada e compare com o seu cadastro pela matrícula ou pelo id guardado.

   GET /colaborador/page?page=0&size=100&sort=id,asc

   Avance page até last ser true. Os desligados não vêm nessa lista: leia-os em GET /colaborador/desligados/page.

O que acontece no cadastro

• O colaborador ganha um usuário para entrar na plataforma. O login é o emailCorporativo ou, sem ele, o emailPessoal — um dos dois é obrigatório.
• Com "enviarEmail": true (o padrão), um e-mail de boas-vindas com a senha inicial é enviado quando o login é novo na TAI. Com false, ninguém é avisado; no lançamento, envie a senha com POST /user/reset-password e {"identifier": "<e-mail>"} (permissão USUARIO).
• Se o e-mail já tem usuário em outra conta da TAI, o colaborador reaproveita a mesma senha.
• Um e-mail que já pertence a um colaborador ativo nesta conta é recusado com 400.
• O usuário criado tem o papel de colaborador (CUSTOMER_EMPLOYEE); o que ele acessa vem dos perfis de acesso.
• Cada cadastro publica o evento Um colaborador é cadastrado (COLABORADOR_CRIADO) — veja Contas para quem chega.

Achar um colaborador pela chave do seu sistema

Pela matrícula

search procura texto nos campos indexados do colaborador — nome, CPF, e-mails, codigoFuncionario, codigoPosicao, matrícula do eSocial. A busca é por trecho: confira o valor exato de codigoFuncionario na resposta.

GET /colaborador/page?search=000123&size=20

Pelo CPF

Devolve o id e o nome do colaborador com aquele CPF nesta conta.

GET /colaborador/buscar-por-cpf/12345678909

Campos

ColaboradorDTO tem mais de cem campos — documentos, endereço, dados do eSocial, jornada, deficiência, desligamento. A lista completa, com tipos e valores aceitos, está na referência de Colaboradores. Alguns que aparecem com frequência:

Campo	Tipo	Observação
codigoFuncionario	texto	Matrícula no seu sistema — a chave de correspondência
tipoContrato	lista	CLT, PJ, ESTAGIO, TEMPORARIO, TERCEIRIZADO, APRENDIZ, INTERMITENTE, SOCIO_SERVICO
regimeTrabalho	lista	INTEGRAL, PARCIAL, PRESENCIAL, REMOTO, HIBRIDO
dataAdmissao, dataNascimento	data	Envie como yyyy-MM-dd — veja datas
empresa, departamento, cargo	referência	Objetos com id
subDepartamento, centroCusto	referência	Objetos com id (o time e o centro de custo)
movimentacaoSalarialAtual	leitura	O salário vigente — veja Movimentações e salário

Muitas pessoas de uma vez

POST /colaborador/batch recebe uma lista, mas o corpo inteiro precisa caber em 8 KB — veja limites. Na prática, mande poucos colaboradores por lote, ou um por chamada. Para centenas de pessoas numa carga única, a tela Organização → Colaboradores → Importar aceita uma planilha de até 1.000 linhas, com prévia antes de gravar.

Automatize

O ERP manda para a TAI pela API. No sentido contrário — a TAI avisando o ERP do que mudou na plataforma —, crie um webhook que assine:

Evento	Quando
COLABORADOR_CRIADO	Um colaborador é cadastrado, venha de onde vier
COLABORADOR_ALTERADO	A ficha é editada; origem diz onde: FICHA (inclui PUT/PATCH pela API), CONTATOS ou TIME
COLABORADOR_DESLIGADO	O desligamento fica efetivo
MOVIMENTACAO_SALARIAL_CRIADA	Uma promoção, reajuste ou outra movimentação salarial é registrada

Os eventos trazem colaboradorId, colaboradorNome e gestorId; com Enviar também o registro completo, a ficha vem junto em registro. Os campos de cada um estão no catálogo.

{
  "id": "evt_53002",
  "tipo": "COLABORADOR_ALTERADO",
  "descricao": "A ficha de um colaborador é alterada",
  "versao": 1,
  "ocorridoEm": "2026-10-06T14:22:10.084Z",
  "empresa": { "id": 12, "nome": "Sua Empresa Ltda" },
  "dados": {
    "colaboradorId": 1043,
    "colaboradorNome": "Ana Ribeiro",
    "gestorId": 1544,
    "origem": "FICHA"
  }
}

Mantenha a conciliação do passo 5 como rede: as novas tentativas cobrem quedas de horas, não de dias.

O eco das suas próprias mudanças

O PATCH que o ERP faz também publica A ficha de um colaborador é alterada. Se o ERP assina esse evento, ele recebe de volta o que acabou de mandar: compare o registro (ou o GET /colaborador/{id}) com o que já tem e ignore quando não há diferença, para não entrar num ciclo de atualizações.

Pelo seu agente de IA

Com o agente conectado por MCP, “quantos colaboradores ativos temos por departamento?” é uma leitura — o agente usa analisar_dados ou a contagem por departamento. “Cadastre a Ana Ribeiro como analista de RH, admitida em 04/03/2024” é uma escrita: exige credencial com escopo de escrita e a sua aprovação no cliente de IA.

Cuidados

• Chave de correspondência. Nada impede dois colaboradores com a mesma matrícula ou o mesmo CPF na conta. A unicidade é responsabilidade da integração: procure antes de criar.
• Idempotência. Repetir um POST /colaborador com o mesmo e-mail é recusado com 400 enquanto o primeiro estiver ativo; com outro e-mail, cria uma segunda pessoa. Trate o id guardado como a prova de que o colaborador já existe.
• Campo escrito errado não dá erro — o valor só não é gravado. Confira os nomes na referência.
• Mudar emailCorporativo não muda o login do usuário já criado.
• Não desligue por PATCH. Use POST /colaborador/{id}/desligar — veja Desligamento. DELETE /colaborador/{id} é para cadastro feito por engano.
• Datas civis como yyyy-MM-dd (datas e formatos) e corpo até 8 KB (limites).