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.

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

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.
• Termo assinado pelo titular, digitalizado.
• Para a rota dedicada: o personId, obtido em 2.3 Cadastro do titular. Não é necessário se o termo for enviado na coleção uploads do próprio cadastro.

Os dois caminhos de envio

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

Como preencher

Documento do consentimento

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:

Exemplo de request

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

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:

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

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

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.

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. 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 — por que este é o primeiro passo e como ele difere do consignado.

Próxima etapa

• 2.2 Conta de liquidação — a conta de destino do valor liberado.
• O termo é conferido na etapa de garantia, em 3. Operação.

Downloads

• Contexto para LLM deste módulo: llms-fgts.txt
• Collection Postman do módulo: uy3-fgts.postman_collection.json
• Documentação consolidada para LLM: llms.txt