FGTS — Cadastro do titular

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 titular cria (ou atualiza) a Pessoa Física que vai contratar a antecipação: o titular da conta FGTS que aderiu ao saque-aniversário. O retorno traz o personId, identificador usado em todas as etapas seguintes.

É também o momento em que o titular passa a estar vinculado ao seu usuário/correspondente — 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 não há campos de vínculo empregatício a preencher (não existe folha a consignar) e o que precisa estar impecável é a identificação e o endereço, porque é por eles que passam a validação de identidade e a emissão do instrumento.

Quando usar

• Depois de o termo estar coletado e com os dados da conta em mãos, para o titular que decidiu contratar.
• Para corrigir dados de identificação ou contato de um titular já cadastrado.

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.
• Termo de consentimento assinado e digitalizado — ver 2.1 Consentimento de consulta. Ele vai na coleção uploads deste mesmo corpo.
• Dados da conta de liquidação preparados — ver 2.2 Conta de liquidação. Eles vão na coleção bankAccounts deste mesmo corpo.

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. O mesmo vale para uploads: omitir apaga o termo de consentimento do dossiê. Para mexer só na conta, use as rotas de 2.2 Conta de liquidação.

Como preencher

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

Dados que este produto exige de fato

"Sim para este produto" significa: o contrato aceita a ausência, mas a operação é devolvida na emissão do instrumento sem o campo. Trate como obrigatório.

Conta de liquidação e termo de consentimento

O id de cada item de bankAccounts é o bankAccountId da criação da operação.

Campos que não se aplicam a este produto

Não preencha os campos de vínculo empregatício — natureOfOccupation, workplace, workplaceCompanyRegistrationNumber, employeeNumber, admissionDate. Eles descrevem margem consignável, que não existe aqui. Se você está preenchendo esses campos, o produto pretendido é provavelmente Consignado privado.

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": "MARIA D*** S*** LIMA",
    "email": "titular@exemplo.com.br",
    "phone": "11900000000",
    "birthDate": "1988-04-12",
    "mothersName": "ANA F*** D*** S***",
    "pep": false,
    "nationality": "Brasileira",
    "documentType": "RG",
    "documentNumber": "000000000",
    "documentIssuer": "SSP/SP",
    "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
      }
    ],
    "uploads": [
      {
        "fileType": "Authorization",
        "fileName": "consentimento-fgts-000123.pdf",
        "displayName": "Consentimento de consulta FGTS",
        "documentDate": "2026-08-25T00:00:00Z"
      }
    ]
  }'

Uma chamada resolve os três cadastros da sequência: termo, conta e titular.

Exemplo de response

{
  "id": "11111111-1111-1111-1111-111111111111",
  "registrationNumber": "000.000.000-**",
  "name": "MARIA D*** S*** LIMA",
  "email": "titular@exemplo.com.br",
  "documentType": "RG",
  "bankAccounts": [
    {
      "id": "22222222-2222-2222-2222-222222222222",
      "operationTypeValue": "Pix",
      "pixKeyTypeValue": "NaturalRegistrationNumber",
      "keyPix": "000.000.000-**"
    }
  ],
  "uploads": [
    { "id": "66666666-6666-6666-6666-666666666666", "fileType": "Authorization" }
  ]
}

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.

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 Consentimento de consulta — os campos do termo enviado aqui.

Próxima etapa

• 3. Operação — simulação, criação da operação e envio para aprovação.

Downloads

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