> ## Documentation Index
> Fetch the complete documentation index at: https://developers.tarefy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Dados pessoais e cadastro de RH

> Como consultar, cadastrar, atualizar e importar os dados pessoais dos colaboradores pela API.

A seção **Employee HR Data**, em **People, Performance & Culture**, documenta os dados usados no cadastro de dados pessoais do perfil (`/users/profile/{userId}`). Inclui identificação, documentos, endereço, contatos de emergência, contrato, formação e benefícios.

O identificador `userId` é o ID do usuário, não o ID do registro de RH. Nos exemplos, `2807` é ilustrativo: substitua pelo ID de um colaborador da sua conta. Os nomes e contatos dos exemplos são fictícios.

## Autenticação e permissões

Use a base `https://app.tarefy.com/nodeapi` e envie `Authorization: Bearer SEU_TOKEN`, conforme o [guia de autenticação](/authentication). A conta é determinada pela autenticação; não envie `account_id` no corpo.

Consulta, cadastro, atualização, download do modelo e importação exigem pelo menos uma das permissões **18 ou 19**, conforme a autorização da conta. Desativar o registro de RH exige **nível 5 (Super Admin)**. Ter acesso ao próprio perfil não substitui essas permissões.

A consulta aceita vínculos inativos para leitura de ex-colaboradores. Para gravar, o usuário e seu vínculo com a conta precisam estar ativos.

## Qual operação usar

| Objetivo                          | Método e caminho                           | Resultado                                                         |
| --------------------------------- | ------------------------------------------ | ----------------------------------------------------------------- |
| Consultar dados pessoais          | `GET /v2/employee-hr-data/{userId}`        | Perfil consolidado, com os dados disponíveis                      |
| Cadastrar dados de RH             | `POST /v2/employee-hr-data`                | Cria o registro ou atualiza o existente; exige `user_id` no corpo |
| Salvar alterações                 | `PUT /v2/employee-hr-data/{userId}`        | Atualiza o registro ou cria se ainda não existir                  |
| Desativar dados de RH             | `DELETE /v2/employee-hr-data/{userId}`     | Desativa o registro de RH na conta                                |
| Baixar modelo de importação       | `GET /v2/employee-hr-data/import/template` | Arquivo XLSX                                                      |
| Importar colaboradores existentes | `POST /v2/employee-hr-data/import`         | Resultado por lote e erros por linha                              |

Essas operações não criam novos usuários. Cadastre o colaborador e seu vínculo com a conta antes de enviar os dados pessoais.

## 1. Consultar o cadastro

```bash theme={null}
curl 'https://app.tarefy.com/nodeapi/v2/employee-hr-data/2807' \
  -H 'Authorization: Bearer SEU_TOKEN'
```

O GET reúne dados do perfil global, do vínculo com a conta e do cadastro de RH. Verifique `has_hr_data`:

* `true`: existe um registro ativo de RH na conta.
* `false`: o usuário pertence à conta, mas não tem registro ativo de RH. O retorno ainda pode conter nome, contato e outros dados disponíveis; campos exclusivos de RH podem estar ausentes.
* Corpo vazio com HTTP `200`: usuário inexistente ou sem vínculo com a conta autenticada. Não espere um `404` nesse caso.

`empresa` corresponde à conta autenticada. `salario` e `regime_trabalho` vêm do histórico salarial e retornam `null` sem permissão 18 ou sem valor disponível. `data_admissao` usa primeiro a data do cadastro de RH, com fallback para a data legada do perfil.

## 2. Salvar dados pessoais

O PUT é o fluxo usado pela tela para salvar. Envie apenas os campos que pretende modificar; os campos omitidos são preservados quando o registro já existe.

```bash theme={null}
curl -X PUT 'https://app.tarefy.com/nodeapi/v2/employee-hr-data/2807' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  --data '{
    "primeiro_nome": "Ana",
    "ultimo_nome": "Exemplo",
    "whatsapp": "+5511999999999",
    "data_nascimento": "1995-05-15",
    "endereco_completo": "Rua Exemplo",
    "numero": "100",
    "cidade": "São Paulo",
    "estado": "SP",
    "cep": "01001000",
    "data_admissao": "2026-09-01",
    "tipo_contrato": "CLT",
    "carga_horaria_semanal": 40,
    "vale_transporte": true
  }'
```

