Consignado privado — Cadastro do tomador

Dado pessoal ou sensível deve ser mascarado em outputs, logs e exemplos. Todos os valores desta página são fictícios. Formatos de data e de valor: Convenções de dados.

O que é

O cadastro do tomador cria (ou atualiza) a Pessoa Física que vai contratar o consignado privado: o trabalhador com carteira assinada. O retorno traz o personId, identificador usado em todas as etapas seguintes.

É também o momento em que o trabalhador passa a estar vinculado ao seu usuário/correspondente. Até aqui existia apenas um consentimento associado a um CPF; a partir daqui existe um cadastro seu, e é esse vínculo que a criação da operação confere.

O cadastro é o mesmo recurso de Pessoa Física usado por outros produtos, mas o preenchimento é específico deste produto: aqui os campos de vínculo empregatício (empregador, matrícula, cargo, data de admissão, salário) deixam de ser opcionais na prática, porque são eles que a averbadora usa para localizar o vínculo e reservar a margem.

Quando usar

• Depois da autorização e com os dados da conta em mãos, para o trabalhador que tem margem e escolheu uma oferta.
• Para atualizar dados de vínculo de um trabalhador já cadastrado (troca de empregador, mudança de cargo, novo salário).

Se o CPF já existir e estiver visível ao seu usuário, a criação atualiza o cadastro existente e devolve o id do registro que já havia — não cria duplicata. Coleções relacionadas (contas bancárias, documentos) são combinadas.

Pré-requisitos

• Token válido — ver Autenticação.
• Autorização de margem já registrada para o mesmo CPF — ver 2.1 Autorização de margem. É o CPF que amarra as duas coisas.
• Dados da conta de liquidação preparados — ver 2.2 Conta de liquidação. Eles vão na coleção bankAccounts deste mesmo corpo.
• Dados do vínculo empregatício, obtidos na consulta de margem ou com o trabalhador.

Endpoints do cadastro

Armadilha do PUT. Uma atualização que omite bankAccounts apaga as contas do cadastro, e isso quebra operações em andamento que apontam para elas. Para mexer só na conta, use as rotas de 2.2 Conta de liquidação.

Como preencher

Identificação (obrigatória em qualquer produto)

Vínculo empregatício (o que este produto realmente exige)

Estes campos existem porque a averbadora precisa localizar o vínculo para reservar margem. Não são dado cadastral decorativo: sem eles, a garantia da operação fica sem a que se referir.

"Sim para este produto" significa: o contrato aceita a ausência, mas a averbação não encontra o vínculo sem o campo. Trate como obrigatório.

Conta de liquidação

O id de cada item devolvido nesta coleção é o bankAccountId da criação da operação.

Endereço e documento

Exemplo de request

curl --location --request POST '{{baseUrl}}/v1/NaturalPerson?returnValue=true' \
  --header 'Authorization: Bearer {{token}}' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
    "registrationNumber": "00000000000",
    "name": "JOAO D*** S*** SANTOS",
    "email": "tomador@exemplo.com.br",
    "phone": "11900000000",
    "birthDate": "1990-01-01",
    "mothersName": "MARIA F*** D*** S***",
    "pep": false,
    "natureOfOccupation": "PrivateEmployee",
    "workplace": "EMPRESA EXEMPLO LTDA",
    "workplaceCompanyRegistrationNumber": "00000000000000",
    "employeeNumber": "MAT-000123",
    "admissionDate": "2022-03-01",
    "occupation": "ANALISTA ADMINISTRATIVO",
    "netSalary": 4500.00,
    "address": {
      "addressName": "Rua Exemplo",
      "number": "100",
      "district": "Centro",
      "city": "Sao Paulo",
      "uf": "SP",
      "zipCode": "00000000"
    },
    "bankAccounts": [
      {
        "operationTypeValue": "Pix",
        "type": "NaturalCheckingAccount",
        "pixKeyTypeValue": "NaturalRegistrationNumber",
        "keyPix": "00000000000",
        "bankCode": 341,
        "jointAccount": false
      }
    ]
  }'

Exemplo de response

{
  "id": "11111111-1111-1111-1111-111111111111",
  "registrationNumber": "000.000.000-**",
  "name": "JOAO D*** S*** SANTOS",
  "natureOfOccupation": "PrivateEmployee",
  "workplaceCompanyRegistrationNumber": "00000000000000",
  "employeeNumber": "MAT-000123",
  "admissionDate": "2022-03-01T00:00:00Z",
  "bankAccounts": [
    {
      "id": "22222222-2222-2222-2222-222222222222",
      "operationTypeValue": "Pix",
      "pixKeyTypeValue": "NaturalRegistrationNumber",
      "keyPix": "000.000.000-**"
    }
  ]
}

Dois identificadores saem daqui, e são os dois que a operação pede:

• id da pessoa → personId
• id do item de bankAccounts → bankAccountId

Códigos de retorno

O que acontece depois

O cadastro passa a existir vinculado ao seu usuário/correspondente. Esse vínculo é conferido em toda operação: sem ele, a criação da operação é recusada mesmo com personId válido.

A partir daqui, a consulta de margem pode ser feita por personId em vez de CPF — é a forma preferida, porque o identificador é estável e não trafega dado pessoal na query string.

Com os três cadastros prontos, o fluxo entra na operação.

Antes desta etapa

• 2.2 Conta de liquidação — os campos da conta enviada aqui.
• 2.1 Autorização de margem — a autorização que precisa existir para o mesmo CPF.

Próxima etapa

• 3. Operação — consulta de margem, simulação, proposta e criação da operação.

Downloads

• Contexto para LLM deste módulo: llms-consignado-privado.txt
• Collection Postman do módulo: uy3-consignado-privado.postman_collection.json
• Documentação consolidada para LLM: llms.txt