API de Colaboradores — dados do eSocial

Base: https://central.proocupacional.com.br/api
Versão: 11/11/2026 · Nova Central do Cliente (beta)

A API mostra os colaboradores de cada cliente com os dados do contrato (matrícula, cargo, CBO, admissão e demissão) já no valor mais confiável disponível. Ela também permite atualizar esses dados sem depender do SOC ou do SGG, de duas formas:

1. Corrigir ou completar um colaborador (PUT). O dado entra como fonte CLIENTE.
2. Enviar o relatório oficial do eSocial (POST /colaboradores/esocial). É o CSV "Relação de Trabalhadores" que o próprio cliente baixa no portal do eSocial com o certificado da empresa. O dado entra como fonte ESOCIAL, a de maior prioridade.

#1. Autenticação

A API usa a mesma sessão da Central, um cookie ncp.auth válido por 12 horas e renovado com o uso.

CopiarPOST /api/login
Content-Type: application/json

{ "Email": "usuario@empresa.com.br", "Senha": "••••••" }

Para sair: POST /api/logout.

Sem o cookie, toda rota abaixo responde 401.

#1.1 Token de integração (para sistemas)

Um sistema de fora (folha, contabilidade, robô do cliente) usa um token em vez do login de tela. O token vai em todas as chamadas, no cabeçalho:

CopiarAuthorization: Bearer pro_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

• Quem cria o token é a equipe Pró. Cada token tem um nome (para quem é), um escopo e uma de duas permissões: somente leitura ou leitura e atualização. O escopo pode ser todas as empresas ou as empresas de um usuário da Central. O token também pode ter validade em dias.
• O token aparece uma única vez, na criação. A Pró guarda só uma impressão digital dele (hash SHA-256) e não consegue mostrar de novo. Se perder, é preciso criar outro e revogar o antigo.
• O token só vale nas rotas /api/empresas… e /api/colaboradores…. Qualquer outra rota da Central recusa o token com 401.
• Token somente leitura em rota de atualização recebe 403 "Este token e somente leitura."
• Token revogado, vencido ou de usuário desativado recebe 401.

Na Central: menu Gestão › Tokens de API, visível só para a equipe Pró. A tela cria o token (nome, escopo, permissão e validade), mostra o token uma vez com botão de copiar, lista os tokens com o último uso e a quantidade de usos, e revoga.

As mesmas ações pela API (só a equipe Pró, logada na tela):

Escopo: cada usuário vê e altera somente os clientes e unidades liberados no cadastro de acesso dele. Um colaborador fora do escopo responde como se não existisse (404 ou 400 "fora do seu acesso"). A equipe Pró vê todos os clientes.

#2. De onde vem cada dado (fontes e prioridade)

Cada campo guarda a sua fonte, devolvida pela API nos campos *Fonte:

Regras de atualização:

• Matrícula, admissão e demissão são fatos do contrato. Uma fonte de prioridade igual ou maior substitui o valor. Uma fonte menor só preenche se o campo estiver vazio. Exemplo: o cliente não consegue trocar uma matrícula que veio do eSocial. A resposta explica isso em NaoAplicado.
• Cargo e CBO mudam com o tempo. Vale o de vigência mais recente:
• no eSocial, a vigência é a data da última alteração contratual (ou a admissão, se não houver alteração);
• numa alteração feita pelo cliente, é a data em que ele alterou.

Se o cliente muda o cargo hoje, o novo cargo vale até chegar um relatório do eSocial com alteração posterior. Em caso de empate na data, vale a fonte de maior prioridade.

• Toda alteração fica no histórico, com o valor anterior, o novo, a fonte e a referência (quem alterou ou qual arquivo trouxe).
• Quando o eSocial confirma o mesmo valor que o cliente informou, a fonte passa a ser ESOCIAL e o valor não muda.

#3. Endpoints

#3.0 Empresas

Uma empresa é um cliente da Pró, identificado pela raiz do CNPJ (8 dígitos). As unidades são os estabelecimentos dela (CNPJ completo).