Para usar POST, envie o mesmo conteúdo para `/v2/employee-hr-data`, acrescentando `"user_id": 2807`. POST retorna `201`; PUT retorna `200`, inclusive quando cria o registro de RH.

<Note>
  A resposta de escrita é o registro de RH, não o perfil consolidado. Alguns valores podem estar criptografados e `observacoes` pode conter JSON interno. Após salvar, faça GET para obter os campos legíveis. Não reutilize a resposta bruta de escrita como payload de atualização.
</Note>

## Campos e efeitos da atualização

| Grupo                   | Campos principais                                                                                                              | Como enviar                                                                                     |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------- |
| Identificação e contato | `primeiro_nome`, `ultimo_nome`, `nome_registro`, `email`, `whatsapp`, `linkedin`, `data_nascimento`                            | Textos; nascimento em `YYYY-MM-DD`                                                              |
| Dados complementares    | `nome_pais`, `nome_mae`, `email_pessoal`, `titulo`, `escolaridade`, `estado_civil`, `departamento`                             | Textos; `nome_pais` é o nome histórico do campo de nome do pai e `titulo` é o título de eleitor |
| Documentos              | `cpf`, `rg`, `rg_orgao_emissor`, `rg_data_emissao`, `ctps`, `ctps_serie`, `pis`, `cnh`, `cnh_categoria`, `cnh_validade`        | Números de documentos como strings; datas em `YYYY-MM-DD`                                       |
| Endereço                | `endereco_completo`, `cep`, `cidade`, `estado`, `bairro`, `numero`, `complemento`                                              | Textos, inclusive número e CEP                                                                  |
| Emergência              | `contato_emergencia_nome`, `contato_emergencia_telefone`, `contato_emergencia_parentesco`                                      | Textos                                                                                          |
| Contrato                | `cargo`, `data_admissao`, `data_demissao`, `tipo_contrato`, `carga_horaria_semanal`, `data_validade_contrato`                  | Datas em `YYYY-MM-DD`; carga horária como inteiro                                               |
| Formação e PJ           | `previsao_formatura`, `nome_faculdade`, `curso`, `cnpj`, `razao_social`                                                        | Textos e data de formatura em `YYYY-MM-DD`                                                      |
| Benefícios              | `vale_transporte`, `vale_alimentacao`, `vale_refeicao`, `plano_saude`, `plano_odontologico`, `auxilio_creche`                  | Booleanos JSON `true` ou `false`, sem aspas                                                     |
| Complementos            | `outros_beneficios`, `numero_dependentes`, `dependentes_info`, `documentos_anexos`, `observacoes`, `observacoes_confidenciais` | Quantidade como inteiro; dependentes e anexos como objetos JSON; demais campos como texto       |
| Dados bancários do RH   | `banco`, `agencia`, `conta`, `conta_tipo`, `pix`                                                                               | Strings; não sincronizam automaticamente o cadastro bancário separado                           |

As páginas dos endpoints detalham cada propriedade. Considere também:

* **Perfil global:** nome, email, WhatsApp, LinkedIn e nascimento alteram o usuário global, que pode participar de várias contas. Os dados de RH e a associação de cargo são da conta atual.
* **Email de acesso:** deve ser válido, não vazio e não utilizado por outro usuário. `email_pessoal` é separado.
* **Cargo:** envie o nome exato de um cargo existente na conta. Nome não encontrado ou texto vazio remove a associação, sem criar um cargo.
* **Formatos:** WhatsApp deve incluir código do país. CPF, RG, PIS, CTPS e CEP passam por normalização de máscara. UF é convertida para maiúsculas e limitada a dois caracteres.
* **Campos que não são gravados:** `empresa`, `salario` e `regime_trabalho` são aceitos por compatibilidade, mas não são alterados por POST/PUT de RH. Não use esse payload para reajuste salarial.
* **Limpeza de campos:** omitir preserva o valor; não existe uma regra uniforme de limpeza por `null` ou `""` para todos os campos. Datas devem seguir o formato documentado.
* **Anexos:** `documentos_anexos` recebe metadados JSON; não é upload de arquivo. Para arquivos do colaborador, use as operações de User Documents.
* **Falhas de escrita:** não há garantia de transação única entre perfil, cargo e RH. Após uma falha, consulte o estado atual antes de reenviar.

