> ## Documentation Index
> Fetch the complete documentation index at: https://docs.salu.com.vc/llms.txt
> Use this file to discover all available pages before exploring further.
# Create Employee
Cria um novo funcionário (Employee) na sua organização.
Regras de negócio
* create\_exam (boolean): quando true, será gerado um exame admissional para o colaborador após a criação.
* send\_email (boolean): quando true, o colaborador receberá uma notificação por e-mail sobre o exame.
* send\_date (date-time, opcional): data/hora de envio da notificação. Se send\_email=true e send\_date estiver vazio ou nulo, usaremos a data/hora atual para disparar a comunicação.
Formato de data
* Campo: send\_date
* Formato aceito: ISO 8601 (UTC quando aplicável)
* Exemplos válidos:
* 2025-01-31T00:00:00Z
* 2025-01-31 00:00:00
## Visão Geral
* **Método:** `POST`
* **Path:** `/v0/employee/`
* **OperationId:** `public_create_employee_v0_employee__post`
* **Autenticação:** header `x-api-key` (`APIKeyHeader` no OpenAPI)
### Campos
| Campo | Descrição |
| :----------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `gov_id` (CPF) | **Identificador da Pessoa / Funcionário**
No Brasil, toda pessoa física possui um CPF (Cadastro de Pessoa Física), que é o número de identificação do contribuinte nacional. É único por pessoa e normalmente não muda. Em nossa API, ele é exposto como `gov_id`. Na prática, desempenha um papel semelhante ao SSN (nos EUA) ou a um número de identificação fiscal pessoal em outros países.
**Ponto chave:** `gov_id` identifica o ser humano, não a relação de trabalho. |
| `hr_code` | **“Matrícula RH” (ID interno de RH da empresa) — opcional**
Corresponde à Matrícula RH, que é um código interno do funcionário criado pela empresa para sistemas de RH/folha de pagamento/administrativos. Opcional (não exigido por lei). Usado para controles internos e integrações com as ferramentas de HRIS/folha de pagamento da empresa. Pode variar de empresa para empresa e pode mudar se a empresa migrar de sistemas. Pense nisso como um ID de Funcionário típico dentro de uma organização. |
| `employee_registration_number` | **“Matrícula eSocial” (ID de vínculo empregatício do governo) — obrigatório (quando aplicável)**
Corresponde à Matrícula eSocial, que é um identificador oficial vinculado à relação de trabalho formal sob a legislação trabalhista brasileira (CLT). Obrigatório por lei para o reporte formal de emprego (eSocial). É único por relação de trabalho (por “vínculo de trabalho”), não necessariamente por pessoa para toda a vida. Pode não estar disponível na admissão, pois geralmente é atribuído/confirmado somente após a folha de pagamento/contabilidade registrar formalmente o funcionário, incluindo o registro na CTPS.
**Nuance importante:** Uma pessoa (`gov_id`) pode existir no sistema antes que a Matrícula eSocial seja conhecida. Uma vez que o emprego é formalizado, `employee_registration_number` se torna a referência oficial do “lado do governo” para aquele vínculo empregatício. |
### Exemplos focados em `create_exam` e `send_email`
#### 1) Gerar exame e enviar e-mail imediatamente (sem send\_date)
```bash theme={null}
curl -X POST "https://public-api.salu.com.vc/dev/routes/v0/employee/" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "x-api-key: $SALU_PUBLIC_API_KEY" \
--data '{
"name": "Maria da Silva",
"gov_id": "12345678900",
"is_disabled": false,
"status": "Ativo",
"sex": "F",
"admission_date": "2025-01-31",
"organization_id": "00000000-0000-0000-0000-000000000001",
"branch_id": "00000000-0000-0000-0000-000000000002",
"position_id": "00000000-0000-0000-0000-000000000003",
"sector_id": "00000000-0000-0000-0000-000000000004",
"create_exam": true,
"send_email": true,
"send_date": null
}'
```
Neste cenário, um exame admissional será criado e o e-mail será enviado agora (data/hora atual), pois send\_email=true e send\_date não foi informado.
#### 2) Agendar envio do e-mail para uma data/hora específica
```bash theme={null}
curl -X POST "https://public-api.salu.com.vc/dev/routes/v0/employee/" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "x-api-key: $SALU_PUBLIC_API_KEY" \
--data '{
"name": "Maria da Silva",
"gov_id": "12345678900",
"is_disabled": false,
"status": "Ativo",
"sex": "F",
"admission_date": "2025-01-31",
"organization_id": "00000000-0000-0000-0000-000000000001",
"branch_id": "00000000-0000-0000-0000-000000000002",
"position_id": "00000000-0000-0000-0000-000000000003",
"sector_id": "00000000-0000-0000-0000-000000000004",
"create_exam": true,
"send_email": true,
"send_date": "2025-02-01T09:30:00Z"
}'
```
Aqui, o exame admissional será criado e o e-mail será enviado na data/hora informada em send\_date (ISO 8601).
### Campos enum e traduções
Use exatamente os valores do enum conforme definidos pela API (strings em português). As traduções/descrições abaixo servem apenas como referência de significado.
#### status
| Campo (request) | Valores permitidos (enum da API) | Significado (PT) |
| --------------- | -------------------------------- | ---------------- |
| `status` | `Ativo` | Ativo |
| | `Inativo` | Inativo |
| | `Afastado` | Afastado |
| | `Férias` | Férias |
| | `Pendente` | Pendente |
#### sex
| Campo (request) | Valores permitidos (enum da API) | Significado (PT) |
| --------------- | -------------------------------- | ---------------- |
| `sex` | `M` | Masculino |
| | `F` | Feminino |
#### gender
| Campo (request) | Valores permitidos (enum da API) | Significado (PT) |
| --------------- | -------------------------------- | ---------------- |
| `gender` | `Cis` | Cisgênero |
| | `Trans` | Transgênero |
#### marital\_status
| Campo (request) | Valores permitidos (enum da API) | Significado (PT) |
| ---------------- | -------------------------------- | ---------------- |
| `marital_status` | `Não informado` | Não informado |
| | `Solteiro` | Solteiro |
| | `Casado` | Casado |
| | `Separado` | Separado |
| | `Desquitado` | Desquitado |
| | `Viúvo` | Viúvo |
| | `Outros` | Outros |
| | `Divorciado` | Divorciado |
| | `União Estável` | União estável |
#### educational\_stage
| Campo (request) | Valores permitidos (enum da API) | Significado (PT) |
| ------------------- | -------------------------------- | ----------------------------- |
| `educational_stage` | `Indefinida` | Indefinida |
| | `Ensino Fundamental Incompleto` | Ensino Fundamental Incompleto |
| | `Ensino Fundamental Completo` | Ensino Fundamental Completo |
| | `Ensino Medio Incompleto` | Ensino Médio Incompleto |
| | `Ensino Medio Completo` | Ensino Médio Completo |
| | `Ensino Superior Incompleto` | Ensino Superior Incompleto |
| | `Ensino Superior Completo` | Ensino Superior Completo |
| | `Profissionalizante` | Profissionalizante |
| | `Técnico Incompleto` | Técnico Incompleto |
| | `Técnico Completo` | Técnico Completo |
| | `Tecnólogo Incompleto` | Tecnólogo Incompleto |
| | `Tecnólogo Completo` | Tecnólogo Completo |
| | `Pós-graduação Incompleta` | Pós-graduação Incompleta |
| | `Pós-graduação Completo` | Pós-graduação Completo |
| | `Mestrado Incompleto` | Mestrado Incompleto |
| | `Mestrado Completo` | Mestrado Completo |
| | `Doutorado Incompleto` | Doutorado Incompleto |
| | `Doutorado Completo` | Doutorado Completo |
| | `PHD Incompleto` | PHD Incompleto |
| | `PHD Completo` | PHD Completo |
| | `Não Informado` | Não informado |
| | `Analfabeto` | Analfabeto |
#### human\_skin\_tone
| Campo (request) | Valores permitidos (enum da API) | Significado (PT) |
| ----------------- | -------------------------------- | ---------------- |
| `human_skin_tone` | `Indefinido` | Indefinido |
| | `Branca` | Branca |
| | `Preta` | Preta |
| | `Parda` | Parda |
| | `Amarela` | Amarela |
| | `Indígena` | Indígena |
| | `Mulato` | Mulato |
#### contract\_type
| Campo (request) | Valores permitidos (enum da API) | Significado (PT) |
| --------------- | ---------------------------------------------- | --------------------------------------------------------- |
| `contract_type` | `CLT` | Emprego pela CLT |
| | `COOPERADO` | Cooperado |
| | `TERCERIZADO` | Terceirizado |
| | `AUTONOMO` | Autônomo |
| | `TEMPORARIO` | Temporário |
| | `PESSOA_JURIDICA` | Pessoa Jurídica |
| | `ESTAGIARIO` | Estagiário |
| | `MENOR_APRENDIZ` | Menor aprendiz |
| | `ESTATUTARIO` | Servidor estatutário |
| | `COMISSIONADO_INTERNO` | Comissionado interno |
| | `COMISSIONADO_EXTERNO` | Comissionado externo |
| | `APOSENTADO` | Aposentado |
| | `APOSENTADO_INATIVO_PREFEITURA` | Aposentado inativo (prefeitura) |
| | `PENSIONISTA` | Pensionista |
| | `SERVIDOR_PUBLICO_EFETIVO` | Servidor público efetivo |
| | `EXTRANUMERARIO` | Extranumerário |
| | `AUTARQUICO` | Servidor autárquico |
| | `INATIVO` | Inativo |
| | `TITULO_PRECARIO` | Título precário |
| | `SERVIDOR_ADM_CENTRALIZADA_OU_DESCENTRALIZADA` | Servidor da administração centralizada ou descentralizada |
### Exemplo de requisição
```bash theme={null}
curl -X POST "https://public-api.salu.com.vc/dev/routes/v0/employee/" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "x-api-key: $SALU_PUBLIC_API_KEY" \
--data '{
"employee_name": "Maria da Silva",
"employee_registration_number": "12345",
"employee_is_disabled": false
}'
```
## OpenAPI
````yaml POST /v0/employee/
openapi: 3.1.0
info:
title: Public API v0
description: API publica da Salu para integracoes de SST.
version: 0.1.0
servers:
- url: https://public-api.salu.com.vc/dev/routes
description: Development
- url: https://public-api.salu.com.vc/prd/routes
description: Production
security: []
paths:
/v0/employee/:
post:
tags:
- Employee
- Employee
summary: Public Create Employee
operationId: public_create_employee_v0_employee__post
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PublicApiCreateEmployeeRequest'
responses:
'201':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/PublicApiCreateEmployeeResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- APIKeyHeader: []
components:
schemas:
PublicApiCreateEmployeeRequest:
properties:
address:
anyOf:
- type: string
- type: 'null'
title: Address
address_number:
anyOf:
- type: string
- type: 'null'
title: Address Number
address_detail:
anyOf:
- type: string
- type: 'null'
title: Address Detail
zip_code:
anyOf:
- type: string
- type: 'null'
title: Zip Code
neighborhood:
anyOf:
- type: string
- type: 'null'
title: Neighborhood
state:
anyOf:
- type: string
- type: 'null'
title: State
city:
anyOf:
- type: string
- type: 'null'
title: City
name:
type: string
title: Name
social_name:
anyOf:
- type: string
- type: 'null'
title: Social Name
gov_id:
type: string
title: Gov Id
birth_date:
anyOf:
- type: string
format: date
- type: 'null'
title: Birth Date
is_disabled:
type: boolean
title: Is Disabled
status:
$ref: '#/components/schemas/PublicApiStatusEnum'
sex:
$ref: '#/components/schemas/PublicApiSexEnum'
gender:
anyOf:
- $ref: '#/components/schemas/PublicApiGenderIdentityEnum'
- type: 'null'
mother_name:
anyOf:
- type: string
- type: 'null'
title: Mother Name
marital_status:
anyOf:
- $ref: '#/components/schemas/PublicApiMaritalStatusEnum'
- type: 'null'
place_of_birth:
anyOf:
- type: string
- type: 'null'
title: Place Of Birth
educational_stage:
anyOf:
- $ref: '#/components/schemas/PublicApiEducationalStageEnum'
- type: 'null'
human_skin_tone:
anyOf:
- $ref: '#/components/schemas/PublicApiHumanSkinToneEnum'
- type: 'null'
phone:
anyOf:
- type: string
- type: 'null'
title: Phone
cell_phone:
anyOf:
- type: string
- type: 'null'
title: Cell Phone
email:
anyOf:
- type: string
- type: 'null'
title: Email
personal_email:
anyOf:
- type: string
- type: 'null'
title: Personal Email
admission_date:
type: string
format: date
title: Admission Date
hr_code:
anyOf:
- type: string
- type: 'null'
title: Hr Code
e_social:
anyOf:
- type: string
- type: 'null'
title: E Social
employee_registration_number:
anyOf:
- type: string
- type: 'null'
title: Employee Registration Number
e_social_category:
anyOf:
- type: string
- type: 'null'
title: E Social Category
contract_type:
anyOf:
- $ref: '#/components/schemas/EmployeeContractTypeEnum'
- type: 'null'
work_shift:
anyOf:
- type: string
- type: 'null'
title: Work Shift
organization_id:
type: string
format: uuid
title: Organization Id
branch_id:
type: string
format: uuid
title: Branch Id
position_id:
type: string
format: uuid
title: Position Id
sector_id:
type: string
format: uuid
title: Sector Id
client_integration_code:
anyOf:
- type: string
- type: 'null'
title: Client Integration Code
create_exam:
type: boolean
title: Create Exam
default: true
send_email:
anyOf:
- type: boolean
- type: 'null'
title: Send Email
default: false
send_date:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Send Date
disability_analysis_id:
anyOf:
- type: string
format: uuid
- type: 'null'
title: ID da Análise PCD
description: >-
ID da análise PCD aprovada vinculada ao colaborador. Obrigatório
quando is_disabled=true e o customer exige pré-análise.
type: object
required:
- name
- gov_id
- is_disabled
- status
- sex
- admission_date
- organization_id
- branch_id
- position_id
- sector_id
title: PublicApiCreateEmployeeRequest
PublicApiCreateEmployeeResponse:
properties:
id:
type: string
format: uuid
title: Id
name:
type: string
title: Name
social_name:
anyOf:
- type: string
- type: 'null'
title: Social Name
gov_id:
anyOf:
- type: string
- type: 'null'
title: Gov Id
birth_date:
anyOf:
- type: string
format: date
- type: 'null'
title: Birth Date
is_disabled:
type: boolean
title: Is Disabled
status:
type: string
title: Status
sex:
type: string
title: Sex
gender:
anyOf:
- type: string
- type: 'null'
title: Gender
mother_name:
anyOf:
- type: string
- type: 'null'
title: Mother Name
marital_status:
anyOf:
- type: string
- type: 'null'
title: Marital Status
place_of_birth:
anyOf:
- type: string
- type: 'null'
title: Place Of Birth
educational_stage:
anyOf:
- type: string
- type: 'null'
title: Educational Stage
human_skin_tone:
anyOf:
- type: string
- type: 'null'
title: Human Skin Tone
phone:
anyOf:
- type: string
- type: 'null'
title: Phone
cell_phone:
anyOf:
- type: string
- type: 'null'
title: Cell Phone
email:
anyOf:
- type: string
- type: 'null'
title: Email
personal_email:
anyOf:
- type: string
- type: 'null'
title: Personal Email
admission_date:
type: string
format: date
title: Admission Date
dismissal_date:
anyOf:
- type: string
format: date
- type: 'null'
title: Dismissal Date
hr_code:
anyOf:
- type: string
- type: 'null'
title: Hr Code
employee_registration_number:
anyOf:
- type: string
- type: 'null'
title: Employee Registration Number
work_shift:
anyOf:
- type: string
- type: 'null'
title: Work Shift
is_active:
type: boolean
title: Is Active
client_integration_code:
anyOf:
- type: string
- type: 'null'
title: Client Integration Code
organization:
$ref: '#/components/schemas/SimpleEntity'
branch:
$ref: '#/components/schemas/SimpleEntity'
position:
$ref: '#/components/schemas/SimpleEntity'
sector:
$ref: '#/components/schemas/SimpleEntity'
address:
anyOf:
- $ref: '#/components/schemas/Address'
- type: 'null'
type: object
required:
- id
- name
- is_disabled
- status
- sex
- admission_date
- is_active
- organization
- branch
- position
- sector
title: PublicApiCreateEmployeeResponse
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
PublicApiStatusEnum:
type: string
enum:
- Ativo
- Inativo
- Afastado
- Férias
- Pendente
title: PublicApiStatusEnum
PublicApiSexEnum:
type: string
enum:
- M
- F
title: PublicApiSexEnum
PublicApiGenderIdentityEnum:
type: string
enum:
- Cis
- Trans
title: PublicApiGenderIdentityEnum
PublicApiMaritalStatusEnum:
type: string
enum:
- Não informado
- Solteiro
- Casado
- Separado
- Desquitado
- Viúvo
- Outros
- Divorciado
- União Estável
title: PublicApiMaritalStatusEnum
PublicApiEducationalStageEnum:
type: string
enum:
- Indefinida
- Ensino Fundamental Incompleto
- Ensino Fundamental Completo
- Ensino Medio Incompleto
- Ensino Medio Completo
- Ensino Superior Incompleto
- Ensino Superior Completo
- Profissionalizante
- Técnico Incompleto
- Técnico Completo
- Tecnólogo Incompleto
- Tecnólogo Completo
- Pós-graduação Incompleta
- Pós-graduação Completo
- Mestrado Incompleto
- Mestrado Completo
- Doutorado Incompleto
- Doutorado Completo
- PHD Incompleto
- PHD Completo
- Não Informado
- Analfabeto
title: PublicApiEducationalStageEnum
PublicApiHumanSkinToneEnum:
type: string
enum:
- Indefinido
- Branca
- Preta
- Parda
- Amarela
- Indígena
- Mulato
title: PublicApiHumanSkinToneEnum
EmployeeContractTypeEnum:
type: string
enum:
- CLT
- COOPERADO
- TERCERIZADO
- AUTONOMO
- TEMPORARIO
- PESSOA_JURIDICA
- ESTAGIARIO
- MENOR_APRENDIZ
- ESTATUTARIO
- COMISSIONADO_INTERNO
- COMISSIONADO_EXTERNO
- APOSENTADO
- APOSENTADO_INATIVO_PREFEITURA
- PENSIONISTA
- SERVIDOR_PUBLICO_EFETIVO
- EXTRANUMERARIO
- AUTARQUICO
- INATIVO
- TITULO_PRECARIO
- SERVIDOR_ADM_CENTRALIZADA_OU_DESCENTRALIZADA
title: EmployeeContractTypeEnum
SimpleEntity:
properties:
id:
type: string
format: uuid
title: Id
name:
type: string
title: Name
type: object
required:
- id
- name
title: SimpleEntity
Address:
properties:
address:
anyOf:
- type: string
- type: 'null'
title: Address
address_number:
anyOf:
- type: string
- type: 'null'
title: Address Number
address_detail:
anyOf:
- type: string
- type: 'null'
title: Address Detail
zip_code:
anyOf:
- type: string
- type: 'null'
title: Zip Code
neighborhood:
anyOf:
- type: string
- type: 'null'
title: Neighborhood
state:
anyOf:
- type: string
- type: 'null'
title: State
city:
anyOf:
- type: string
- type: 'null'
title: City
type: object
title: Address
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
input:
title: Input
ctx:
type: object
title: Context
type: object
required:
- loc
- msg
- type
title: ValidationError
securitySchemes:
APIKeyHeader:
type: apiKey
in: header
name: x-api-key
````