CopiarGET /api/empresas?busca=&comTotais=false&comEstabelecimentos=false&todas=false&pagina=1&tamanho=100

Por padrão, vêm só as empresas com pelo menos um colaborador ativo (ativo, afastado ou em férias). São cerca de 14 mil das 19 mil cadastradas; as demais são clientes antigos ou avulsos sem ninguém ativo. Use todas=true para trazer todas. A base junta os clientes do SOC, os do cadastro da Pró (que também vêm do SOC) e os do SGG.

Cada empresa traz CnpjRaiz (8 dígitos) e CnpjMatriz (14 dígitos: o estabelecimento ativo de menor CNPJ, o 0001 quando existe). Com comEstabelecimentos=true, traz também Estabelecimentos: a lista dos CNPJs completos de todos os estabelecimentos ativos que o token enxerga. O CnpjMatriz vem vazio para empregador pessoa física, cadastrado por CPF.

Fluxo para um sistema de eSocial:

1. GET /api/empresas?comEstabelecimentos=true&tamanho=500, página a página, para pegar todas as empresas do token com os CNPJs.
2. Para cada empresa, chamar GET /api/empresas/cnpj/{CnpjRaiz}/colaboradores?tamanho=1000 para trazer a empresa inteira. Para um estabelecimento só, use o CNPJ de 14 dígitos dele. Cada colaborador traz UnidadeCnpj, o estabelecimento onde trabalha.
3. Nas rodadas seguintes, use alteradosDesde (ver "Sincronização").

Os nomes saem sem os espaços sobrando que existem no cadastro de origem.

Copiar{ "Total": 14102,
  "Itens": [ { "ClienteId": 10, "CnpjRaiz": "11222333", "CnpjMatriz": "11222333000101", "Nome": "EMPRESA EXEMPLO LTDA", "NomeFantasia": "Exemplo",
               "Estabelecimentos": ["11222333000101", "11222333000202"],
               "Ativo": true, "Unidades": 7, "UltimoArquivoEsocial": "2026-11-11T10:58:03",
               "Ativos": 224, "SemMatricula": 1, "SemCargo": 0, "SemCbo": 219, "SemAdmissao": 0 } ],
  "Pagina": 1, "Tamanho": 100 }

Os campos Ativos a SemAdmissao só vêm com comTotais=true.

CopiarGET /api/empresas/{clienteId}

Devolve Empresa (os dados acima, mais CNAE e grau de risco) e Unidades. Cada unidade traz UnidadeId, Tipo (J para CNPJ ou F para CPF), Inscricao (o CNPJ completo), RazaoSocial, NomeUnidade, Cidade, Uf e Ativo. O UnidadeId é o que se usa para cadastrar colaborador novo.

CopiarGET /api/empresas/{clienteId}/colaboradores?unidadeId=&situacao=&pendencia=&busca=&pagina=1&tamanho=500

Lista todos os colaboradores da empresa, com até 1000 por página. A resposta e os filtros são os mesmos da lista geral (3.1). Cada item traz também ClienteId e UnidadeCnpj.

Para percorrer tudo: chame GET /api/empresas para pegar as empresas. Depois, para cada empresa, chame GET /api/empresas/{id}/colaboradores?pagina=1,2,3… até somar o Total.

#Pelo CNPJ (recomendado para sistemas de eSocial)

Se o sistema conhece a empresa pelo CNPJ, use estas rotas e não precisa do ClienteId:

CopiarGET /api/empresas/cnpj/{cnpj}
GET /api/empresas/cnpj/{cnpj}/colaboradores?alteradosDesde=&situacao=&pendencia=&pagina=1&tamanho=1000

• {cnpj} vai só com números. A barra de 0001/… quebra o endereço; pontos funcionam, mas é melhor evitar.
• 8 dígitos (raiz) traz a empresa inteira, com todos os estabelecimentos.
• 14 dígitos traz só aquele estabelecimento. Na resposta de /empresas/cnpj/{cnpj} vem SoEsteEstabelecimento: true.
• CNPJ fora do escopo do token ou inexistente devolve 404.