## Importação em lote

1. Baixe o modelo XLSX pelo endpoint `/v2/employee-hr-data/import/template`.
2. Substitua a linha de exemplo. Preencha `EMAIL` com o email de acesso de um colaborador existente na conta.
3. Mantenha os cabeçalhos do modelo. O email identifica o colaborador; a importação não altera esse email nem cria usuários.
4. Envie o arquivo no campo `file` de um formulário multipart.

```bash theme={null}
curl 'https://app.tarefy.com/nodeapi/v2/employee-hr-data/import/template' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -o modelo-dados-pessoais.xlsx

curl -X POST 'https://app.tarefy.com/nodeapi/v2/employee-hr-data/import' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -F 'file=@colaboradores.xlsx;type=application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'
```

São aceitos CSV, XLSX e XLS, até **10 MiB**. No Excel, somente a primeira aba é lida. Células vazias não apagam valores existentes. Para documentos, CEP e contas bancárias, use células de texto para preservar zeros iniciais. Datas no modelo podem seguir o exemplo `DD/MM/YYYY`.

Prefira XLSX. O leitor CSV atual usa vírgulas como separadores e não suporta vírgulas dentro de valores, mesmo entre aspas, nem quebras de linha em células.

<Note>
  O modelo contém também as colunas legadas `CELULAR`, `CELULAR_ALTERNATIVO`, `ANIVERSARIO` e `SEXO`, que não são mapeadas pelo importador atual. Use `WHATSAPP` para telefone e `DATA_NASCIMENTO` para nascimento. As colunas bancárias são enviadas ao cadastro bancário separado, diferentemente dos campos bancários do POST/PUT de RH.
</Note>

Uma resposta HTTP `201` indica que o lote foi processado, mas não garante sucesso de todas as linhas:

```json theme={null}
{
  "total": 2,
  "updated": 1,
  "errors": [
    { "row": 3, "error": "Colaborador não encontrado para o email informado" }
  ]
}
```

`total` conta linhas de dados; `updated` conta linhas com RH atualizado; `errors` contém falhas e avisos. `row` começa em 2, após o cabeçalho, e acompanha as linhas não vazias processadas. Evite linhas vazias intermediárias para facilitar a conferência com a planilha.

O lote não faz rollback das linhas anteriores. Se RH for salvo e os dados bancários falharem, a linha permanece em `updated` e recebe um aviso em `errors`. Por isso, `updated + errors.length` pode ser maior que `total`. Revise os erros e corrija as linhas afetadas antes de reenviar.

## Desativação e erros

DELETE faz **soft delete do registro de RH**. Não exclui o usuário, não desativa seu vínculo e não apaga o perfil global. A consulta pode continuar retornando esses dados com `has_hr_data=false`. POST/PUT não reativam automaticamente um registro desativado.

| Status | Interpretação                                                                                 |
| ------ | --------------------------------------------------------------------------------------------- |
| `400`  | Dados, identificador ou arquivo inválido; conta ausente; usuário sem vínculo ativo na escrita |
| `401`  | Falha de autenticação                                                                         |
| `403`  | Sem permissão para a operação                                                                 |
| `413`  | Arquivo maior que 10 MiB                                                                      |
| `500`  | Falha interna; as mensagens públicas não expõem os detalhes internos                          |

Na consulta, ausência de vínculo retorna `200` vazio. Na importação, erros individuais vêm em `errors`, mesmo com HTTP `201`.