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.

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 já existem.

A sequência é mais curta que a do Consignado privado 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

Endpoints do fluxo principal

Passo 1 — Simular a antecipação

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.

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 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.

Passo 2 — Criar a operação de crédito

POST /v1/CreditNote

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

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

POST /v1/CreditNote/{id}/submitapproval

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

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.

Quando a mesa devolve a garantia para revisão (WarrantyRevision), o encerramento da revisão é feito por:

POST /v1/CreditNote/{id}/doneWarrantyRevision

Passo 7 — Cancelar, excluir ou restaurar

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.

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

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.

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.

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:

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.

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

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:

{
  "fileType": "SignedContract",
  "fileName": "instrumento-assinado.pdf",
  "displayName": "Instrumento assinado",
  "documentDate": "2026-08-25T00:00:00Z"
}

Exemplo de response

{
  "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

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.

Antes desta etapa

• 2.3 Cadastro do titular — o personId e o bankAccountId consumidos aqui.
• 2. Pré-requisitos e cadastros — índice dos três cadastros e a ordem entre eles.

Próxima etapa

• 4. Consultas e acompanhamento — status, parcelas e comprovante de transferência.
• 4.1 Eventos e notificações — o ciclo de vida completo, evento por evento.
• 5. Erros e troubleshooting — quando alguma etapa acima falhar.

Downloads

• Contexto para LLM deste módulo: llms-fgts.txt
• Collection Postman do módulo: uy3-fgts.postman_collection.json
• Collection completa (Consignado privado + FGTS): uy3-api-completa.postman_collection.json
• Documentação consolidada para LLM: llms.txt