#Sincronização: só o que mudou (alteradosDesde)

Cada colaborador traz AlteradoEm, a última vez que mudou o contrato, o cadastro próprio, o eSocial ou a pessoa. A resposta traz ConsultadoEm, a hora do servidor no começo da consulta.

Rotina recomendada:

1. Primeira carga: chame sem alteradosDesde, percorra as páginas e guarde o ConsultadoEm da primeira página.
2. Próximas rodadas: chame com alteradosDesde=<ConsultadoEm guardado>. Vêm só as admissões, demissões e alterações desde então, ordenadas por AlteradoEm. Guarde o novo ConsultadoEm.
3. Uma rodada por dia costuma bastar. A carga interna do SOC/SGG roda a cada 30 minutos.

Se houver uma recarga completa do cadastro de origem, muitos colaboradores podem aparecer como alterados de uma vez, mesmo sem mudança real. Trate a sincronização como "atualizar se diferente", não como "evento novo".

#Campos para montar os eventos do eSocial

Além dos campos da lista (3.1), cada colaborador traz:

#3.1 Listar colaboradores

CopiarGET /api/colaboradores?clienteId=&cnpj=&unidadeId=&busca=&situacao=&pendencia=&alteradosDesde=&pagina=1&tamanho=25

Sem clienteId, cnpj ou unidadeId, a lista traz todos os colaboradores do acesso. Para um usuário de uma empresa é a empresa dele; para a equipe Pró ou um token "todas as empresas" é a base inteira, que é mais lenta. Para integração, filtre sempre por empresa.

Resposta 200:

Copiar{
  "Kpis": {
    "Total": 1240, "Ativos": 1102,
    "SemMatricula": 37, "SemCargo": 0, "SemCbo": 214, "SemAdmissao": 12,
    "ConferidosNoEsocial": 1180, "Divergentes": 41, "DesligadosNoEsocial": 6,
    "Completos": 1015, "UltimoArquivoEsocial": "2026-11-11T10:58:03"
  },
  "Total": 41,
  "Itens": [
    {
      "VinculoId": 1844, "VinculoCadastroId": 26, "PessoaId": 2066,
      "Nome": "Fulana de Tal", "Cpf": 12345678909,
      "UnidadeId": 54, "Unidade": "EMPRESA EXEMPLO - FILIAL BH", "Setor": "Operação",
      "Matricula": "004587", "MatriculaFonte": "ESOCIAL",
      "Cargo": "Operadora de caixa", "Cbo": "421125", "CargoFonte": "ESOCIAL",
      "DataAdmissao": "2021-03-14T00:00:00", "AdmissaoFonte": "ESOCIAL",
      "DataDemissao": null, "DemissaoFonte": null,
      "Situacao": 1,
      "NoEsocial": true, "Divergencias": 2, "DesligadoNoEsocial": false, "Completo": true
    }
  ],
  "Pagina": 1, "Tamanho": 25
}

• Os Kpis contam o escopo inteiro, antes do filtro pendencia, para mostrar o tamanho do problema. O Total conta o resultado já filtrado.
• VinculoId é o vínculo no cadastro de origem. Quando vem null, o colaborador só existe no cadastro próprio (cadastrado pela API ou vindo do eSocial antes do SOC/SGG). Nesse caso use as rotas /cadastro/{VinculoCadastroId}.
• Divergencias é a quantidade de campos em que o eSocial difere do cadastro de origem (matrícula, cargo, CBO, admissão e desligamento). Vem null quando o colaborador ainda não apareceu em nenhum relatório do eSocial.

#3.2 Detalhe de um colaborador

CopiarGET /api/colaboradores/{vinculoId}
GET /api/colaboradores/cadastro/{vinculoCadastroId}

Resposta 200:

Copiar{
  "Colaborador": { "...": "mesmos campos da lista + Cliente, DataNascimento, Sexo, Funcao, MotivoDemissao, OrigemVinculo" },
  "Esocial": [
    { "EsocialVinculoId": 1, "Matricula": "004587", "DataAdmissao": "2021-03-14T00:00:00", "DataDesligamento": null,
      "CodCategoria": "101", "Categoria": "Empregado - Geral", "Cargo": "Operadora de caixa", "CboCargo": "421125",
      "EstabelecimentoInscricao": 11222333000505, "DataUltAlteracao": "2024-02-01T00:00:00",
      "Arquivo": "relacao_trabalhadores.csv", "ImportadoEm": "2026-11-11T10:58:03", "EsteContrato": true }
  ],
  "Divergencias": [ { "Esocial_Matricula": "004587", "Cadastro_Matricula": "4587", "MatriculaDifere": true, "...": "..." } ],
  "Historico": [
    { "Campo": "Cargo", "ValorAntes": "Auxiliar de loja | CBO 521110", "ValorDepois": "Operadora de caixa | CBO 421125",
      "FonteAntes": "CLIENTE", "Fonte": "ESOCIAL", "Referencia": "ESOCIAL:arquivo 12", "Em": "2026-11-11T10:58:03" }
  ]
}

• Esocial traz o que o governo tem para esse CPF nesse empregador. Pode ter mais de um contrato. EsteContrato marca o que corresponde a este vínculo.
• Divergencias compara o eSocial com o cadastro de origem (SOC/SGG).

404 quando o colaborador não existe ou está fora do escopo.

#3.3 Corrigir ou completar

CopiarPUT /api/colaboradores/{vinculoId}
PUT /api/colaboradores/cadastro/{vinculoCadastroId}
Content-Type: application/json

{
  "Matricula": "004587",
  "Cargo": "Operadora de caixa",
  "Cbo": "4211-25",
  "DataAdmissao": "2021-03-14",
  "DataDemissao": null,
  "MotivoDemissao": null
}

Todos os campos são opcionais: envie só o que quer alterar. O CBO aceita 4211-25 ou 421125.

Resposta 200:

Copiar{ "Ok": 1, "VinculoCadastroId": 26, "VinculoId": 1844, "Alteracoes": 1,
  "NaoAplicado": "Matricula mantida em 004587 (informada pelo ESOCIAL). " }

• Alteracoes é a quantidade de campos que mudaram de fato.
• NaoAplicado lista o que foi pedido e não entrou porque uma fonte mais forte vale mais. Vem null quando tudo foi aplicado.

Erros 400 ({ "erro": "..." }):

#3.3.1 Atualizar em lote (integração)

CopiarPUT /api/colaboradores/lote
Authorization: Bearer pro_...
Content-Type: application/json

{
  "Itens": [
    { "Cpf": "390.533.447-05", "Cnpj": "11.222.333/0001-01", "Cargo": "Assistente administrativo", "Cbo": "4110-05" },
    { "Cpf": "12345678909", "ClienteId": 10, "MatriculaAtual": "004587", "DataDemissao": "2026-11-05", "MotivoDemissao": "02 - Rescisao sem justa causa" },
    { "VinculoId": 1585, "Matricula": "M1807" },
    { "Cpf": "11144477735", "ClienteId": 10, "CriarSeNaoExistir": true, "Nome": "Novo Colaborador", "UnidadeId": 54,
      "DataAdmissao": "2026-11-02", "Matricula": "L-9", "Cargo": "Auxiliar", "Cbo": "514320" }
  ]
}

São até 500 itens por chamada. Cada item indica quem é o colaborador por uma destas formas:

E diz o que atualizar, com os mesmos campos do PUT (3.3): Matricula, Cargo, Cbo, DataAdmissao, DataDemissao e MotivoDemissao. As mesmas regras de prioridade valem.

Com CriarSeNaoExistir: true, um CPF que não existe na empresa é cadastrado como colaborador novo. Para isso o item precisa de Nome, UnidadeId e DataAdmissao.

Resposta 200, item a item, na mesma ordem do envio:

