VUIT

Carregando

POST/api/v1/people

Adicionar ou Atualizar Pessoas (Upsert)

Adiciona ou atualiza pessoas via JSON (upsert baseado em CPF + CNPJ). Se a combinação CPF + CNPJ já existir, atualiza os dados; caso contrário, cria um novo registro. Aceita um único objeto ou array de objetos.

Write

Este endpoint requer um token com permissão de escrita (writePermission: true)

Parâmetros de Query

removeAbsentboolean

padrão: false

Se true, marca como 'removido' todas as pessoas não presentes no payload que pertencem às empresas (CNPJs) enviadas

Body (JSON)

Campo	Tipo	Obrigatório	Padrão	Descrição
name	string	Sim	-	Nome completo da pessoa
cpf	string	Sim	-	CPF da pessoa (validado por algoritmo de dígitos verificadores). Aceita formatação com pontos e traços Formato: `11 dígitos (ex: 12345678901 ou 123.456.789-01)`
birthdate	string	Sim	-	Data de nascimento Formato: `DD-MM-YYYY`
city	string	Sim	-	Cidade de residência
uf	string	Sim	-	Estado (UF) Formato: `2 caracteres`
type	string	Sim	-	Tipo de pessoa Valores: `humano, remoto`
cnpj	string	Sim	-	CNPJ da empresa à qual a pessoa pertence. Aceita formatação com pontos, barras e traços Formato: `14 dígitos (ex: 12345678000190 ou 12.345.678/0001-90)`
email	string	Não	-	Email da pessoa Formato: `email válido`
status	string	Não	ativo	Status da pessoa Valores: `ativo, afastado, removido`
cid	string	Não	-	Código CID (classificação internacional de doenças)
details	string	Não	-	Detalhes adicionais sobre a pessoa
sex	string	Não	-	Sexo da pessoa Valores: `masculino, feminino, outro`
role	string	Não	-	Cargo ou função exercida
phone	string	Não	-	Telefone de contato. Pontos, traços e parênteses são removidos automaticamente
salary	number	Não	-	Salário
internalId	string	Não	-	ID interno usado pela empresa
contractStartDate	string	Não	-	Data de início do contrato Formato: `DD-MM-YYYY`
address.street	string	Não	-	Rua do endereço
address.number	string	Não	-	Número do endereço
address.complement	string	Não	-	Complemento do endereço
address.neighborhood	string	Não	-	Bairro
address.city	string	Não	-	Cidade do endereço
address.state	string	Não	-	Estado do endereço
address.postalCode	string	Não	-	CEP. Aceita formatação com pontos e traços Formato: `8 dígitos (ex: 01310200 ou 01310-200)`

Exemplo de Requisição

curl -X POST "/api/v1/people?removeAbsent=true" \
  -H "Authorization: SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "name": "Maria Santos",
      "cpf": "98765432100",
      "birthdate": "20-03-1985",
      "city": "Rio de Janeiro",
      "uf": "RJ",
      "type": "humano",
      "email": "maria@example.com",
      "cnpj": "12345678000190"
    },
    {
      "name": "João Silva",
      "cpf": "12345678901",
      "birthdate": "15-05-1990",
      "city": "São Paulo",
      "uf": "SP",
      "type": "humano",
      "cnpj": "12345678000190",
      "email": "joao.silva@example.com",
      "status": "ativo",
      "cid": "M79.3",
      "details": "Colaborador com mais de 5 anos de empresa",
      "sex": "masculino",
      "role": "Gerente de Operações",
      "phone": "(11) 98765-4321",
      "salary": 8500.00,
      "internalId": "EMP-2024-001",
      "contractStartDate": "01-03-2019",
      "address": {
        "street": "Avenida Paulista",
        "number": "1578",
        "complement": "Conjunto 301",
        "neighborhood": "Bela Vista",
        "city": "São Paulo",
        "state": "SP",
        "postalCode": "01310-200"
      }
    }
  ]'

Exemplo de Resposta

{
  "success": true,
  "message": "1 pessoa inserida, 1 atualizada, 2 removidas",
  "data": {
    "inserted": [
      {
        "index": 0,
        "_id": "...",
        "name": "Maria Santos",
        "cpf": "98765432100"
      }
    ],
    "updated": [
      {
        "index": 1,
        "_id": "...",
        "name": "João Silva",
        "cpf": "12345678901"
      }
    ],
    "removed": 2
  },
  "summary": {
    "totalInserted": 1,
    "totalUpdated": 1,
    "totalRemoved": 2,
    "totalErrors": 0
  }
}