FGTS — Pré-requisitos e cadastros

Esta página é o índice dos cadastros do módulo FGTS. Todos eles vivem dentro deste módulo: não existe cadastro avulso na navegação, porque o mesmo objeto (uma Pessoa Física, por exemplo) é preenchido de forma diferente em cada produto.

O que precisa estar pronto

Itens provisionados pela UY3, antes da primeira chamada. Você não os cria pela API — você recebe os identificadores.

Ordem dos cadastros

A ordem importa, e ela espelha a do Consignado privado: o consentimento vem antes do cadastro completo.

1. 2.1 Consentimento de consulta — o termo assinado pelo titular, coletado antes de tudo.
2. 2.2 Conta de liquidação — define a conta que recebe o valor liberado. Os dados são preparados aqui.
3. 2.3 Cadastro do titular — cria a Pessoa Física, com a conta e o termo no mesmo corpo, e devolve o personId.

Por que o consentimento vem antes do cadastro do titular

Pela mesma razão comercial do consignado: o consentimento é a primeira pergunta do funil, não a última. O titular chega ao seu canal, autoriza a consulta ao saldo do FGTS, e só depois se descobre se há saldo antecipável e qual valor faz sentido. Coletar cadastro completo de todo interessado — nome, endereço, documento, conta bancária — antes de saber isso significa guardar dado pessoal de gente que nunca vai contratar.

A diferença de mecânica em relação ao Consignado privado

Aqui a semelhança termina. A forma como o consentimento é registrado é diferente, e é uma diferença que muda o seu código:

Por isso, no FGTS, "consentimento primeiro" é uma ordem de processo, não uma dependência técnica: você coleta e valida o termo antes de tudo, e o envia junto do cadastro do titular, na coleção uploads. É o caminho recomendado — uma chamada em vez de duas.

Essa é a única divergência de sequência entre os dois módulos, e ela existe porque o Crédito do Trabalhador impõe um registro de autorização que o FGTS não tem.

Em que momento o titular passa a estar cadastrado e vinculado

No passo 3, e não antes. O vínculo ao seu usuário/correspondente nasce junto do cadastro, e é ele que a criação da operação confere: um personId válido mas de outro correspondente é recusado com "Tomador não vinculado ao usuário ou correspondente selecionado".

Como isso se conecta à simulação e à operação

[2.1] Termo de consentimento assinado  (coletado, guardado)
                |
[2.2] Dados da conta de liquidação     (preparados)
                |
                v
[2.3] Cadastro do titular  ->  personId + bankAccountId
                |            (com o termo em uploads)
                v
[3]  Simulação por amortização  ->  plano de pagamento
                |
                v
[3]  Criação da operação (personId, bankAccountId, uploads)
                |
                v
[3]  Averbação no órgão  (a esteira confere o termo aqui)

A conferência do termo acontece na etapa de garantia, dentro da esteira — depois de a operação já existir. É por isso que faltar o documento não devolve 400 na criação: devolve a operação em WarrantyRevision mais tarde, o que é bem mais caro de corrigir. Anexe desde o começo.

O que dá para encurtar

• Termo, conta e titular em uma chamada. É o caminho recomendado: envie o termo em uploads e a conta em bankAccounts, no próprio cadastro da Pessoa Física.
• Titular e conta dentro da criação da operação. O objeto newPersonAndAccount do POST /v1/CreditNote cria os dois no momento da operação.
• O termo pode ir na operação em vez do cadastro. Se o seu processo exige um termo por contrato, e não por titular, envie-o em uploads no POST /v1/CreditNote.

Cadastros deste módulo

Antes desta etapa

• 1. Visão geral — o que é o produto e o fluxo completo.
• Convenções de dados — formatos de data e de valor usados nos cadastros.

Próxima etapa

• 2.1 Consentimento de consulta — o primeiro cadastro da sequência.

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