{
  "info": {
    "_postman_id": "a1c00000-0000-4000-8000-000000000002",
    "name": "UY3 — FGTS",
    "description": "Collection do modulo FGTS (antecipacao do saque-aniversario) da API de Credito da UY3.\n\nPastas na ordem do fluxo: 1. Cadastros -> 2. Operacao -> 3. Consultas. Dentro de cada pasta, as requisicoes estao na ORDEM em que devem ser chamadas.\n\nORDEM DOS CADASTROS: 2.1 consentimento de consulta (termo assinado) -> 2.2 conta de liquidacao -> 2.3 cadastro do titular. O termo e a conta sao enviados DENTRO do cadastro do titular — uma chamada resolve os tres.\n\nDIFERENCA EM RELACAO AO CONSIGNADO PRIVADO: aqui o consentimento e um DOCUMENTO (fileType=Authorization), nao um registro com endpoint proprio e status. E ha um unico caminho de simulacao (por amortizacao), porque nao existe margem consignavel a comparar.\n\nVariaveis da collection: {{baseUrl}} e {{token}}. A autorizacao Bearer esta no nivel da collection; as requisicoes herdam.\n\nUNIDADES: requestedAmount e INTEIRO EM CENTAVOS. apr e taxa MENSAL em porcentagem. termInMonths em meses.\n\nDATAS: data civil = AAAA-MM-DD. Data e hora = AAAA-MM-DDTHH:MM:SSZ (UTC).\n\nTodos os dados de exemplo sao ficticios e mascarados. Nunca substitua por CPF, token ou chave reais em ambiente compartilhado.\n\nDocumentacao: /guia/fgts-visao-geral",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "auth": {
    "type": "bearer",
    "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ]
  },
  "variable": [
    { "key": "baseUrl", "value": "", "type": "string" },
    { "key": "token", "value": "", "type": "string" },
    { "key": "personId", "value": "11111111-1111-1111-1111-111111111111", "type": "string" },
    { "key": "bankAccountId", "value": "22222222-2222-2222-2222-222222222222", "type": "string" },
    { "key": "productId", "value": "33333333-3333-3333-3333-333333333333", "type": "string" },
    { "key": "creditNoteId", "value": "55555555-5555-5555-5555-555555555555", "type": "string" }
  ],
  "item": [
    {
      "name": "1. Cadastros",
      "description": "Ordem: 2.1 consentimento -> 2.2 conta de liquidacao -> 2.3 cadastro do titular. O termo e a conta viajam DENTRO do cadastro do titular — e o caminho recomendado, uma chamada em vez de tres.",
      "item": [
        {
          "name": "2.3 Criar titular com conta e consentimento",
          "request": {
            "method": "POST",
            "header": [
              { "key": "Content-Type", "value": "application/json" },
              { "key": "Accept", "value": "application/json" }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"registrationNumber\": \"00000000000\",\n  \"name\": \"MARIA D*** S*** LIMA\",\n  \"email\": \"titular@exemplo.com.br\",\n  \"phone\": \"11900000000\",\n  \"birthDate\": \"1988-04-12\",\n  \"mothersName\": \"ANA F*** D*** S***\",\n  \"pep\": false,\n  \"nationality\": \"Brasileira\",\n  \"documentType\": \"IdentityCard\",\n  \"documentNumber\": \"000000000\",\n  \"documentIssuer\": \"SSP/SP\",\n  \"address\": {\n    \"zipCode\": \"00000-000\",\n    \"street\": \"Rua Exemplo\",\n    \"number\": \"100\",\n    \"district\": \"Centro\",\n    \"city\": \"Sao Paulo\",\n    \"state\": \"SP\",\n    \"country\": \"Brasil\"\n  },\n  \"bankAccounts\": [\n    {\n      \"operationTypeValue\": \"Pix\",\n      \"type\": \"NaturalCheckingAccount\",\n      \"pixKeyTypeValue\": \"NaturalRegistrationNumber\",\n      \"keyPix\": \"00000000000\",\n      \"bankCode\": 341,\n      \"jointAccount\": false\n    }\n  ],\n  \"uploads\": [\n    {\n      \"fileType\": \"Authorization\",\n      \"fileName\": \"consentimento-fgts-000123.pdf\",\n      \"displayName\": \"Consentimento de consulta FGTS\",\n      \"documentDate\": \"2026-08-25T00:00:00Z\"\n    }\n  ]\n}",
              "options": { "raw": { "language": "json" } }
            },
            "url": {
              "raw": "{{baseUrl}}/v1/NaturalPerson?returnValue=true",
              "host": [ "{{baseUrl}}" ],
              "path": [ "v1", "NaturalPerson" ],
              "query": [ { "key": "returnValue", "value": "true" } ]
            },
            "description": "CAMINHO RECOMENDADO: resolve os tres cadastros em uma chamada — titular, conta (bankAccounts) e termo de consentimento (uploads com fileType=Authorization).\n\nDois identificadores saem daqui: id da pessoa = personId; id do item de bankAccounts = bankAccountId.\n\nNAO preencha campos de vinculo empregaticio (natureOfOccupation, workplace, employeeNumber, admissionDate): nao existe folha a consignar neste produto. Se voce precisa deles, o produto pretendido e Consignado privado.\n\nO termo de consentimento e conferido na ETAPA DE GARANTIA, depois de a operacao existir. Faltar o documento nao devolve 400 aqui — devolve WarrantyRevision mais tarde, que e bem mais caro de corrigir.\n\nDoc: /guia/fgts-cadastro-pessoa"
          },
          "response": []
        },
        {
          "name": "2.3 Buscar titular por CPF",
          "request": {
            "method": "GET",
            "header": [ { "key": "Accept", "value": "application/json" } ],
            "url": {
              "raw": "{{baseUrl}}/v1/NaturalPerson?registrationNumber=00000000000&page=1&size=10",
              "host": [ "{{baseUrl}}" ],
              "path": [ "v1", "NaturalPerson" ],
              "query": [
                { "key": "registrationNumber", "value": "00000000000" },
                { "key": "page", "value": "1" },
                { "key": "size", "value": "10" }
              ]
            },
            "description": "Procura o titular antes de criar. Se o CPF ja existir visivel ao seu usuario, a criacao ATUALIZA o cadastro e devolve o id existente — nao cria duplicata."
          },
          "response": []
        },
        {
          "name": "2.3 Consultar titular por id",
          "request": {
            "method": "GET",
            "header": [ { "key": "Accept", "value": "application/json" } ],
            "url": {
              "raw": "{{baseUrl}}/v1/NaturalPerson/{{personId}}",
              "host": [ "{{baseUrl}}" ],
              "path": [ "v1", "NaturalPerson", "{{personId}}" ]
            },
            "description": "Cadastro completo do titular, com contas e documentos anexados. E AQUI que voce confere se o termo de consentimento esta no dossie — como o FGTS nao tem registro de autorizacao com status, essa conferencia e sua."
          },
          "response": []
        },
        {
          "name": "2.1 Anexar consentimento a titular existente",
          "request": {
            "method": "POST",
            "header": [
              { "key": "Content-Type", "value": "application/json" },
              { "key": "Accept", "value": "application/json" }
            ],
            "body": {
              "mode": "raw",
              "raw": "[\n  {\n    \"fileType\": \"Authorization\",\n    \"fileName\": \"consentimento-fgts-000123.pdf\",\n    \"displayName\": \"Consentimento de consulta FGTS\",\n    \"documentDate\": \"2026-08-25T00:00:00Z\"\n  }\n]",
              "options": { "raw": { "language": "json" } }
            },
            "url": {
              "raw": "{{baseUrl}}/v1/NaturalPerson/{{personId}}/Upload",
              "host": [ "{{baseUrl}}" ],
              "path": [ "v1", "NaturalPerson", "{{personId}}", "Upload" ]
            },
            "description": "Use quando o titular JA EXISTE, ou quando o termo foi renovado.\n\nfileType precisa ser Authorization: com Others o documento nao e reconhecido como consentimento na esteira.\n\nNao existe prazo de validade nem status neste produto — o termo velho continua no dossie e nenhuma chamada e recusada por causa dele. O controle de revalidacao e seu, com o Compliance.\n\nDoc: /guia/fgts-cadastro-autorizacao"
          },
          "response": []
        },
        {
          "name": "2.2 Cadastrar conta depois (caminho alternativo)",
          "request": {
            "method": "POST",
            "header": [
              { "key": "Content-Type", "value": "application/json" },
              { "key": "Accept", "value": "application/json" }
            ],
            "body": {
              "mode": "raw",
              "raw": "[\n  {\n    \"operationTypeValue\": \"Pix\",\n    \"type\": \"NaturalCheckingAccount\",\n    \"pixKeyTypeValue\": \"NaturalRegistrationNumber\",\n    \"keyPix\": \"00000000000\",\n    \"bankCode\": 341,\n    \"jointAccount\": false\n  }\n]",
              "options": { "raw": { "language": "json" } }
            },
            "url": {
              "raw": "{{baseUrl}}/v1/NaturalPerson/{{personId}}/BankAccount",
              "host": [ "{{baseUrl}}" ],
              "path": [ "v1", "NaturalPerson", "{{personId}}", "BankAccount" ]
            },
            "description": "Use quando o titular JA EXISTE — troca ou acrescimo de conta. Para fluxo novo, prefira enviar a conta dentro do cadastro do titular.\n\nA titularidade e conferida na liquidacao: a chave Pix precisa ser do CPF do titular. Chave de terceiro devolve a operacao para PaymentRevision depois de ela ja estar assinada e averbada.\n\nDoc: /guia/fgts-cadastro-conta"
          },
          "response": []
        }
      ]
    },
    {
      "name": "2. Operacao",
      "description": "Fluxo principal: simulacao -> operacao -> documentos -> aprovacao -> assinatura. Um unico caminho de simulacao neste produto.",
      "item": [
        {
          "name": "Passo 1 — Simular antecipacao",
          "request": {
            "method": "POST",
            "header": [
              { "key": "Content-Type", "value": "application/json" },
              { "key": "Accept", "value": "application/json" }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"amortizationType\": \"fgts\",\n  \"requestedAmount\": 150000,\n  \"termInMonths\": 24,\n  \"apr\": 2.09,\n  \"startDate\": \"2026-08-25T00:00:00Z\",\n  \"paymentMonth\": \"August\"\n}",
              "options": { "raw": { "language": "json" } }
            },
            "url": {
              "raw": "{{baseUrl}}/v1/Amortization",
              "host": [ "{{baseUrl}}" ],
              "path": [ "v1", "Amortization" ]
            },
            "description": "UNICO caminho de simulacao deste produto. Devolve o plano de pagamento completo.\n\nNao existe simulacao de ofertas no FGTS: ofertas servem para comparar produtos que caibam numa margem consignavel, e aqui nao ha margem — o lastro e um saldo que ja existe.\n\nCinco campos essenciais: amortizationType=fgts, requestedAmount (CENTAVOS), termInMonths, apr (MENSAL, em %), startDate. paymentMonth ancora o cronograma no mes do saque-aniversario.\n\nO saldo antecipavel do titular NAO e validado aqui — a conferencia acontece na averbacao. Dimensione pelo valor combinado com o titular.\n\nDoc: /guia/fgts-operacao"
          },
          "response": []
        },
        {
          "name": "Passo 1 — Simular varios prazos (lote)",
          "request": {
            "method": "POST",
            "header": [
              { "key": "Content-Type", "value": "application/json" },
              { "key": "Accept", "value": "application/json" }
            ],
            "body": {
              "mode": "raw",
              "raw": "[\n  {\n    \"amortizationType\": \"fgts\",\n    \"requestedAmount\": 150000,\n    \"termInMonths\": 12,\n    \"apr\": 2.09,\n    \"startDate\": \"2026-08-25T00:00:00Z\",\n    \"paymentMonth\": \"August\"\n  },\n  {\n    \"amortizationType\": \"fgts\",\n    \"requestedAmount\": 150000,\n    \"termInMonths\": 24,\n    \"apr\": 2.09,\n    \"startDate\": \"2026-08-25T00:00:00Z\",\n    \"paymentMonth\": \"August\"\n  }\n]",
              "options": { "raw": { "language": "json" } }
            },
            "url": {
              "raw": "{{baseUrl}}/v1/Amortization/Batch",
              "host": [ "{{baseUrl}}" ],
              "path": [ "v1", "Amortization", "Batch" ]
            },
            "description": "Simula varios prazos em uma chamada, para montar uma vitrine propria de opcoes para o titular."
          },
          "response": []
        },
        {
          "name": "Passo 1 — Consultar simulacao gerada",
          "request": {
            "method": "GET",
            "header": [ { "key": "Accept", "value": "application/json" } ],
            "url": {
              "raw": "{{baseUrl}}/v1/Amortization/77777777-7777-7777-7777-777777777777",
              "host": [ "{{baseUrl}}" ],
              "path": [ "v1", "Amortization", "77777777-7777-7777-7777-777777777777" ]
            },
            "description": "Recupera uma simulacao ja gerada, sem simular de novo."
          },
          "response": []
        },
        {
          "name": "Passo 2 — Criar operacao de credito",
          "request": {
            "method": "POST",
            "header": [
              { "key": "Content-Type", "value": "application/json" },
              { "key": "Accept", "value": "application/json" }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"productId\": \"{{productId}}\",\n  \"personId\": \"{{personId}}\",\n  \"liquidationType\": \"EletronicTransfer\",\n  \"bankAccountId\": \"{{bankAccountId}}\",\n  \"observations\": \"Antecipacao saque-aniversario\",\n  \"amortization\": {\n    \"amortizationType\": \"fgts\",\n    \"requestedAmount\": 150000,\n    \"termInMonths\": 24,\n    \"apr\": 2.09,\n    \"startDate\": \"2026-08-25T00:00:00Z\",\n    \"paymentMonth\": \"August\",\n    \"includePaymentFixedCosts\": false\n  },\n  \"uploads\": [\n    {\n      \"fileType\": \"Authorization\",\n      \"fileName\": \"consentimento-fgts-000123.pdf\",\n      \"displayName\": \"Consentimento de consulta FGTS\",\n      \"documentDate\": \"2026-08-25T00:00:00Z\"\n    }\n  ]\n}",
              "options": { "raw": { "language": "json" } }
            },
            "url": {
              "raw": "{{baseUrl}}/v1/CreditNote?returnValue=true",
              "host": [ "{{baseUrl}}" ],
              "path": [ "v1", "CreditNote" ],
              "query": [ { "key": "returnValue", "value": "true" } ]
            },
            "description": "Cria a operacao. Guarde o id devolvido em {{creditNoteId}}.\n\nNAO ENVIE a colecao warranty neste produto: o lastro e o saldo do titular e a averbacao e etapa dedicada da esteira. Nao existe tipo de garantia FGTS na lista de tipos de garantia. A colecao volta vazia no response — e o esperado.\n\nuploads e o que importa aqui: o termo de consentimento. Sem ele a operacao e devolvida na etapa de garantia.\n\nDOCUMENTO ASSINADO EM RASCUNHO: se voce ja tem o instrumento assinado, acrescente um item com fileType=SignedContract enquanto a operacao esta em Draft. Desde que a colecao nao esteja vazia, ele permanece vinculado e e aproveitado na etapa de assinatura. Nao envie uploads como [] esperando anexar depois.\n\nrequestedAmount = 150000 CENTAVOS (R$ 1.500,00)."
          },
          "response": []
        },
        {
          "name": "Passo 3 — Anexar documentos",
          "request": {
            "method": "PUT",
            "header": [
              { "key": "Content-Type", "value": "application/json" },
              { "key": "Accept", "value": "application/json" }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"uploads\": [\n    {\n      \"fileType\": \"Authorization\",\n      \"fileName\": \"consentimento-fgts-000123.pdf\",\n      \"displayName\": \"Consentimento de consulta FGTS\",\n      \"documentDate\": \"2026-08-25T00:00:00Z\"\n    },\n    {\n      \"fileType\": \"SignedContract\",\n      \"fileName\": \"instrumento-assinado.pdf\",\n      \"displayName\": \"Instrumento assinado\",\n      \"documentDate\": \"2026-08-25T00:00:00Z\"\n    }\n  ]\n}",
              "options": { "raw": { "language": "json" } }
            },
            "url": {
              "raw": "{{baseUrl}}/v1/CreditNote/{{creditNoteId}}/upload",
              "host": [ "{{baseUrl}}" ],
              "path": [ "v1", "CreditNote", "{{creditNoteId}}", "upload" ]
            },
            "description": "Documentos da operacao. Permitido nos status Rascunho, Revisao, Aprovacao de Instrumento e Coleta de Assinaturas.\n\nAnexe o termo ANTES do submitapproval: depois disso a devolucao vem na etapa de garantia. Nao reenvie o mesmo documento em cada etapa — gera duplicata no dossie."
          },
          "response": []
        },
        {
          "name": "Passo 4 — Enviar para aprovacao",
          "request": {
            "method": "POST",
            "header": [ { "key": "Accept", "value": "application/json" } ],
            "url": {
              "raw": "{{baseUrl}}/v1/CreditNote/{{creditNoteId}}/submitapproval",
              "host": [ "{{baseUrl}}" ],
              "path": [ "v1", "CreditNote", "{{creditNoteId}}", "submitapproval" ]
            },
            "description": "Inicia a esteira. Bloqueado quando o titular excede o limite anual de contratos — cada saque-aniversario so pode ser antecipado uma vez.\n\nDepois do envio a operacao nao aceita alteracao ate o fim da analise; reenviar devolve 409."
          },
          "response": []
        },
        {
          "name": "Passo 5 — URLs de assinatura",
          "request": {
            "method": "GET",
            "header": [ { "key": "Accept", "value": "application/json" } ],
            "url": {
              "raw": "{{baseUrl}}/v1/CreditNote/{{creditNoteId}}/SignUrl",
              "host": [ "{{baseUrl}}" ],
              "path": [ "v1", "CreditNote", "{{creditNoteId}}", "SignUrl" ]
            },
            "description": "URLs de coleta de assinatura, para entregar ao titular. Disponiveis a partir do status Signatures. Antes disso, a resposta vem vazia — nao e erro."
          },
          "response": []
        },
        {
          "name": "Passo 6 — Encerrar revisao de garantia",
          "request": {
            "method": "POST",
            "header": [ { "key": "Accept", "value": "application/json" } ],
            "url": {
              "raw": "{{baseUrl}}/v1/CreditNote/{{creditNoteId}}/doneWarrantyRevision",
              "host": [ "{{baseUrl}}" ],
              "path": [ "v1", "CreditNote", "{{creditNoteId}}", "doneWarrantyRevision" ]
            },
            "description": "Encerra a revisao de garantia depois de corrigir o que a mesa apontou. Em WarrantyRevision por saldo insuficiente, a correcao pode exigir cancelar e recriar com valor compativel."
          },
          "response": []
        },
        {
          "name": "Passo 7 — Cancelar operacao",
          "request": {
            "method": "POST",
            "header": [
              { "key": "Content-Type", "value": "application/json" },
              { "key": "Accept", "value": "application/json" }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"message\": \"Desistencia do titular\"\n}",
              "options": { "raw": { "language": "json" } }
            },
            "url": {
              "raw": "{{baseUrl}}/v1/CreditNote/{{creditNoteId}}/cancel",
              "host": [ "{{baseUrl}}" ],
              "path": [ "v1", "CreditNote", "{{creditNoteId}}", "cancel" ]
            },
            "description": "Acao unica, sem parametros de controle: o desfazimento do registro no orgao faz parte do processamento pela esteira.\n\nACOMPANHE ATE Canceled. So contrate de novo para o mesmo titular depois desse status — antes, o saque-aniversario pode ainda estar comprometido com a operacao anterior."
          },
          "response": []
        }
      ]
    },
    {
      "name": "3. Consultas",
      "description": "Acompanhamento por consulta. Nao ha webhook de saida nesta API — ver /guia/fgts-eventos.",
      "item": [
        {
          "name": "Consultar operacao por id",
          "request": {
            "method": "GET",
            "header": [ { "key": "Accept", "value": "application/json" } ],
            "url": {
              "raw": "{{baseUrl}}/v1/CreditNote/{{creditNoteId}}",
              "host": [ "{{baseUrl}}" ],
              "path": [ "v1", "CreditNote", "{{creditNoteId}}" ]
            },
            "description": "Operacao completa: status, calculo, documentos, assinaturas e cronograma. O campo status e o \"evento\" atual. A colecao warranty volta vazia — e o esperado neste produto.\n\nDoc: /guia/fgts-consultas e /guia/fgts-eventos"
          },
          "response": []
        },
        {
          "name": "Listar operacoes do titular",
          "request": {
            "method": "GET",
            "header": [ { "key": "Accept", "value": "application/json" } ],
            "url": {
              "raw": "{{baseUrl}}/v1/CreditNote?personId={{personId}}&page=1&size=50&orderBy=createDate desc",
              "host": [ "{{baseUrl}}" ],
              "path": [ "v1", "CreditNote" ],
              "query": [
                { "key": "personId", "value": "{{personId}}" },
                { "key": "page", "value": "1" },
                { "key": "size", "value": "50" },
                { "key": "orderBy", "value": "createDate desc" }
              ]
            },
            "description": "Todas as operacoes do titular. E a consulta que confere o LIMITE ANUAL DE CONTRATOS antes de abrir nova antecipacao."
          },
          "response": []
        },
        {
          "name": "Listar operacoes por status",
          "request": {
            "method": "GET",
            "header": [ { "key": "Accept", "value": "application/json" } ],
            "url": {
              "raw": "{{baseUrl}}/v1/CreditNote?status=Warranty&page=1&size=50",
              "host": [ "{{baseUrl}}" ],
              "path": [ "v1", "CreditNote" ],
              "query": [
                { "key": "status", "value": "Warranty" },
                { "key": "page", "value": "1" },
                { "key": "size", "value": "50" }
              ]
            },
            "description": "Varredura da fila de uma etapa. Estados que exigem acao sua: Draft, WarrantyRevision, Signatures, PaymentRevision (mais Revision e Disapproved). Todo o resto e espera.\n\nNeste produto, Warranty merece tolerancia maior que no consignado: a janela de manutencao do orgao pode manter a operacao parada legitimamente por mais tempo."
          },
          "response": []
        },
        {
          "name": "Comprovante de transferencia",
          "request": {
            "method": "GET",
            "header": [ { "key": "Accept", "value": "application/json" } ],
            "url": {
              "raw": "{{baseUrl}}/v1/CreditNote/{{creditNoteId}}/transferReceipt",
              "host": [ "{{baseUrl}}" ],
              "path": [ "v1", "CreditNote", "{{creditNoteId}}", "transferReceipt" ]
            },
            "description": "Comprovante da transferencia (Pix/TED) feita ao titular. Disponivel a partir da liquidacao."
          },
          "response": []
        },
        {
          "name": "Calendario de quitacao",
          "request": {
            "method": "POST",
            "header": [ { "key": "Accept", "value": "application/json" } ],
            "url": {
              "raw": "{{baseUrl}}/v1/CreditNote/{{creditNoteId}}/DuePaymentSchedule",
              "host": [ "{{baseUrl}}" ],
              "path": [ "v1", "CreditNote", "{{creditNoteId}}", "DuePaymentSchedule" ]
            },
            "description": "Calendario de quitacao: o que o titular deve para liquidar antecipadamente, antes do proximo saque-aniversario."
          },
          "response": []
        },
        {
          "name": "Exportar carteira em Excel",
          "request": {
            "method": "GET",
            "header": [ { "key": "Accept", "value": "application/json" } ],
            "url": {
              "raw": "{{baseUrl}}/v1/CreditNote/Export/excel?productId={{productId}}",
              "host": [ "{{baseUrl}}" ],
              "path": [ "v1", "CreditNote", "Export", "excel" ],
              "query": [ { "key": "productId", "value": "{{productId}}" } ]
            },
            "description": "Exportacao da carteira filtrada, para conciliacao periodica. Nao use para acompanhar operacao individual."
          },
          "response": []
        }
      ]
    }
  ]
}