FGTS — Conta de liquidação

Dado pessoal ou bancário 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 é

A conta de liquidação é a conta bancária do próprio titular que recebe o valor antecipado do saque-aniversário. O identificador dela é o bankAccountId informado na criação da operação.

A liquidação do FGTS é sempre por transferência eletrônica (Pix ou TED). Não há liquidação por boleto neste produto.

Como esta etapa se encaixa na ordem. A conta é um dado do titular — a rota dedicada dela pede o personId no caminho. Nesta etapa você prepara e valida os dados da conta; o envio acontece de uma das duas formas abaixo. É por isso que a conta aparece antes do cadastro do titular na sequência: na prática você coleta os dados bancários junto com o interesse, e os envia dentro do cadastro dele.

Os dois caminhos de envio

Os campos são os mesmos nos dois caminhos: o que muda é onde o objeto vai. As tabelas de preenchimento abaixo valem para os dois.

Se o titular já tem conta cadastrada e ela continua válida, reaproveite o bankAccountId — não crie outra. Contas duplicadas geram escolha errada na liquidação.

Quando usar

• Sempre, antes de criar a operação: sem conta não há para onde liberar o dinheiro.
• Para trocar a conta de destino antes de a operação ser liquidada (caminho B).

Pré-requisitos

• Token válido — ver Autenticação.
• Dados bancários do titular, conferidos com ele.
• Para o caminho B: o personId, obtido em 2.3 Cadastro do titular.

Endpoints do cadastro

Como preencher

Meio de liquidação

Quando operationTypeValue é Pix

Quando operationTypeValue é Transfer (TED)

Titularidade. A conta precisa ser do CPF do titular da conta FGTS; é conferido na liquidação. Chave Pix ou conta de terceiro reprova a liquidação e devolve a operação para revisão de pagamento — depois de a operação já estar assinada e averbada, que é o pior momento para descobrir. Confira antes.

Exemplo de request

Caminho A — a conta dentro do cadastro do titular (recomendado). O corpo completo está em 2.3 Cadastro do titular; aqui, só a parte da conta:

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",
    "bankAccounts": [
      {
        "operationTypeValue": "Pix",
        "type": "NaturalCheckingAccount",
        "pixKeyTypeValue": "NaturalRegistrationNumber",
        "keyPix": "00000000000",
        "bankCode": 341,
        "jointAccount": false
      }
    ]
  }'

Caminho B — conta para um titular que já existe:

curl --location --request POST '{{baseUrl}}/v1/NaturalPerson/11111111-1111-1111-1111-111111111111/BankAccount' \
  --header 'Authorization: Bearer {{token}}' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '[
    {
      "operationTypeValue": "Pix",
      "type": "NaturalCheckingAccount",
      "pixKeyTypeValue": "NaturalRegistrationNumber",
      "keyPix": "00000000000",
      "bankCode": 341,
      "jointAccount": false
    }
  ]'

Exemplo de response

No caminho A, a conta volta dentro do cadastro do titular:

{
  "id": "11111111-1111-1111-1111-111111111111",
  "registrationNumber": "000.000.000-**",
  "bankAccounts": [
    {
      "id": "22222222-2222-2222-2222-222222222222",
      "operationTypeValue": "Pix",
      "pixKeyTypeValue": "NaturalRegistrationNumber",
      "keyPix": "000.000.000-**",
      "bankCode": 341
    }
  ]
}

No caminho B, volta a lista de contas criadas. Nos dois casos, o id da conta é o bankAccountId da criação da operação — não confunda com o id da pessoa, que é o personId.

Códigos de retorno

O que acontece depois

A conta fica disponível para ser escolhida na operação. Nada é debitado ou creditado neste momento: o cadastro apenas declara o destino do valor.

Antes desta etapa

• 2.1 Consentimento de consulta — o passo anterior da sequência.

Próxima etapa

• 2.3 Cadastro do titular — onde o objeto da conta é enviado, no caminho recomendado.
• O bankAccountId é consumido em 3. Operaçã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