Copiar{ "Total": 4, "Ok": 3, "Erros": 1,
  "Itens": [
    { "Indice": 0, "Ok": true, "Acao": "atualizado", "VinculoId": 1843, "VinculoCadastroId": 31, "Alteracoes": 2, "NaoAplicado": null,
      "MesmoContrato": 2, "VinculosMesmoContrato": "1907,2210", "Erro": null },
    { "Indice": 1, "Ok": false, "Erro": "Mais de um contrato para esse CPF: informe a matricula." },
    { "Indice": 2, "Ok": true, "Acao": "atualizado", "VinculoId": 1585, "Alteracoes": 0, "NaoAplicado": "Matricula mantida em M1807 (informada pelo ESOCIAL). " },
    { "Indice": 3, "Ok": true, "Acao": "criado", "VinculoId": null, "VinculoCadastroId": 54, "Alteracoes": 3 }
  ] }

Um item com erro não impede os outros. Corrija e reenvie só os itens que falharam.

#O mesmo contrato em mais de um vínculo

Na lista, a mesma pessoa pode aparecer mais de uma vez na mesma empresa com a mesma matrícula, cada vez numa unidade, com o mesmo PessoaId e VinculoId diferentes. Não são contratos diferentes: é o mesmo contrato que chegou à Pró por mais de um sistema de origem, ou que ficou na loja antiga depois de uma transferência. Para o eSocial, matrícula é única por empregador.

Por isso:

• Mande um item só por contrato, usando qualquer um dos VinculoId com aquela matrícula. A API aplica a mesma atualização em todos os vínculos da pessoa com a mesma matrícula na mesma empresa (raiz do CNPJ).
• A resposta diz quantos e quais vínculos também foram atualizados: MesmoContrato (quantidade) e VinculosMesmoContrato (ids separados por vírgula).
• No envio por CPF, se todos os vínculos do CPF na empresa têm a mesma matrícula, a API não pede MatriculaAtual: é um contrato só.
• Matrículas diferentes para o mesmo CPF continuam sendo contratos separados: um item por VinculoId (ou por CPF + MatriculaAtual).

Exemplo: a pessoa tem os vínculos 231003, 235280 e 253612, todos com matrícula 67682. Um item com "VinculoId": 231003 e a admissão do eSocial corrige os três. A resposta traz "MesmoContrato": 2, "VinculosMesmoContrato": "235280,253612".

#3.4 Cadastrar colaborador novo

CopiarPOST /api/colaboradores
Content-Type: application/json

{
  "Cpf": "529.982.247-25",
  "Nome": "Novo Colaborador",
  "UnidadeId": 54,
  "Matricula": "N-001",
  "Cargo": "Auxiliar de serviços gerais",
  "Cbo": "514320",
  "DataAdmissao": "2026-11-01"
}

Cpf (válido), Nome, UnidadeId (do seu escopo) e DataAdmissao são obrigatórios. A resposta é igual à do PUT, com VinculoId: null. O colaborador passa a aparecer na lista na hora, mesmo antes de existir no SOC ou no SGG.

O cadastro é recusado quando o mesmo CPF já está ativo no cliente com a mesma admissão ou a mesma matrícula. Nesse caso, a mensagem orienta a abrir o cadastro existente.

#3.5 Enviar o relatório do eSocial (CSV)

O cliente baixa o relatório no portal do eSocial, com o certificado da própria empresa:

1. Acesse login.esocial.gov.br e entre com o certificado digital.
2. Abra o card Emissão de Relatórios Gerenciais.
3. Clique em Solicitar Novo Relatório, escolha "Relação de Trabalhadores – eSocial" e marque "Todos os vínculos".
4. O relatório fica pronto em alguns minutos ou horas. Quando a situação for Processado, baixe em CSV.

Depois envie o arquivo:

CopiarPOST /api/colaboradores/esocial
Content-Type: multipart/form-data

arquivo=<relacao_trabalhadores.csv>

Resposta 200:

Copiar{
  "Resultado": { "Ok": 1, "EsocialArquivoId": 10, "Cliente": "EMPRESA EXEMPLO LTDA",
                 "Linhas": 1240, "Inseridas": 12, "Atualizadas": 1228, "Vinculadas": 1180, "Rejeitadas": 3,
                 "AlteracoesNoCadastro": 57 },
  "ColunasNaoEncontradas": []
}

