# UY3 — FGTS (contexto completo para LLM) Gerado do portal de documentação da UY3. Contém, em um único arquivo e na ordem da navegação, todas as páginas do módulo FGTS — nada de outros produtos. ## Como ler este arquivo - Cada página aparece como `## /guia/{id} — {título}`. Links internos no formato `/guia/{id}` apontam para outra seção deste mesmo arquivo. - Placeholders dos exemplos: `{{baseUrl}}` (URL base da API) e `{{token}}` (token Bearer). Compatíveis com variáveis de environment do Postman. - Formato de datas, de valores monetários e de identificadores: seção `/guia/convencoes-de-dados`. Vale para todos os campos de toda a documentação. - Todos os dados de exemplo são fictícios e mascarados. Dado pessoal ou sensível deve ser mascarado em outputs, logs e exemplos. - A ordem das páginas de um módulo é a ordem em que as etapas devem ser executadas. Ela não é arbitrária: reflete a dependência de negócio entre elas. Escopo desta versão da documentação: **Consignado privado** e **FGTS**. Os demais produtos do catálogo entram quando forem migrados para este mesmo padrão. Referência de API gerada do contrato OpenAPI (fora deste arquivo): - Crédito: /referencia/creditapi/llm.md Collections Postman: - /downloads/uy3-api-completa.postman_collection.json - /downloads/uy3-consignado-privado.postman_collection.json - /downloads/uy3-fgts.postman_collection.json ## Sumário - CaaS Massificados / FGTS - /guia/fgts-visao-geral — 1. Visão geral - /guia/fgts-cadastros — 2. Pré-requisitos e cadastros - /guia/fgts-cadastro-autorizacao — 2.1 Consentimento de consulta - /guia/fgts-cadastro-conta — 2.2 Conta de liquidação - /guia/fgts-cadastro-pessoa — 2.3 Cadastro do titular - /guia/fgts-operacao — 3. Operação - /guia/fgts-consultas — 4. Consultas e acompanhamento - /guia/fgts-eventos — 4.1 Eventos e notificações - /guia/fgts-erros — 5. Erros e troubleshooting # Seção: CaaS Massificados ## Módulo: FGTS ## /guia/fgts-visao-geral — 1. Visão geral # FGTS — Visão geral **Antecipação do saque-aniversário.** O produto FGTS antecipa, em uma única liberação hoje, parcelas anuais futuras do saque-aniversário do titular. A garantia é o próprio saldo do FGTS: a cada ano o valor do saque-aniversário é debitado na origem e amortiza a operação. Esta página abre o módulo. Ela responde o que é o produto, para quem ele serve e qual é o caminho completo — do primeiro cadastro à consulta final. Cada passo do fluxo abaixo é um link para a página que o executa. ## O que é O FGTS é um crédito **lastreado em saldo já existente**, não em renda futura. O titular que aderiu à modalidade saque-aniversário troca o direito de sacar nos próximos anos por dinheiro agora. Três consequências práticas para quem integra: - **Não há margem consignável nem comprovação de renda.** O teto da operação vem do saldo disponível e do número de saques que podem ser antecipados. - **A averbação acontece antes da liquidação.** A operação entra em uma etapa de garantia dedicada e aguarda o retorno do órgão, respeitando a janela de manutenção dele. - **O objeto de cálculo é o mais enxuto do catálogo.** Prazo, valor e mês do saque bastam: não há dia de vencimento, carência nem periodicidade a informar. Diferente do [Consignado privado](/guia/consignado-privado-visao-geral), aqui **não se envia objeto de garantia por tipo**: a averbação é uma etapa própria da esteira, que fala direto com o órgão. Não existe tipo de garantia `FGTS` na lista de tipos de garantia — FGTS é o produto, não um tipo de garantia. ## Para quem serve | Perfil | Serve? | Por quê | |---|---|---| | Pessoa Física titular de conta FGTS, com adesão ao saque-aniversário | **Sim** | É o público do produto: existe saldo antecipável e o débito anual é automático na origem. | | Titular de FGTS na modalidade saque-rescisão | Não | Sem adesão ao saque-aniversário não há parcela anual a antecipar. | | Trabalhador que quer desconto em folha | Não | Isso é [Consignado privado](/guia/consignado-privado-visao-geral). Aqui o FGTS não passa pela folha. | | Pessoa Jurídica | Não | Não há conta FGTS de PJ. | Quem consome esta documentação: times de integração de correspondentes bancários, fintechs parceiras e squads internas da UY3. ## Fluxo ponta a ponta ### Passo a passo A ordem abaixo **não é arbitrária**: é a ordem em que o negócio permite executar cada etapa. Ela espelha a do [Consignado privado](/guia/consignado-privado-visao-geral) — o consentimento primeiro, o cadastro completo depois — com uma diferença de mecânica explicada no passo 1. 1. **Consentimento de consulta ao FGTS.** É o termo assinado pelo titular, coletado antes de qualquer cadastro. Aqui ele é um **documento**, não um registro com endpoint próprio. → [2.1 Consentimento de consulta](/guia/fgts-cadastro-autorizacao) 2. **Cadastrar a conta de liquidação.** É a conta que vai receber o dinheiro liberado. Os dados são preparados aqui e enviados junto do cadastro do titular. → [2.2 Conta de liquidação](/guia/fgts-cadastro-conta) 3. **Cadastrar o titular (Pessoa Física).** É aqui que o titular passa a existir e a estar vinculado ao seu usuário/correspondente, com a conta e o consentimento no mesmo corpo. → [2.3 Cadastro do titular](/guia/fgts-cadastro-pessoa) 4. **Simular a antecipação.** Valor, prazo em meses e mês do saque definem o plano de pagamento. → [3. Operação](/guia/fgts-operacao) 5. **Criar a operação de crédito.** A operação nasce em rascunho, com o modelo de cálculo do FGTS. → [3. Operação](/guia/fgts-operacao) 6. **Enviar para aprovação, assinar e aguardar a averbação.** A operação percorre as etapas de crédito, garantia e assinatura. → [3. Operação](/guia/fgts-operacao) 7. **Acompanhar status, liquidação e comprovante.** Do envio até o encerramento, o acompanhamento é por consulta. → [4. Consultas e acompanhamento](/guia/fgts-consultas) Os eventos que marcam cada transição estão em [4.1 Eventos e notificações](/guia/fgts-eventos). Quando algum passo falha, a causa e a ação corretiva estão em [5. Erros e troubleshooting](/guia/fgts-erros). ### Diagrama do fluxo ```text [2.1] Consentimento de consulta ao FGTS (termo assinado — documento) | [2.2] Dados da conta de liquidação (preparados) | [2.3] Cadastro do titular (PF) (com conta e termo no mesmo corpo -> personId) | [3] Simulação por amortização (valor, prazo, mês do saque) | [3] Criação da operação de crédito (sem objeto de garantia) | [3] Envio para aprovação -> Crédito -> Garantia (averbação no órgão) -> Assinatura | [3] Liquidação (Pix/TED na conta do titular) | [4] Acompanhamento: status, parcelas, comprovante ``` ### Os caminhos de simulação No [Consignado privado](/guia/consignado-privado-visao-geral) existem dois caminhos de simulação: ofertas e amortização. **No FGTS existe um só: a simulação por amortização.** | | **Simulação por amortização** | **Simulação de ofertas** | |---|---|---| | Existe neste produto? | **Sim** — é o caminho do FGTS | **Não** | | Rota | `POST /v1/Amortization` | — | | Você informa | valor, taxa, prazo e mês do saque | — | | Você recebe | um plano de pagamento completo | — | A razão é de negócio, não de contrato: a simulação de ofertas existe para escolher **entre produtos habilitados que caibam numa margem consignável**, e no FGTS não há margem a consultar nem vitrine de produtos a comparar — o lastro é um saldo que já existe na conta do titular. O que resta é dimensionar valor e prazo, e isso é exatamente o que a simulação por amortização faz. Detalhe e exemplos em [3. Operação](/guia/fgts-operacao). ## Regras de negócio que decidem o produto | Regra | Por que existe | Efeito na integração | |---|---|---| | Modelo de cálculo exclusivo | O cronograma se ancora no mês do saque-aniversário, que nenhum outro produto tem. | `amortizationType` precisa ser `fgts`. Nenhum outro valor é aceito neste produto. | | Somente Pessoa Física | Conta FGTS é de trabalhador, não de empresa. | O titular é sempre PF. Não há cadastro de PJ neste produto. | | Etapa de averbação dedicada | O registro da garantia é feito junto ao órgão, que tem janela própria de atendimento. | A operação assume a etapa de garantia e aguarda. Não há rota de averbação para o parceiro chamar. | | Limite anual de contratos por titular | Cada saque-aniversário só pode ser antecipado uma vez. | Exceder o limite bloqueia o envio para aprovação. | | Consentimento de guarda obrigatória | A consulta ao saldo do titular depende de autorização expressa dele. | O termo faz parte do dossiê da operação, não é artefato descartável. | | Liquidação por transferência | O valor vai para a conta do próprio titular. | Sai por Pix ou TED; não há liquidação por boleto. | O produto contratado (`productId`) é provisionado **pela UY3** e carrega faixa de taxa e faixa de prazo. Você não o cria pela API: você recebe o identificador e trabalha dentro dos limites dele. Formato de datas, de valores monetários e de taxas: [Convenções de dados](/guia/convencoes-de-dados). É a mesma convenção em todos os campos deste módulo. ## O que este produto não é - **Não é consignado.** Nada é descontado em folha. Para desconto em folha do setor privado, use [Consignado privado](/guia/consignado-privado-visao-geral). - **Não é empréstimo sem garantia.** Aqui existe lastro: o saldo do FGTS do titular. - **Não é reforço de garantia de outro produto.** Quando saldo e multa rescisória do FGTS entram como reforço da margem consignável, o produto é [Consignado privado](/guia/consignado-privado-visao-geral) — não este. ## Antes desta etapa - [Primeiros passos](/guia/primeiros-passos) — como obter acesso e o `productId` do seu produto contratado. - [Autenticação](/guia/autenticacao) — como emitir e renovar o token enviado em todas as chamadas. - [Convenções de dados](/guia/convencoes-de-dados) — formatos de data, valor e taxa usados em todo o módulo. ## Próxima etapa - [2. Pré-requisitos e cadastros](/guia/fgts-cadastros) — o que precisa estar pronto e em que ordem. ## Downloads - Contexto para LLM deste módulo: [llms-fgts.txt](/downloads/llms-fgts.txt) - Collection Postman do módulo: [uy3-fgts.postman_collection.json](/downloads/uy3-fgts.postman_collection.json) - Collection completa (Consignado privado + FGTS): [uy3-api-completa.postman_collection.json](/downloads/uy3-api-completa.postman_collection.json) - Documentação consolidada para LLM: [llms.txt](/downloads/llms.txt) --- ## /guia/fgts-cadastros — 2. Pré-requisitos e cadastros # 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. | Pré-requisito | O que é | O que você recebe | |---|---|---| | Credencial de integração | Token de acesso do seu usuário/correspondente. | Credenciais para emitir o token — ver [Autenticação](/guia/autenticacao). | | Produto contratado | Define o modelo de cálculo do FGTS, a faixa de taxa e a faixa de prazo. | `productId` (uuid). | | Habilitação de averbação no órgão | Integração da UY3 com o órgão que registra a garantia do saque-aniversário. | Nada a enviar; habilitação por ambiente do parceiro. | | Adesão do titular ao saque-aniversário | Condição do próprio titular, verificada fora da API. | Confirmação com o titular antes de simular. | ## Ordem dos cadastros A ordem importa, e ela espelha a do [Consignado privado](/guia/consignado-privado-cadastros): o consentimento vem antes do cadastro completo. 1. **[2.1 Consentimento de consulta](/guia/fgts-cadastro-autorizacao)** — o termo assinado pelo titular, coletado antes de tudo. 2. **[2.2 Conta de liquidação](/guia/fgts-cadastro-conta)** — define a conta que recebe o valor liberado. Os dados são preparados aqui. 3. **[2.3 Cadastro do titular](/guia/fgts-cadastro-pessoa)** — 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: | | **Consignado privado** | **FGTS** | |---|---|---| | O que é o consentimento | Um **registro estruturado**, com endpoint próprio | Um **documento** anexado | | Rota | `POST /v1/DataprevEmployee/AuthorizationMargin` | `POST /v1/NaturalPerson/{id}/Upload`, ou a coleção `uploads` | | Precisa de `personId`? | **Não** — identifica-se por CPF e telefone | **Sim**, para a rota dedicada; **não**, se enviado na coleção `uploads` do cadastro | | Tem status próprio? | Sim: `Pending`, `Approved`, `Refused` | Não. É um arquivo no dossiê. | | Tem prazo de validade externo? | Sim, definido pelo Crédito do Trabalhador | Não. A retenção é política sua e do Compliance da UY3. | | Bloqueia consulta se ausente? | Sim — a consulta de margem é recusada | Não bloqueia chamada; a **operação** é devolvida na etapa de garantia | 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 ```text [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 | Cadastro | Serve para | Exige `personId`? | Consumido por | |---|---|---|---| | [Consentimento de consulta](/guia/fgts-cadastro-autorizacao) | Comprovar a autorização do titular para a consulta ao FGTS. | Depende do caminho | Etapa de garantia, em [3. Operação](/guia/fgts-operacao) | | [Conta de liquidação](/guia/fgts-cadastro-conta) | Definir a conta que recebe o valor liberado. | Depende do caminho | Liquidação, em [3. Operação](/guia/fgts-operacao) | | [Cadastro do titular](/guia/fgts-cadastro-pessoa) | Identificar o titular da conta FGTS. | Cria o `personId` | Criação da operação, em [3. Operação](/guia/fgts-operacao) | ## Antes desta etapa - [1. Visão geral](/guia/fgts-visao-geral) — o que é o produto e o fluxo completo. - [Convenções de dados](/guia/convencoes-de-dados) — formatos de data e de valor usados nos cadastros. ## Próxima etapa - [2.1 Consentimento de consulta](/guia/fgts-cadastro-autorizacao) — o primeiro cadastro da sequência. ## Downloads - Contexto para LLM deste módulo: [llms-fgts.txt](/downloads/llms-fgts.txt) - Collection Postman do módulo: [uy3-fgts.postman_collection.json](/downloads/uy3-fgts.postman_collection.json) - Documentação consolidada para LLM: [llms.txt](/downloads/llms.txt) --- ## /guia/fgts-cadastro-autorizacao — 2.1 Consentimento de consulta # FGTS — Consentimento de consulta 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: [Convenções de dados](/guia/convencoes-de-dados). ## O que é O consentimento de consulta é o **termo assinado pelo titular** autorizando a UY3 a consultar o saldo do saque-aniversário do FGTS e a registrar a garantia junto ao órgão. Diferente do [Consignado privado](/guia/consignado-privado-cadastro-autorizacao), onde a autorização é um registro estruturado com endpoint próprio, aqui o consentimento é **um documento**: um arquivo do tipo `Authorization` anexado ao cadastro do titular ou à operação. É documento de **guarda obrigatória** — parte do dossiê, não artefato descartável do fluxo. > **Este é o primeiro passo do módulo — de processo, não de dependência técnica.** Você coleta e valida o termo antes de qualquer cadastro, porque é a primeira pergunta do funil. O **envio** dele acontece junto do cadastro do titular, na coleção `uploads`. A comparação completa com o consignado está em [2. Pré-requisitos e cadastros](/guia/fgts-cadastros). ## Quando usar - Antes de tudo, para cada titular que entra no seu funil. - De novo em cada nova operação, quando o seu processo exige termo por contrato em vez de termo por titular. Anexar ao **cadastro do titular** vale para todas as operações dele. Anexar à **operação** amarra o termo àquele contrato específico. Quando houver dúvida, anexe nos dois lugares: a operação é devolvida na esteira se o documento obrigatório faltar. ## Pré-requisitos - Token válido — ver [Autenticação](/guia/autenticacao). - Termo assinado pelo titular, digitalizado. - Para a rota dedicada: o `personId`, obtido em [2.3 Cadastro do titular](/guia/fgts-cadastro-pessoa). **Não é necessário** se o termo for enviado na coleção `uploads` do próprio cadastro. ## Os dois caminhos de envio | | **Caminho A — junto do cadastro do titular** | **Caminho B — depois do cadastro** | |---|---|---| | Como | Coleção `uploads` no corpo de `POST /v1/NaturalPerson` | `POST /v1/NaturalPerson/{id}/Upload` | | Exige `personId` antes? | **Não** | Sim | | Chamadas | Uma | Duas | | Quando usar | Fluxo novo — é o **caminho recomendado** nesta ordem. | Titular já cadastrado; termo renovado. | Os campos são **os mesmos** nos dois caminhos. Há ainda um terceiro destino: a coleção `uploads` do `POST /v1/CreditNote`, quando o termo é por contrato. ## Endpoints do cadastro | Método | Rota | Uso | |---|---|---| | POST | `/v1/NaturalPerson` | Caminho A: cria o titular **com** o termo na coleção `uploads`. | | POST | `/v1/NaturalPerson/{id}/Upload` | Caminho B: anexa o termo a um titular que já existe. | | PUT | `/v1/NaturalPerson/{id}/Upload/{uploadId}` | Substitui um termo já anexado (versão corrigida, nova assinatura). | | DELETE | `/v1/NaturalPerson/{id}/Upload/{uploadId}` | Remove um termo do cadastro. | | PUT | `/v1/CreditNote/{id}/upload` | Anexa o termo à operação. Permitido nos status `Draft`, `Revision`, `InstrumentApproval` e `Signatures`. | ## Como preencher ### Documento do consentimento | Campo | Tipo | Obrigatório | Como preencher | Exemplo | |---|---|---|---|---| | `fileType` | enum | Sim | Use `Authorization` — é o tipo que marca o arquivo como termo de autorização. `Others` faz o documento não ser reconhecido como consentimento na esteira. | `Authorization` | | `fileName` | string | Sim | Nome do arquivo com extensão. Prefira nome que identifique o titular e a data sem expor dado pessoal. | `consentimento-fgts-000123.pdf` | | `displayName` | string | Não (envie) | Rótulo exibido para a mesa de crédito. Sem ele a mesa vê apenas o nome do arquivo. | `Consentimento de consulta FGTS` | | `documentDate` | `data e hora` | Não (envie) | Data da assinatura do termo, em UTC com sufixo `Z`. É a data que comprova quando o consentimento foi dado. | `2026-08-25T00:00:00Z` | > O conteúdo do arquivo é enviado pelo mecanismo de upload acordado no onboarding; o corpo desta chamada declara os **metadados** do documento. O termo em si nunca deve trafegar em log nem em anexo de ticket. ### O que o termo precisa conter Não é campo de API, é conteúdo do documento — e é o que a esteira confere na etapa de garantia: | Item | Por que | |---|---| | Identificação do titular (nome e CPF) | Amarra o consentimento ao cadastro. | | Autorização expressa de consulta ao saldo do FGTS | É o objeto do termo. | | Autorização de registro da garantia junto ao órgão | Sem isso a averbação não pode ser solicitada. | | Data e forma de assinatura | Comprova quando e como o consentimento foi dado. | ## Exemplo de request **Caminho A — o termo dentro do cadastro do titular** (recomendado). O corpo completo está em [2.3 Cadastro do titular](/guia/fgts-cadastro-pessoa); aqui, só a parte do documento: ```bash 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", "uploads": [ { "fileType": "Authorization", "fileName": "consentimento-fgts-000123.pdf", "displayName": "Consentimento de consulta FGTS", "documentDate": "2026-08-25T00:00:00Z" } ] }' ``` **Caminho B — termo para um titular que já existe:** ```bash curl --location --request POST '{{baseUrl}}/v1/NaturalPerson/11111111-1111-1111-1111-111111111111/Upload' \ --header 'Authorization: Bearer {{token}}' \ --header 'Content-Type: application/json' \ --header 'Accept: application/json' \ --data '[ { "fileType": "Authorization", "fileName": "consentimento-fgts-000123.pdf", "displayName": "Consentimento de consulta FGTS", "documentDate": "2026-08-25T00:00:00Z" } ]' ``` ## Exemplo de response ```json [ { "id": "66666666-6666-6666-6666-666666666666", "fileType": "Authorization", "fileName": "consentimento-fgts-000123.pdf", "displayName": "Consentimento de consulta FGTS", "documentDate": "2026-08-25T00:00:00Z" } ] ``` Guarde o `id` do upload: é a referência para substituir o termo por uma versão nova. ## Códigos de retorno | Código | Significado | O que fazer | |---|---|---| | `200` | Documento anexado. | Guarde o `id` do upload. | | `400` | `fileType` inválido, `fileName` ausente ou sem extensão. | Confira a tabela de preenchimento. | | `401` | Token ausente, expirado ou inválido. | Renove o token — ver [Autenticação](/guia/autenticacao). | | `403` | Sem permissão sobre esse cadastro ou operação. | Confirme o vínculo do cadastro com o seu usuário/correspondente. | | `404` | `personId`, `uploadId` ou `id` da operação inexistente. | Confira os identificadores. | | `409` | Upload na operação em status que não aceita alteração de documentos. | Aguarde a devolução para revisão. Ver [4.1 Eventos e notificações](/guia/fgts-eventos). | ## Duração e validade A pergunta prática é a mesma do consignado — *por quanto tempo este consentimento continua servindo?* —, mas a resposta é diferente, e a diferença é estrutural. | | FGTS | |---|---| | O que define o prazo | **A sua política de retenção**, alinhada com o Compliance da UY3. Não há prazo imposto por um órgão externo. | | Quando começa a contar | Da assinatura do termo — `documentDate`. | | Onde ler a data-base | Campo `documentDate` do upload. | | Existe campo de expiração no contrato? | Não. E também não existe status: o termo é um arquivo, não um registro com ciclo de vida. | | O que acontece quando "expira" | **Nada automático.** Nenhuma chamada é recusada por termo antigo. O risco é de conformidade, não de integração. | | Como renovar | Colete um termo novo e anexe (`POST`), ou substitua o anterior (`PUT .../Upload/{uploadId}`). | **Consequência para quem integra.** No consignado, a API te avisa quando a autorização não vale mais: a consulta de margem é recusada. Aqui **não há esse aviso** — o termo velho continua no dossiê e a operação segue. O controle é do seu lado. Recomendação prática: 1. Guarde a data de assinatura do termo junto do seu cadastro de cliente. 2. Defina um prazo de revalidação com o Compliance e trate-o no seu processo, não esperando erro da API. 3. Ao contratar de novo para um titular antigo, colete termo novo em vez de reaproveitar o anexado há muito tempo — é a operação nova que está sendo autorizada. **Diferença em relação ao Consignado privado.** Lá o prazo é imposto pelo Crédito do Trabalhador, a autorização tem status próprio e a API bloqueia a consulta quando ela não vale mais — ver [Consignado privado — Autorização de margem](/guia/consignado-privado-cadastro-autorizacao). Os dois módulos são espelhados na estrutura, e esta etapa é a única em que a mecânica divergiu; a razão é que o FGTS não tem um registro de autorização junto a terceiro, e o consignado tem. > Orientação técnica. A base legal do tratamento, o prazo de retenção e a forma de guarda do consentimento são competência do Compliance/Jurídico da UY3 (LGPD, Lei 13.709/2018, art. 7º e art. 37). Esta página não substitui parecer. ## O que acontece depois O documento passa a compor o dossiê. Na etapa de garantia, a esteira confere a presença do termo antes de solicitar a averbação ao órgão: sem ele a operação é devolvida com documento obrigatório ausente — e isso acontece **depois** de a operação já existir, o que é o momento mais caro para descobrir. Anexe desde o cadastro. ## Antes desta etapa - [2. Pré-requisitos e cadastros](/guia/fgts-cadastros) — por que este é o primeiro passo e como ele difere do consignado. ## Próxima etapa - [2.2 Conta de liquidação](/guia/fgts-cadastro-conta) — a conta de destino do valor liberado. - O termo é conferido na etapa de garantia, em [3. Operação](/guia/fgts-operacao). ## Downloads - Contexto para LLM deste módulo: [llms-fgts.txt](/downloads/llms-fgts.txt) - Collection Postman do módulo: [uy3-fgts.postman_collection.json](/downloads/uy3-fgts.postman_collection.json) - Documentação consolidada para LLM: [llms.txt](/downloads/llms.txt) --- ## /guia/fgts-cadastro-conta — 2.2 Conta de liquidação # 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](/guia/convencoes-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 | | **Caminho A — junto do cadastro do titular** | **Caminho B — depois do cadastro** | |---|---|---| | Como | Coleção `bankAccounts` no corpo de `POST /v1/NaturalPerson` | `POST /v1/NaturalPerson/{id}/BankAccount` | | Exige `personId` antes? | **Não** | Sim | | Chamadas | Uma | Duas | | Quando usar | Fluxo novo — é o **caminho recomendado** nesta ordem de cadastros. | Titular já cadastrado; troca ou acréscimo de conta. | 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](/guia/autenticacao). - Dados bancários do titular, conferidos com ele. - Para o **caminho B**: o `personId`, obtido em [2.3 Cadastro do titular](/guia/fgts-cadastro-pessoa). ## Endpoints do cadastro | Método | Rota | Uso | |---|---|---| | POST | `/v1/NaturalPerson` | Caminho A: cria o titular **com** a conta na coleção `bankAccounts`. | | POST | `/v1/NaturalPerson/{id}/BankAccount` | Caminho B: cadastra uma ou mais contas para um titular que já existe. | | PUT | `/v1/NaturalPerson/{id}/BankAccount/{bankAccountId}` | Corrige os dados de uma conta já cadastrada. | | DELETE | `/v1/NaturalPerson/{id}/BankAccount/{bankAccountId}` | Remove uma conta. Recusado quando a conta está amarrada a operação em andamento. | | GET | `/v1/NaturalPerson/{id}` | Lista as contas do titular, para reaproveitar o `bankAccountId`. | ## Como preencher ### Meio de liquidação | Campo | Tipo | Obrigatório | Como preencher | Exemplo | |---|---|---|---|---| | `operationTypeValue` | enum | Sim | Meio de liquidação da conta: `Pix` ou `Transfer` (TED). Define quais dos campos abaixo passam a ser exigidos — decida isto primeiro. | `Pix` | | `type` | enum | Não (envie) | Natureza da conta. Para o titular PF, use `NaturalCheckingAccount` (corrente) ou `NaturalSavingsAccount` (poupança). | `NaturalCheckingAccount` | | `jointAccount` | booleano | Não | `true` para conta conjunta. Conta conjunta pode exigir documento adicional na esteira. | `false` | ### Quando `operationTypeValue` é `Pix` | Campo | Tipo | Obrigatório | Como preencher | Exemplo | |---|---|---|---|---| | `pixKeyTypeValue` | enum | Sim | Tipo da chave: `NaturalRegistrationNumber` (CPF), `Phone`, `Email`, `Automatic` (aleatória) ou `AgencyAndAccount`. | `NaturalRegistrationNumber` | | `keyPix` | string | Sim | A chave, no formato do tipo escolhido. Com `NaturalRegistrationNumber`, use o **mesmo CPF** do titular — chave de terceiro é recusada na liquidação. | `000.000.000-00` | | `bankCode` | inteiro | Não | Código Compe do banco da chave. Ajuda a conciliação; não substitui a chave. | `341` | ### Quando `operationTypeValue` é `Transfer` (TED) | Campo | Tipo | Obrigatório | Como preencher | Exemplo | |---|---|---|---|---| | `bankCode` | inteiro | Sim | Código Compe do banco (3 dígitos). Alternativa: informe `bankIspb`. | `341` | | `bankIspb` | inteiro | Condicional | ISPB do banco, quando o código Compe não estiver disponível. | `60701190` | | `agency` | string | Sim | Agência, até 4 dígitos, sem o dígito verificador. | `0001` | | `agencyDigit` | string | Não | Dígito da agência, 1 caractere, quando o banco usar. | `0` | | `account` | string | Sim | Número da conta, sem o dígito verificador e sem pontuação. | `12345678` | | `accountDigit` | string | Sim | Dígito verificador da conta, 1 caractere. | `9` | > **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](/guia/fgts-cadastro-pessoa); aqui, só a parte da conta: ```bash 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:** ```bash 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: ```json { "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 | Código | Significado | O que fazer | |---|---|---| | `200` | Conta cadastrada. | Guarde o `id` da conta como `bankAccountId`. | | `400` | Combinação inválida: `Pix` sem chave, `Transfer` sem agência/conta, dígito com mais de 1 caractere. | Confira a tabela do meio de liquidação escolhido. | | `401` | Token ausente, expirado ou inválido. | Renove o token — ver [Autenticação](/guia/autenticacao). | | `403` | Sem permissão sobre esse cadastro de pessoa. | Confirme o vínculo do cadastro com o seu usuário/correspondente. | | `404` | `personId` ou `bankAccountId` inexistente (caminho B). | Confira os identificadores. | ## 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](/guia/fgts-cadastro-autorizacao) — o passo anterior da sequência. ## Próxima etapa - [2.3 Cadastro do titular](/guia/fgts-cadastro-pessoa) — onde o objeto da conta é enviado, no caminho recomendado. - O `bankAccountId` é consumido em [3. Operação](/guia/fgts-operacao). ## Downloads - Contexto para LLM deste módulo: [llms-fgts.txt](/downloads/llms-fgts.txt) - Collection Postman do módulo: [uy3-fgts.postman_collection.json](/downloads/uy3-fgts.postman_collection.json) - Documentação consolidada para LLM: [llms.txt](/downloads/llms.txt) --- ## /guia/fgts-cadastro-pessoa — 2.3 Cadastro do titular # 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](/guia/convencoes-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](/guia/autenticacao). - **Termo de consentimento assinado e digitalizado** — ver [2.1 Consentimento de consulta](/guia/fgts-cadastro-autorizacao). Ele vai na coleção `uploads` deste mesmo corpo. - Dados da conta de liquidação preparados — ver [2.2 Conta de liquidação](/guia/fgts-cadastro-conta). Eles vão na coleção `bankAccounts` deste mesmo corpo. ## Endpoints do cadastro | Método | Rota | Uso | |---|---|---| | POST | `/v1/NaturalPerson` | Cria ou atualiza a Pessoa Física, com a conta em `bankAccounts` e o termo em `uploads`, e devolve o `personId`. | | GET | `/v1/NaturalPerson` | Busca por CPF, nome, e-mail ou telefone antes de criar. | | GET | `/v1/NaturalPerson/{id}` | Consulta o cadastro completo por identificador. | | PUT | `/v1/NaturalPerson/{id}` | Atualiza o cadastro. Coleções não enviadas são **excluídas** — envie `null` para preservá-las. | | POST | `/v1/NaturalPerson/{id}/Upload` | Anexa documentos ao 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](/guia/fgts-cadastro-conta). ## Como preencher ### Identificação (obrigatória em qualquer produto) | Campo | Tipo | Obrigatório | Como preencher | Exemplo | |---|---|---|---|---| | `registrationNumber` | string | Sim | CPF do titular da conta FGTS, só dígitos. É a chave de deduplicação do cadastro. | `000.000.000-00` | | `name` | string | Sim | Nome civil completo, como consta no documento de identidade. Sem abreviar. | `MARIA D*** S*** LIMA` | | `email` | string | Sim | E-mail válido do próprio titular — é por ele que a assinatura eletrônica é enviada. | `titular@exemplo.com.br` | | `phone` | string | Sim | Celular com DDD, ativo. Usado nas validações de identidade do fluxo. | `(11) 9****-**00` | | `birthDate` | `data civil` | Não (envie) | Data de nascimento. Usada na validação de identidade. | `1988-04-12` | | `mothersName` | string | Não (envie) | Nome completo da mãe. Segundo fator da validação de identidade. | `ANA F*** D*** S***` | | `socialName` | string | Não | Nome social, quando houver. Não substitui `name` nos documentos. | `—` | | `pep` | booleano | Não | `true` se o titular é pessoa exposta politicamente. Afeta a análise de compliance. | `false` | ### Dados que este produto exige de fato | Campo | Tipo | Obrigatório | Como preencher | Exemplo | |---|---|---|---|---| | `address` | objeto | Sim para este produto | Endereço residencial completo. Exigido na emissão do instrumento de crédito. Dentro do objeto, `addressName` (logradouro), `city` e `district` são **obrigatórios**. | ver exemplo abaixo | | `documentType` | enum | Sim para este produto | Tipo do documento de identidade apresentado. Aceitos: `RG`, `CPF`, `CNH`, `CTPS`. | `RG` | | `documentNumber` | string | Sim para este produto | Número do documento, como impresso. | `00.000.000-0` | | `documentIssuer` | string | Não (envie) | Órgão emissor do documento. | `SSP/SP` | | `documentDate` | `data civil` | Não (envie) | Data de emissão do documento. | `2016-02-20` | | `nationality` | string | Não | Nacionalidade do titular. | `Brasileira` | | `civilStatus` | enum | Não | Estado civil. Pode exigir dados do cônjuge na emissão do instrumento. | `Single` | | `netSalary` | `decimal em reais` | Não | Renda mensal. Não define o limite da operação neste produto — o saldo do FGTS define. | `3200.00` | > "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 | Campo | Tipo | Obrigatório | Como preencher | Exemplo | |---|---|---|---|---| | `bankAccounts` | lista de objetos | Sim para este produto | A conta que vai receber o valor liberado. Campo a campo em [2.2 Conta de liquidação](/guia/fgts-cadastro-conta) — enviar aqui é o caminho recomendado. | ver exemplo abaixo | | `uploads` | lista de objetos | Sim na prática | O termo de consentimento, com `fileType: "Authorization"`. Campo a campo em [2.1 Consentimento de consulta](/guia/fgts-cadastro-autorizacao). Sem ele a operação é devolvida na etapa de garantia. | ver exemplo abaixo | 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](/guia/consignado-privado-cadastro-pessoa). ## Exemplo de request ```bash 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 ```json { "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 | Código | Significado | O que fazer | |---|---|---| | `200` | Cadastro criado ou atualizado. | Guarde o `id` como `personId` e o `id` da conta como `bankAccountId`. | | `400` | Corpo inválido: CPF malformado, e-mail inválido, campo obrigatório ausente, conta com combinação inválida, `fileType` inválido. | Corrija o campo apontado na resposta e reenvie. | | `401` | Token ausente, expirado ou inválido. | Renove o token — ver [Autenticação](/guia/autenticacao). | | `403` | Sem permissão para criar ou ver esse cadastro. | Confirme o perfil do usuário/correspondente com a UY3. | | `404` | Identificador inexistente (nas rotas com `{id}`). | Confira o `personId`. | ## 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](/guia/fgts-cadastro-conta) — os campos da conta enviada aqui. - [2.1 Consentimento de consulta](/guia/fgts-cadastro-autorizacao) — os campos do termo enviado aqui. ## Próxima etapa - [3. Operação](/guia/fgts-operacao) — simulação, criação da operação e envio para aprovação. ## Downloads - Contexto para LLM deste módulo: [llms-fgts.txt](/downloads/llms-fgts.txt) - Collection Postman do módulo: [uy3-fgts.postman_collection.json](/downloads/uy3-fgts.postman_collection.json) - Documentação consolidada para LLM: [llms.txt](/downloads/llms.txt) --- ## /guia/fgts-operacao — 3. Operação # FGTS — Operação 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, de valor e de taxa: [Convenções de dados](/guia/convencoes-de-dados). ## O que é Esta é a página do fluxo principal: da simulação até a operação assinada e liquidada. Ela assume que os três cadastros de [2. Pré-requisitos e cadastros](/guia/fgts-cadastros) já existem. A sequência é mais curta que a do [Consignado privado](/guia/consignado-privado-operacao) porque não há margem a consultar nem proposta a enviar ao empregador: o lastro já existe na conta do FGTS do titular. O que decide o valor é **quantos saques-aniversário podem ser antecipados** e a faixa de taxa e prazo do produto contratado. ## Quando usar - Sempre que houver um titular cadastrado, termo anexado e valor a antecipar. - Para retomar uma operação em rascunho que precisa de correção antes do envio à aprovação. ## Pré-requisitos | Item | Origem | |---|---| | Termo de consentimento anexado | [2.1 Consentimento de consulta](/guia/fgts-cadastro-autorizacao) | | `bankAccountId` | [2.2 Conta de liquidação](/guia/fgts-cadastro-conta) | | `personId` | [2.3 Cadastro do titular](/guia/fgts-cadastro-pessoa) | | `productId` | Fornecido pela UY3 no onboarding | | Token válido | [Autenticação](/guia/autenticacao) | ## Endpoints do fluxo principal ### Passo 1 — Simular a antecipação ```http POST /v1/Amortization GET /v1/Amortization/{id} POST /v1/Amortization/Batch ``` Gera o plano de pagamento da antecipação: parcelas anuais, CET, IOF e custo de emissão. O corpo é o **mesmo objeto de cálculo** enviado na criação da operação — ver a seção **Como preencher** abaixo. Isso é uma vantagem prática: o corpo que você simulou é o corpo que você cria, sem tradução. `GET /v1/Amortization/{id}` recupera uma simulação já gerada, sem simular de novo. `POST /v1/Amortization/Batch` simula várias condições em uma chamada — útil para oferecer ao titular mais de um prazo. | Parâmetro | Tipo | Obrigatório | Como preencher | Exemplo | |---|---|---|---|---| | `amortizationType` | string | Sim | `fgts`. Nenhum outro valor descreve este produto. | `fgts` | | `requestedAmount` | `inteiro em centavos` | Sim | Valor pretendido. | `150000` (= R$ 1.500,00) | | `termInMonths` | inteiro | Sim | Prazo em meses. Corresponde aos saques-aniversário antecipados. | `24` | | `apr` | número | Sim | Taxa de juros **mensal**, em porcentagem, dentro da faixa do produto. | `2.09` | | `startDate` | `data e hora` | Sim | Data base da operação, em UTC. | `2026-08-25T00:00:00Z` | | `paymentMonth` | enum | Não (envie) | Mês do saque-aniversário do titular. Sem ele o cronograma não se ancora no mês certo. | `August` | ```bash curl --location --request POST '{{baseUrl}}/v1/Amortization' \ --header 'Authorization: Bearer {{token}}' \ --header 'Content-Type: application/json' \ --header 'Accept: application/json' \ --data '{ "productId": "44444444-4444-4444-4444-444444444444", "legalPerson": false, "amortization": { "amortizationType": "fgts", "requestedAmount": 150000, "termInMonths": 24, "apr": 2.09, "startDate": "2026-08-25T00:00:00Z", "paymentMonth": "August" } }' ``` O objeto de cálculo vai dentro de `amortization`; a raiz exige `productId` e `legalPerson`, os dois **obrigatórios** no contrato. No FGTS o titular é pessoa física, então `legalPerson` é `false`. Os campos da tabela acima são os de dentro de `amortization`. > **Há só um caminho de simulação neste produto.** O [Consignado privado](/guia/consignado-privado-operacao) tem dois — ofertas e amortização —, porque lá existe uma margem consignável contra a qual comparar produtos habilitados. Aqui não há margem nem vitrine a comparar: o lastro é um saldo que já existe, e o que resta é dimensionar valor e prazo. A simulação por amortização faz exatamente isso. > **Saldo disponível do FGTS.** A apuração do saldo antecipável do titular acontece na etapa de averbação, dentro da esteira, e não é exposta como consulta ao parceiro nesta API. Dimensione o `requestedAmount` pelo valor combinado com o titular; se ele exceder o antecipável, a operação é devolvida na garantia. Ver [5. Erros e troubleshooting](/guia/fgts-erros). ### Passo 2 — Criar a operação de crédito ```http POST /v1/CreditNote ``` | Parâmetro | Local | Obrigatório | Como preencher | Exemplo | |---|---|---|---|---| | `updateStartDate` | query | Não | `true` para a API reposicionar a data de início no dia da criação. | `true` | | `returnValue` | query | Não | `true` para o retorno vir com a operação completa em vez de apenas o identificador. | `true` | Corpo: ver **Como preencher** abaixo. A operação nasce em `Draft` (rascunho) ou já em `ComplianceApproval`, conforme a configuração do produto contratado. ### Passo 3 — Documentos ```http PUT /v1/CreditNote/{id}/upload PUT /v1/CreditNote/{id} ``` Os documentos podem ir **no corpo da criação** (coleção `uploads`) **ou** ser anexados depois, pela rota acima. Ver a seção **Documentos: `uploads`, e por que não há `warranty`** em Como preencher. `PUT /v1/CreditNote/{id}` corrige atributos da operação — permitido apenas nos status `Draft`, `Revision`, `Disapproved` e `Error`. ### Passo 4 — Enviar para aprovação ```http POST /v1/CreditNote/{id}/submitapproval ``` | Parâmetro | Local | Obrigatório | Como preencher | Exemplo | |---|---|---|---|---| | `id` | rota | Sim | Identificador da operação criada no passo 2. | `55555555-5555-5555-5555-555555555555` | | `updateStartDate` | query | Não | `true` para reposicionar a data de início no envio. | `false` | ```bash curl --location --request POST '{{baseUrl}}/v1/CreditNote/55555555-5555-5555-5555-555555555555/submitapproval' \ --header 'Authorization: Bearer {{token}}' \ --header 'Accept: application/json' ``` Depois do envio, **a operação não pode mais ser alterada** até o fim da análise. O envio é bloqueado quando o titular excede o limite anual de contratos — cada saque-aniversário só pode ser antecipado uma vez. ### Passo 5 — Assinatura eletrônica ```http GET /v1/CreditNote/{id}/SignUrl ``` Devolve as URLs de assinatura para você entregar ao titular. A coleta em si acontece fora da API, no provedor de assinatura. Disponível a partir do status `Signatures`. Se você já tem o instrumento assinado em mãos antes disso, ele pode ser enviado como documento na criação — ver a seção sobre `uploads` em Como preencher. ### Passo 6 — Averbação no órgão A averbação **não é uma rota que você chama**: é uma etapa da esteira, exclusiva deste produto. A operação assume o status de garantia (`Warranty`) e aguarda o retorno do órgão, respeitando a janela de manutenção dele. Você acompanha por consulta — ver [4. Consultas e acompanhamento](/guia/fgts-consultas). Quando a mesa devolve a garantia para revisão (`WarrantyRevision`), o encerramento da revisão é feito por: ```http POST /v1/CreditNote/{id}/doneWarrantyRevision ``` ### Passo 7 — Cancelar, excluir ou restaurar ```http POST /v1/CreditNote/{id}/cancel DELETE /v1/CreditNote/{id} POST /v1/CreditNote/{id}/restore ``` O cancelamento é uma **ação única, sem parâmetros de controle**: você chama `cancel` e o desfazimento do registro no órgão faz parte do processamento pela esteira. | Campo | Tipo | Obrigatório | Como preencher | Exemplo | |---|---|---|---|---| | `message` | corpo | Não (envie) | Motivo do cancelamento, em texto. Fica no histórico da operação e é o que a mesa lê. | `Desistencia do titular` | ```bash curl --location --request POST '{{baseUrl}}/v1/CreditNote/55555555-5555-5555-5555-555555555555/cancel' \ --header 'Authorization: Bearer {{token}}' \ --header 'Content-Type: application/json' \ --header 'Accept: application/json' \ --data '{ "message": "Desistencia do titular" }' ``` **Acompanhe até `Canceled`.** Se a operação já estava averbada, o desfazimento no órgão faz parte do processamento e o status é o sinal de que terminou. Só contrate de novo para o mesmo titular depois disso — antes, o saque-aniversário pode ainda estar comprometido com a operação anterior. A exclusão (`DELETE`) é lógica e só é permitida nos status `Draft`, `Revision`, `Disapproved` e `Canceled`. `restore` desfaz a exclusão. ## Como preencher ### Nível da operação — corpo de `POST /v1/CreditNote` | Campo | Tipo | Obrigatório | Como preencher | Exemplo | |---|---|---|---|---| | `productId` | string (uuid) | Sim | Produto contratado de FGTS, fornecido pela UY3. Define o modelo de cálculo e as faixas de taxa e prazo. | `33333333-3333-3333-3333-333333333333` | | `personId` | string (uuid) | Sim | O titular. Precisa estar vinculado ao seu usuário/correspondente. | `11111111-1111-1111-1111-111111111111` | | `amortization` | objeto | Sim | Objeto de cálculo do FGTS. Ver a tabela abaixo. | ver abaixo | | `uploads` | lista de objetos | Sim na prática | Documentos da operação, incluindo o termo de consentimento. Sem ele a operação é devolvida na garantia. | ver abaixo | | `liquidationType` | enum | Sim para este produto | Use `EletronicTransfer`. `Invoice` (boleto) não se aplica ao FGTS. | `EletronicTransfer` | | `bankAccountId` | string (uuid) | Sim para este produto | Conta de destino do valor liberado. | `22222222-2222-2222-2222-222222222222` | | `emissionDate` | `data e hora` | Não | Data de emissão do instrumento. Omita para usar a data da criação. | `2026-08-25T00:00:00Z` | | `newPersonAndAccount` | objeto | Não | Cria titular e conta na própria criação, dispensando os cadastros 2.2 e 2.3. Alternativa a `personId` + `bankAccountId`. | ver [2.3 Cadastro do titular](/guia/fgts-cadastro-pessoa) | | `observations` | string | Não | Observação livre para a mesa de crédito. | `Antecipacao saque-aniversario` | | `warranty` | lista de objetos | **Não envie** | O FGTS não usa garantia por tipo. Ver a seção sobre documentos abaixo. | — | ### Objeto de cálculo — modelo FGTS O modelo de cálculo do FGTS é o mais enxuto do catálogo. **Somente os campos abaixo se aplicam.** | Campo | Tipo | Obrigatório | Como preencher | Exemplo | |---|---|---|---|---| | `amortizationType` | string | Sim | Discriminador do modelo. Valor literal `fgts`. Comparação sem distinção de caixa. | `fgts` | | `requestedAmount` | `inteiro em centavos` | Sim | Valor contratado. **Não tem sufixo `InCents` e ainda assim é em centavos.** | `150000` (= R$ 1.500,00) | | `termInMonths` | inteiro | Sim | Prazo em meses, correspondente aos saques-aniversário antecipados. Precisa estar na faixa de prazo do produto. | `24` | | `apr` | número | Sim | Taxa de juros **mensal**, em porcentagem. Precisa estar na faixa do produto e ser maior que zero. | `2.09` | | `startDate` | `data e hora` | Sim | Data base de cálculo do contrato. | `2026-08-25T00:00:00Z` | | `paymentMonth` | enum | Não (envie) | Mês do saque-aniversário do titular: `January` a `December` (ou `NotSet`). Sem ele o cronograma não se ancora no mês do saque. | `August` | | `includePaymentFixedCosts` | booleano | Não | `true` para embutir custos fixos na parcela. | `false` | **Não envie** neste produto: `paymentDay`, `absAmortizationInMonths`, `absInterestInMonths`, `daysInYear`, `periodicity`, `paymentPeriodicity`, `firstPaymentDate`, `numberOfPayments`, `calculationType`, `calculateByValueType`, `indexer`, `indexerValue`, `firstPaymentInterest`, `fiduciaryGuarantee`, `financeTaxExempted`. Esses campos pertencem a outros modelos de cálculo e indicam objeto errado — se você precisa deles, o produto pretendido é provavelmente [Consignado privado](/guia/consignado-privado-operacao). ### Documentos: `uploads`, e por que não há `warranty` O `POST /v1/CreditNote` aceita documento e garantia em duas coleções. **Neste produto, só uma delas é usada:** | Coleção | O que vai nela | Neste produto | |---|---|---| | `uploads` | Os **arquivos** da operação — termo de consentimento, instrumento assinado, comprovantes. | **Use sempre.** | | `warranty` | Os **dados** de uma garantia por tipo — vínculo, bem, margem. | **Não use.** O lastro do FGTS é o saldo do titular, e a averbação é etapa dedicada da esteira. Não existe tipo de garantia `FGTS` na lista de tipos de garantia. | Enviar `warranty` aqui cria uma garantia sem correspondência no produto — a rota `PUT /v1/CreditNote/{id}/warranty` existe no contrato, mas não se aplica ao FGTS. | Campo | Tipo | Obrigatório | Como preencher | Exemplo | |---|---|---|---|---| | `uploads[].fileType` | enum | Sim (no item) | Tipo do documento. `Authorization` para o termo de consentimento; `SignedContract` para o instrumento já assinado; `Others` para o resto. | `Authorization` | | `uploads[].fileName` | string | Sim (no item) | Nome do arquivo, com extensão. | `consentimento-fgts-000123.pdf` | | `uploads[].displayName` | string | Não (envie) | Rótulo exibido na mesa. Sem ele a mesa vê só o nome do arquivo. | `Consentimento de consulta FGTS` | | `uploads[].documentDate` | `data e hora` | Não | Data do documento. | `2026-08-25T00:00:00Z` | **Documento assinado enviado em rascunho permanece disponível para a assinatura.** Se você já tem o instrumento assinado — coleta presencial, assinatura em canal próprio — envie-o em `uploads` com `fileType: "SignedContract"` enquanto a operação está em `Draft`. Desde que a coleção não esteja vazia, o documento continua vinculado à operação e é aproveitado quando ela chega à etapa de assinatura, em vez de a esteira pedir uma coleta nova. Duas consequências práticas: - **Não envie `uploads` vazio** (`[]`) esperando anexar depois "por segurança". Coleção vazia não reserva lugar; ou você manda o documento, ou anexa por `PUT /v1/CreditNote/{id}/upload` antes do `submitapproval`. - **Não reenvie o mesmo documento** em cada etapa. Ele permanece; reenviar gera duplicata no dossiê. ## Exemplo de request ```bash curl --location --request POST '{{baseUrl}}/v1/CreditNote?returnValue=true' \ --header 'Authorization: Bearer {{token}}' \ --header 'Content-Type: application/json' \ --header 'Accept: application/json' \ --data '{ "productId": "33333333-3333-3333-3333-333333333333", "personId": "11111111-1111-1111-1111-111111111111", "liquidationType": "EletronicTransfer", "bankAccountId": "22222222-2222-2222-2222-222222222222", "observations": "Antecipacao saque-aniversario", "amortization": { "amortizationType": "fgts", "requestedAmount": 150000, "termInMonths": 24, "apr": 2.09, "startDate": "2026-08-25T00:00:00Z", "paymentMonth": "August", "includePaymentFixedCosts": false }, "uploads": [ { "fileType": "Authorization", "fileName": "consentimento-fgts-000123.pdf", "displayName": "Consentimento de consulta FGTS", "documentDate": "2026-08-25T00:00:00Z" } ] }' ``` Para enviar o instrumento **já assinado** junto da criação, acrescente um item a `uploads`: ```json { "fileType": "SignedContract", "fileName": "instrumento-assinado.pdf", "displayName": "Instrumento assinado", "documentDate": "2026-08-25T00:00:00Z" } ``` ## Exemplo de response ```json { "id": "55555555-5555-5555-5555-555555555555", "creditNoteNo": "2026/000456", "status": "Draft", "productId": "33333333-3333-3333-3333-333333333333", "personId": "11111111-1111-1111-1111-111111111111", "amortization": { "amortizationType": "fgts", "requestedAmount": 150000, "termInMonths": 24, "apr": 2.09, "paymentMonth": "August" }, "warranty": [], "uploads": [ { "fileType": "Authorization", "fileName": "consentimento-fgts-000123.pdf" } ] } ``` Guarde o `id`: é ele que identifica a operação em todas as etapas seguintes e nas consultas. A coleção `warranty` volta vazia — é o esperado neste produto. ## Códigos de retorno | Código | Significado | O que fazer | |---|---|---| | `200` | Etapa concluída. | Siga para a etapa seguinte com o `id` devolvido. | | `400` | Validação de negócio ou de contrato: modelo de cálculo divergente do produto, taxa fora da faixa, prazo fora da faixa, campos de outro modelo enviados. | Ver [5. Erros e troubleshooting](/guia/fgts-erros). | | `401` | Token ausente, expirado ou inválido. | Renove o token — ver [Autenticação](/guia/autenticacao). | | `403` | Sem permissão para a ação, ou titular não vinculado ao usuário/correspondente. | Ver [5. Erros e troubleshooting](/guia/fgts-erros). | | `404` | Operação, titular, conta ou produto inexistente. | Confira os identificadores das etapas anteriores. | | `409` | Ação inválida para o status atual da operação. | Consulte o status antes de repetir — ver [4. Consultas e acompanhamento](/guia/fgts-consultas). | ## O que acontece depois Depois do `submitapproval`, a operação percorre a esteira: análise de crédito, compliance, **garantia (averbação no órgão)**, aprovação do instrumento e coleta de assinaturas. Confirmada a averbação e concluídas as assinaturas, a operação entra em liquidação e o valor é transferido por Pix ou TED para a conta cadastrada. A partir daí, a cada ano, o saque-aniversário do titular é debitado na origem e amortiza o contrato — sem nova chamada de API sua. Cada uma dessas transições é um evento observável. O ciclo completo, evento por evento, está em [4.1 Eventos e notificações](/guia/fgts-eventos). ## Antes desta etapa - [2.3 Cadastro do titular](/guia/fgts-cadastro-pessoa) — o `personId` e o `bankAccountId` consumidos aqui. - [2. Pré-requisitos e cadastros](/guia/fgts-cadastros) — índice dos três cadastros e a ordem entre eles. ## Próxima etapa - [4. Consultas e acompanhamento](/guia/fgts-consultas) — status, parcelas e comprovante de transferência. - [4.1 Eventos e notificações](/guia/fgts-eventos) — o ciclo de vida completo, evento por evento. - [5. Erros e troubleshooting](/guia/fgts-erros) — quando alguma etapa acima falhar. ## Downloads - Contexto para LLM deste módulo: [llms-fgts.txt](/downloads/llms-fgts.txt) - Collection Postman do módulo: [uy3-fgts.postman_collection.json](/downloads/uy3-fgts.postman_collection.json) - Collection completa (Consignado privado + FGTS): [uy3-api-completa.postman_collection.json](/downloads/uy3-api-completa.postman_collection.json) - Documentação consolidada para LLM: [llms.txt](/downloads/llms.txt) --- ## /guia/fgts-consultas — 4. Consultas e acompanhamento # FGTS — Consultas e acompanhamento 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](/guia/convencoes-de-dados). ## O que é Depois do envio para aprovação a operação sai das suas mãos e percorre a esteira da UY3. Esta página reúne as consultas que respondem "onde está a operação, o que falta e o que já foi pago". O acompanhamento do FGTS é **por consulta**: você pergunta, a API responde com o status atual. O que cada transição de status significa, e o que fazer em cada uma, está em [4.1 Eventos e notificações](/guia/fgts-eventos). ## Quando usar - Entre o `submitapproval` e a liquidação, para saber em que etapa a operação está. - Depois da liquidação, para obter o comprovante de transferência. - Ao longo do contrato, para consultar o cronograma de parcelas anuais e o saldo. - Em rotina de reconciliação diária ou semanal da sua carteira. ## Pré-requisitos - `id` da operação — devolvido em [3. Operação](/guia/fgts-operacao). - Token válido — ver [Autenticação](/guia/autenticacao). ## Endpoints de consulta ### Status e dados da operação ```http GET /v1/CreditNote/{id} GET /v1/CreditNote ``` `GET /v1/CreditNote/{id}` devolve a operação completa: status, cálculo, documentos, assinaturas e cronograma. É a consulta que responde "e agora?". `GET /v1/CreditNote` lista operações com filtros. Os que interessam ao acompanhamento do FGTS: | Parâmetro | Local | Obrigatório | Como preencher | Exemplo | |---|---|---|---|---| | `status` | query | Não | Status a filtrar. Combine com paginação para varrer a fila de uma etapa. | `Warranty` | | `personId` | query | Não | Todas as operações de um titular — é a consulta que confere o limite anual de contratos. | `11111111-1111-1111-1111-111111111111` | | `productId` | query | Não | Todas as operações de um produto contratado. | `33333333-3333-3333-3333-333333333333` | | `creditNoteNo` | query | Não | Número da operação, quando você tem o número e não o `id`. | `2026/000456` | | `initialDate` / `finalDate` | `data civil` (query) | Não | Janela de criação. Use para varredura incremental. | `2026-08-01` / `2026-08-31` | | `initialPaymentDate` / `finalPaymentDate` | `data civil` (query) | Não | Janela de vencimento de parcela — no FGTS, o mês do saque-aniversário. | `2027-08-01` / `2027-08-31` | | `minValue` / `maxValue` | `inteiro em centavos` (query) | Não | Faixa de valor contratado. | `50000` / `1000000` | | `isDeleted` | query | Não | `true` para incluir operações excluídas logicamente. | `false` | | `page` / `size` | query | Não | Paginação. Mantenha `size` moderado em varredura. | `1` / `50` | | `orderBy` | query | Não | Campo de ordenação. | `createDate desc` | ```bash curl --location --request GET '{{baseUrl}}/v1/CreditNote/55555555-5555-5555-5555-555555555555' \ --header 'Authorization: Bearer {{token}}' \ --header 'Accept: application/json' ``` ### Assinatura ```http GET /v1/CreditNote/{id}/SignUrl ``` Devolve as URLs de coleta de assinatura, para entregar ao titular. Disponíveis a partir do status `Signatures`. O andamento da coleta é lido no próprio `GET /v1/CreditNote/{id}`. ### Liquidação e comprovante ```http GET /v1/CreditNote/{id}/transferReceipt ``` Devolve o comprovante da transferência (Pix ou TED) feita ao titular. Disponível a partir da liquidação. ### Cronograma de parcelas e quitação ```http POST /v1/CreditNote/{id}/DuePaymentSchedule GET /v1/CreditNote/{id}/LiquidationScheduleCreditNote ``` `DuePaymentSchedule` calcula o calendário de quitação da operação — o que o titular deve para liquidar antecipadamente em uma data, antes do próximo saque-aniversário. ### Consultas dos cadastros ```http GET /v1/NaturalPerson/{id} GET /v1/NaturalPerson ``` Confirmam os dados do titular e os documentos anexados. **É a consulta que verifica se o termo de consentimento está no dossiê** — como o FGTS não tem registro de autorização com status próprio, essa conferência substitui a listagem de autorizações do consignado. Ver [2.1 Consentimento de consulta](/guia/fgts-cadastro-autorizacao). ### Extração em lote ```http GET /v1/CreditNote/Export/excel GET /v1/CreditNote/related-operations ``` `Export/excel` exporta a carteira filtrada em planilha — use para conciliação periódica, não para acompanhamento de operação individual. ## Webhooks O acompanhamento hoje é por consulta. O ciclo de vida completo — quais eventos existem, quando cada um acontece, quais exigem ação sua e o padrão de varredura recomendado — está na página dedicada: **→ [4.1 Eventos e notificações](/guia/fgts-eventos)** ## O que acontece depois Com a operação em `Finished`, o ciclo de integração se encerra: a cada ano o saque-aniversário é debitado na origem e amortiza o contrato. O que resta do seu lado é a conciliação periódica e, quando o titular quiser antecipar de novo, conferir o limite anual de contratos antes de abrir nova operação. ## Antes desta etapa - [3. Operação](/guia/fgts-operacao) — é de lá que vem o `id` consultado aqui. ## Próxima etapa - [4.1 Eventos e notificações](/guia/fgts-eventos) — o significado de cada status e o que fazer em cada um. - [5. Erros e troubleshooting](/guia/fgts-erros) — quando uma consulta revelar reprovação, revisão ou erro. ## Downloads - Contexto para LLM deste módulo: [llms-fgts.txt](/downloads/llms-fgts.txt) - Collection Postman do módulo: [uy3-fgts.postman_collection.json](/downloads/uy3-fgts.postman_collection.json) - Documentação consolidada para LLM: [llms.txt](/downloads/llms.txt) --- ## /guia/fgts-eventos — 4.1 Eventos e notificações # FGTS — Eventos e notificações Dado pessoal ou sensível deve ser **mascarado** em outputs, logs e exemplos. Todos os valores desta página são fictícios. ## O que é O ciclo de vida completo de uma operação de FGTS, evento por evento: o que acontece, quando, o que aquilo significa e o que exige ação sua. Esta página existe para que você **não descubra os eventos por tentativa e erro**. Depois do `submitapproval`, a operação percorre a esteira sozinha — e cada parada dela é um estado que você precisa saber ler. > **O que é um "evento" aqui.** É uma **transição de status** da operação. Não há, hoje, um canal de notificação que empurre esses eventos para o seu sistema: você os observa consultando. A seção **Webhook de saída** no fim da página trata disso explicitamente. ## Quando usar - Ao desenhar a máquina de estados do seu lado, antes de escrever o acompanhamento. - Quando uma operação parou em um status e você não sabe se deve agir ou esperar. - Ao definir alertas operacionais: quais estados são normais e quais pedem intervenção. ## Pré-requisitos - `id` da operação — devolvido em [3. Operação](/guia/fgts-operacao). - Token válido — ver [Autenticação](/guia/autenticacao). ## Eventos do ciclo de vida ### Eventos do consentimento **Não existem.** No FGTS o consentimento é um **documento**, não um registro com ciclo de vida: ele não tem status, não emite evento e não é recusado por prazo. Essa é uma diferença deliberada em relação ao [Consignado privado](/guia/consignado-privado-eventos), onde a autorização de margem tem três estados (`Pending`, `Approved`, `Refused`) e bloqueia a consulta de margem quando não vale mais. A razão: lá existe um registro de autorização junto ao Crédito do Trabalhador; aqui, não. **Consequência prática:** a ausência ou a inadequação do termo **não aparece cedo**. Ela aparece na etapa de garantia, como `WarrantyRevision`, quando a operação já existe. O controle é do seu lado — ver a seção de duração em [2.1 Consentimento de consulta](/guia/fgts-cadastro-autorizacao). ### Eventos da operação de crédito Em ordem de percurso. A coluna **Ação sua** é a que importa: só quatro estados exigem que você faça algo. | Evento | Status | Quando acontece | O que representa | Ação sua | |---|---|---|---|---| | Operação criada | `Draft` | No `POST /v1/CreditNote`. | Rascunho. Ainda editável por `PUT`. | **Sim** — conferir documentos e chamar `submitapproval`. | | Enviada à esteira | `ComplianceApproval` ou `CreditApproval` | No `submitapproval`. | Em análise. A operação não aceita mais alteração. | Aguardar. | | Em análise de crédito | `CreditApproval` | Após compliance. | Mesa avaliando risco e política. | Aguardar. | | Em averbação | `Warranty` | Após aprovação de crédito. | A UY3 solicitou o registro da garantia ao órgão e aguarda o retorno. | Aguardar. O órgão tem janela de manutenção. | | Averbação em tratamento manual | `ManualWarranty` | Quando a averbação eletrônica não conclui. | A mesa está tratando o caso à mão. | Aguardar contato da UY3. **Não** recrie a operação em paralelo. | | Garantia devolvida | `WarrantyRevision` | Quando a averbação não confirma. | Saldo antecipável menor que o pedido, termo de consentimento ausente ou inadequado, ou adesão ao saque-aniversário não confirmada. | **Sim** — corrigir e chamar `POST /v1/CreditNote/{id}/doneWarrantyRevision`, ou cancelar e recriar com valor compatível. | | Instrumento em aprovação | `InstrumentApproval` | Após a garantia confirmada. | Geração e conferência do instrumento de crédito. | Aguardar. | | Coleta de assinaturas aberta | `Signatures` | Após aprovação do instrumento. | As URLs de assinatura passam a existir. | **Sim** — obter `GET /v1/CreditNote/{id}/SignUrl` e entregar ao titular. | | Assinaturas em validação | `SignaturesValidation` ou `PartnerSignaturesValidation` | Após a coleta. | Conferência das assinaturas colhidas. | Aguardar. | | Aguardando liquidação | `WaitLiquidation` | Após as assinaturas validadas. | Na fila de pagamento. | Aguardar. | | Em liquidação | `Liquidation` ou `ManualLiquidation` | No processamento do pagamento. | A transferência está sendo feita. | Aguardar. | | Pagamento devolvido | `PaymentRevision` | Quando a transferência falha. | Conta inválida ou titularidade divergente do CPF do titular. | **Sim** — corrigir a conta em [2.2 Conta de liquidação](/guia/fgts-cadastro-conta). | | Operação encerrada | `Finished` | Após a liquidação. | Contrato ativo; os saques-aniversário passam a amortizar. | Nada. Conciliação periódica. | | Devolvida para revisão | `Revision` | A qualquer momento, por decisão da mesa. | Algum atributo precisa de correção. | **Sim** — corrigir por `PUT /v1/CreditNote/{id}` e reenviar. | | Reprovada | `Disapproved` | Em qualquer etapa de análise, ou por limite anual de contratos excedido. | A operação não segue. | Ler o motivo — ver [5. Erros e troubleshooting](/guia/fgts-erros). | | Cancelada | `Canceled` | Após `POST /v1/CreditNote/{id}/cancel`. | Cancelamento concluído, incluindo o desfazimento do registro no órgão. | Só recontratar para o mesmo titular **depois** deste estado. | | Falha técnica | `Error` | Falha no processamento. | Erro interno, não decisão de negócio. | Acionar a UY3 com o `id` da operação. | ### Como ler o evento Não há corpo de evento a receber: o "payload do evento" é a própria operação, lida por `GET /v1/CreditNote/{id}`. Os campos relevantes para o acompanhamento: | Campo | Tipo | Para que serve no acompanhamento | |---|---|---| | `id` | string (uuid) | A chave da operação no seu lado. | | `creditNoteNo` | string | O número que a mesa e o suporte usam. Guarde junto do `id`. | | `status` | enum | O evento atual. É o campo que dispara a sua máquina de estados. | | `amortization` | objeto | Confirma valor, taxa, prazo e mês do saque efetivamente contratados. | | `uploads` | lista | Confirma se o termo de consentimento está no dossiê — a conferência que evita `WarrantyRevision`. | | `warranty` | lista | Volta **vazia** neste produto. É o esperado. | ## Como processar O padrão recomendado, e as armadilhas de cada parte. É o mesmo do [Consignado privado](/guia/consignado-privado-eventos) — o que muda são os estados a observar, não a mecânica. 1. **Guarde `id`, `creditNoteNo` e o último `status` conhecido** de cada operação, no seu banco. Sem o último status conhecido não existe "mudou de estado", só "está neste estado". 2. **Varra por status e por janela de data.** `GET /v1/CreditNote` com `status` e `initialDate`/`finalDate`, com paginação. Varra os estados em que você tem operações abertas, não todos. 3. **Compare com o último status conhecido.** Só reaja quando houver diferença. Reagir a cada leitura gera ação repetida — por exemplo, reentregar a URL de assinatura ao titular todo dia. 4. **Trate o seu handler como idempotente.** A consulta devolve estado, não evento: ler duas vezes o mesmo `Signatures` é o comportamento normal, não uma duplicidade da API. A proteção contra ação repetida é do seu lado. 5. **Não confie na ordem das leituras para reconstruir o caminho.** Entre duas varreduras a operação pode ter passado por vários estados. Se você precisa do histórico, guarde cada transição que observar — a API devolve o estado atual, não a trilha. 6. **Reaja apenas aos quatro estados que exigem ação:** `Draft`, `WarrantyRevision`, `Signatures`, `PaymentRevision`. Some `Revision` e `Disapproved` se o seu processo trata devolução e reprovação. Todo o resto é espera. 7. **Defina alerta operacional por tempo em estado**, não por estado. Neste produto o `Warranty` merece tolerância maior que no consignado: a janela de manutenção do órgão pode manter a operação parada legitimamente por mais tempo. Calibre o alerta com a UY3. Intervalo de varredura: comece em 15 a 30 minutos para operações abertas e ajuste pelo seu volume. Varredura de minuto em minuto sobre carteira inteira consome limite de chamadas sem ganho — os estados que dependem de terceiros (órgão, provedor de assinatura) não mudam nessa velocidade. ## Webhook de saída > **Não disponível hoje.** O contrato da API **não expõe** webhook de saída para o FGTS. Não existe endpoint para você registrar uma URL de callback, e nenhum evento desta página é entregue ativamente ao seu sistema. As rotas de webhook que existem no contrato de Crédito (`/v1/WebhookAutovist`, `/v1/WebhookWarehouse`) são o **contrário** do que se procura aqui: são endpoints da UY3 que **recebem** callbacks de prestadores externos, em fluxos de outros produtos. Não são endereçadas ao parceiro e não notificam nada sobre FGTS. Portanto: **o acompanhamento por consulta descrito acima não é uma alternativa ao webhook — é o mecanismo.** Implemente a varredura. ### Estrutura prevista Quando o recurso existir, a intenção é entregar os mesmos eventos desta página, com um envelope estável. O desenho previsto — **sujeito a mudança até a publicação, não implemente contra ele**: - Registro da URL de callback por ambiente do parceiro, e não por operação. - Envelope com identificador do evento, tipo do evento, momento em UTC, e o identificador da operação — sem dado pessoal no corpo. - O corpo da notificação **não substitui a consulta**: ele diz "a operação X mudou", e você busca o estado por `GET /v1/CreditNote/{id}`. Isso mantém uma fonte de verdade só. - Reenvio em caso de falha de entrega, com o mesmo identificador de evento — o que torna a deduplicação pelo identificador obrigatória do seu lado. Duas consequências para quem está desenhando a integração agora: - **Construa a varredura de qualquer forma.** Ela continua necessária como rede de segurança mesmo depois do webhook, para o caso de entrega perdida. - **Guarde o identificador do evento quando ele existir.** Se o seu handler já é idempotente por operação e estado, a migração para webhook é de transporte, não de lógica. Para acompanhar a disponibilidade, fale com a equipe de tecnologia da UY3. ## O que acontece depois Com a máquina de estados montada e a varredura rodando, o acompanhamento deixa de ser manual: o seu sistema sabe quando pedir assinatura, quando corrigir conta e quando avisar o titular de que o dinheiro saiu. ## Antes desta etapa - [4. Consultas e acompanhamento](/guia/fgts-consultas) — as rotas usadas na varredura. - [3. Operação](/guia/fgts-operacao) — as ações que cada evento pode pedir. ## Próxima etapa - [5. Erros e troubleshooting](/guia/fgts-erros) — o que fazer quando o evento é `Disapproved`, `Revision` ou `Error`. - [Consignado privado — Eventos e notificações](/guia/consignado-privado-eventos) — o mesmo ciclo no outro módulo, com as diferenças marcadas. ## Downloads - Contexto para LLM deste módulo: [llms-fgts.txt](/downloads/llms-fgts.txt) - Collection Postman do módulo: [uy3-fgts.postman_collection.json](/downloads/uy3-fgts.postman_collection.json) - Documentação consolidada para LLM: [llms.txt](/downloads/llms.txt) --- ## /guia/fgts-erros — 5. Erros e troubleshooting # FGTS — Erros e troubleshooting Dado pessoal ou sensível deve ser **mascarado** em outputs, logs e exemplos. Todos os valores desta página são fictícios. ## O que é Os erros que aparecem de fato na integração do FGTS, agrupados pela etapa em que aparecem, com causa e ação corretiva. Cada linha responde: por que aconteceu e o que fazer agora. ## Quando usar - Quando uma chamada devolve `400`, `403` ou `409` e a mensagem não é autoexplicativa. - Quando a operação entra em `Disapproved`, `Revision`, `WarrantyRevision` ou `PaymentRevision`. - Antes de abrir chamado: a maior parte dos casos abaixo se resolve sem a UY3. ## Erros por etapa ### Autenticação | Sintoma | Causa provável | Ação corretiva | |---|---|---| | `401` em qualquer rota | Token expirado ou header ausente. | Emita um token novo e reenvie. Ver [Autenticação](/guia/autenticacao). | | `403` em todas as rotas de operação | Ambiente do parceiro sem habilitação para o produto FGTS. | Acione a UY3: a habilitação é por ambiente, não por chamada. | ### Consentimento de consulta | Sintoma | Causa provável | Ação corretiva | |---|---|---| | Documento obrigatório ausente na etapa de garantia | O termo não foi anexado, ou foi anexado com `fileType` diferente de `Authorization`. | Reanexe com `fileType: "Authorization"`. Ver [2.1 Consentimento de consulta](/guia/fgts-cadastro-autorizacao). | | `409` ao anexar documento à operação | Status da operação não aceita alteração de documentos. | Anexe em `Draft`, ou aguarde a devolução para revisão. | | Consentimento recusado na conferência | Termo sem CPF do titular, sem autorização de registro da garantia, ou sem data de assinatura. | Colete novo termo com os quatro itens exigidos e reanexe. | | Termo desapareceu do cadastro | `PUT /v1/NaturalPerson/{id}` enviado sem a coleção `uploads`. | Reanexe. No futuro, envie `null` para preservar coleções. | | Nenhum aviso de que o termo está velho | Correto: o FGTS não tem status nem prazo de autorização. O controle de validade é seu. | Guarde a data de assinatura e defina revalidação com o Compliance — ver [2.1 Consentimento de consulta](/guia/fgts-cadastro-autorizacao). | ### Simulação | Sintoma | Causa provável | Ação corretiva | |---|---|---| | `400` de modelo de cálculo não suportado | `amortizationType` diferente de `fgts`. | O FGTS aceita apenas `fgts`. Corrija o discriminador. | | `400` com campos desconhecidos no cálculo | Envio de `paymentDay`, `numberOfPayments`, `firstPaymentDate`, `calculationType`, `paymentPeriodicity`, `periodicity` ou `daysInYear`. | Remova. O modelo do FGTS tem cinco campos essenciais — ver [3. Operação](/guia/fgts-operacao). | | `400` de taxa | `apr` fora da faixa do produto contratado, ou igual a zero. | Use uma taxa dentro da faixa. `apr` é **mensal**, em porcentagem. | | `400` de prazo | `termInMonths` fora da faixa de prazo do produto. | Ajuste o prazo dentro da faixa. | | Parcelas em mês errado | `paymentMonth` ausente ou diferente do mês do saque-aniversário do titular. | Informe o mês correto do saque-aniversário. | | Valor simulado cem vezes menor ou maior | `requestedAmount` enviado em reais e não em **centavos**. | `150000` são R$ 1.500,00. Ver [Convenções de dados](/guia/convencoes-de-dados). | | Procurando a simulação de ofertas | Este produto não tem esse caminho: não há margem consignável a comparar. | Use `POST /v1/Amortization`. A justificativa está em [1. Visão geral](/guia/fgts-visao-geral). | | Simulação não valida o saldo do titular | Correto: o saldo antecipável não é exposto como consulta. A simulação calcula o plano, não confere o lastro. | Dimensione pelo valor combinado com o titular. A conferência acontece na averbação. | ### Criação da operação | Sintoma | Causa provável | Ação corretiva | |---|---|---| | Tomador não vinculado ao usuário ou correspondente selecionado | O `personId` existe, mas pertence a outro correspondente ou grupo. | Use um titular do seu escopo, ou solicite a atribuição do cadastro ao seu correspondente. | | `400` de modelo divergente do produto | O `productId` informado não é de FGTS. | Confirme o `productId` de FGTS com a UY3. | | `400` na conta de liquidação | `liquidationType` é `EletronicTransfer` sem `bankAccountId`. | Informe a conta cadastrada. | | Garantia criada sem correspondência | Objeto `warranty` enviado no FGTS. | Não envie garantia por tipo neste produto: o lastro é o saldo do titular e a averbação é etapa da esteira. | | Operação criada mas sem documento | `uploads` omitido na criação. | Anexe por `PUT /v1/CreditNote/{id}/upload` **antes** do `submitapproval`. Sem isso a devolução vem na garantia, muito depois. | | Documento assinado enviado em rascunho não foi aproveitado | A coleção `uploads` foi enviada vazia, ou com `fileType` que não identifica o documento assinado. | Envie o item com `fileType: "SignedContract"`. Coleção vazia não reserva lugar — ver [3. Operação](/guia/fgts-operacao). | | Documento duplicado no dossiê | O mesmo arquivo foi reenviado em mais de uma etapa. | Envie uma vez. O documento permanece vinculado à operação. | ### Envio para aprovação e averbação | Sintoma | Causa provável | Ação corretiva | |---|---|---| | Envio bloqueado por limite de contratos | O titular excedeu o limite anual: cada saque-aniversário só pode ser antecipado uma vez. | Não há operação possível neste ciclo. Confira as operações do titular com `GET /v1/CreditNote?personId=...`. | | `409` ao reenviar `submitapproval` | A operação já saiu do rascunho: depois do envio ela não aceita alteração até o fim da análise. | Consulte o status antes de repetir. Ver [4.1 Eventos e notificações](/guia/fgts-eventos). | | Operação parada em `Warranty` por muito tempo | Averbação aguardando retorno do órgão, possivelmente em janela de manutenção. | Aguardar. Este produto tolera espera maior que o consignado. Se passar da janela combinada, acione a UY3 com o `id`. | | Operação em `WarrantyRevision` com saldo insuficiente | O saldo antecipável do titular é menor que o `requestedAmount` contratado. | Cancele e recrie com valor compatível, ou aguarde a orientação da mesa. | | Reprovação sem adesão ao saque-aniversário | O titular não aderiu à modalidade, ou migrou para saque-rescisão. | Sem adesão não há parcela a antecipar. Confirme com o titular antes de recontratar. | | Operação em `ManualWarranty` | Averbação em tratamento manual da mesa. | Aguardar contato da UY3; não recrie a operação em paralelo. | ### Assinatura e liquidação | Sintoma | Causa provável | Ação corretiva | |---|---|---| | Sem URL de assinatura | A operação ainda não chegou a `Signatures`. | Aguarde a aprovação do instrumento e reconsulte `SignUrl`. | | Operação em `PaymentRevision` | Conta de liquidação inválida ou titularidade divergente do CPF do titular. | Corrija a conta em [2.2 Conta de liquidação](/guia/fgts-cadastro-conta). Chave Pix de terceiro é recusada. | | Sem comprovante de transferência | A liquidação ainda não ocorreu. | Aguarde `Liquidation`/`Finished` e reconsulte. | ### Cancelamento | Sintoma | Causa provável | Ação corretiva | |---|---|---| | Nova operação para o mesmo titular reprovada logo após um cancelamento | O desfazimento do registro no órgão ainda está em processamento. | Aguarde a operação anterior chegar a `Canceled` antes de recontratar. | | `400` ao excluir a operação | Exclusão só é permitida em `Draft`, `Revision`, `Disapproved` e `Canceled`. | Cancele primeiro e depois exclua, se necessário. | ## Como reagir a cada erro Ordem de diagnóstico, do mais provável ao menos: 1. **Releia a mensagem da resposta.** As validações de negócio do FGTS (modelo de cálculo, faixa de taxa, faixa de prazo, limite de contratos) vêm com texto explícito. 2. **Confira o status atual** com `GET /v1/CreditNote/{id}`. Boa parte dos `400` e `409` é ação certa no status errado — ver [4.1 Eventos e notificações](/guia/fgts-eventos). 3. **Confira o objeto de cálculo.** Campo de outro modelo no cálculo do FGTS é a causa mais comum de `400` neste produto: o modelo tem cinco campos essenciais, e só eles. 4. **Confira a unidade e o formato.** `requestedAmount` é inteiro em **centavos**; `apr` é porcentagem mensal; o prazo é em meses. Ver [Convenções de dados](/guia/convencoes-de-dados). 5. **Confira se o termo está no dossiê.** `GET /v1/NaturalPerson/{id}` ou `GET /v1/CreditNote/{id}` mostram os uploads. É a conferência que evita `WarrantyRevision` — e ela é sua, porque neste produto a API não avisa antes. 6. **Confira os identificadores** contra os cadastros: `personId`, `bankAccountId`, `productId`. 7. **Só então acione a UY3**, com o `id` da operação, o horário da chamada e o corpo enviado — **com os dados pessoais mascarados**. > Orientação técnica. A classificação de dado pessoal, a base legal do tratamento e a guarda do termo de consentimento são competência do Compliance/Jurídico da UY3 (LGPD, Lei 13.709/2018, art. 7º e art. 37). Esta página não substitui parecer. ## O que acontece depois Erro corrigido no rascunho: reenvie para aprovação e a operação retoma o fluxo. Erro corrigido depois de uma devolução para revisão: encerre a revisão pela rota indicada e a operação volta para a etapa seguinte da esteira, sem recomeçar. ## Antes desta etapa - [4.1 Eventos e notificações](/guia/fgts-eventos) — é o status que revela em qual erro você caiu. - [3. Operação](/guia/fgts-operacao) — as tabelas de preenchimento que a maioria dos `400` aponta. ## Próxima etapa - [1. Visão geral](/guia/fgts-visao-geral) — voltar ao começo do fluxo com um novo titular. - [Consignado privado](/guia/consignado-privado-visao-geral) — o outro módulo publicado neste padrão. ## Downloads - Contexto para LLM deste módulo: [llms-fgts.txt](/downloads/llms-fgts.txt) - Collection Postman do módulo: [uy3-fgts.postman_collection.json](/downloads/uy3-fgts.postman_collection.json) - Documentação consolidada para LLM: [llms.txt](/downloads/llms.txt) ---