Regras do envio:

• Aceita apenas CSV, de até 200 MB (o portal gera até 500 mil linhas em CSV). O separador pode ser ;, , ou TAB, e a codificação UTF-8 ou Windows-1252. Linhas de título antes do cabeçalho são ignoradas.
• As colunas obrigatórias são Número de Inscrição do Empregador, CPF do Trabalhador, Matrícula e Data de Admissão.
• O empregador do arquivo precisa ser um cliente do escopo de quem envia. Caso contrário, nada é importado: 400 "O arquivo e de uma empresa que nao esta no seu acesso." Linhas de outro empregador dentro do mesmo arquivo são descartadas.
• O mesmo arquivo não entra duas vezes (a comparação é pelo conteúdo): 400 "Esse arquivo ja foi importado em dd/mm/aaaa." Um relatório novo, mesmo com o mesmo nome, é aceito normalmente.
• Os vínculos que existem no eSocial e ainda não estão no cadastro entram como colaboradores novos.

#3.6 Arquivos enviados

CopiarGET /api/colaboradores/esocial/arquivos

Devolve os últimos 50 envios do escopo, com EsocialArquivoId, NomeArquivo, Cliente, Linhas, Inseridas, Atualizadas, Vinculadas, Rejeitadas, Situacao (Importado · Erro · Carregando), Erro e ImportadoEm.

#4. Exemplos com curl

Copiar# login (guarda o cookie em cookies.txt)
curl -c cookies.txt -H "Content-Type: application/json" \
     -d '{"Email":"usuario@empresa.com.br","Senha":"SUA_SENHA"}' \
     https://central.proocupacional.com.br/api/login

# ativos sem CBO
curl -b cookies.txt "https://central.proocupacional.com.br/api/colaboradores?situacao=1&pendencia=SemCbo&tamanho=100"

# corrigir cargo e CBO
curl -b cookies.txt -X PUT -H "Content-Type: application/json" \
     -d '{"Cargo":"Operadora de caixa","Cbo":"4211-25"}' \
     https://central.proocupacional.com.br/api/colaboradores/1844

# enviar o relatório do eSocial
curl -b cookies.txt -F "arquivo=@relacao_trabalhadores.csv" \
     https://central.proocupacional.com.br/api/colaboradores/esocial

Com token de integração (sem login):

CopiarTOKEN="pro_..."

# empresas do escopo do token
curl -H "Authorization: Bearer $TOKEN" "https://central.proocupacional.com.br/api/empresas?tamanho=500"

# colaboradores de uma empresa (página 1, 1000 por página)
curl -H "Authorization: Bearer $TOKEN" "https://central.proocupacional.com.br/api/empresas/10/colaboradores?tamanho=1000&pagina=1"

# pelo CNPJ: empresa inteira (raiz) e só o que mudou desde a última rodada
curl -H "Authorization: Bearer $TOKEN" "https://central.proocupacional.com.br/api/empresas/cnpj/11222333/colaboradores?tamanho=1000&alteradosDesde=2026-11-10T08:00:00"

# só um estabelecimento (CNPJ completo, só números)
curl -H "Authorization: Bearer $TOKEN" "https://central.proocupacional.com.br/api/empresas/cnpj/11222333000505/colaboradores?tamanho=1000"

# atualização em lote
curl -X PUT -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
     -d '{"Itens":[{"Cpf":"39053344705","Cnpj":"11222333","Cargo":"Assistente administrativo","Cbo":"411005"}]}' \
     https://central.proocupacional.com.br/api/colaboradores/lote

#5. Códigos de resposta

#6. Referência técnica (equipe Pró)

Por que o caminho é o CSV, e não a busca automática no eSocial: o webservice oficial permite só 10 chamadas por dia por empregador, com um CPF por consulta. O portal exige hCaptcha no login, e automação ali não é permitida. O relatório "Relação de Trabalhadores" é a única forma oficial de obter todos os vínculos de uma vez.