Consignado privado — Autorização de margem

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 é

A autorização de margem é o registro do consentimento do trabalhador para que a UY3 consulte sua margem consignável no Crédito do Trabalhador (CTPS Digital). É um cadastro, não uma consulta: ele guarda quem autorizou, por qual canal, quando e com quais evidências.

Sem uma autorização aprovada para o CPF, a consulta de margem é recusada — e sem margem não há simulação, proposta nem operação.

Este é o primeiro passo do módulo, e ele não exige tomador cadastrado. A autorização se identifica por CPF e telefone; o corpo não tem personId. Isso é deliberado: o consentimento é a primeira pergunta do funil, feita antes de você saber se existe margem. O raciocínio completo está em 2. Pré-requisitos e cadastros.

Quando usar

• Antes de qualquer outra coisa, para cada trabalhador que entra no seu funil.
• De novo, quando a autorização anterior estiver Refused ou já não for aceita pela consulta de margem.

Antes de criar, consulte: uma autorização Approved ainda válida para aquele CPF deve ser reaproveitada, não duplicada.

Pré-requisitos

• Token válido — ver Autenticação.
• CPF e telefone do trabalhador, e o aceite dele coletado no seu canal.
• productId do produto contratado, fornecido pela UY3 (opcional no corpo, recomendado).
• Nenhum cadastro prévio. Não é necessário personId, e não existe campo para ele.

Endpoints do cadastro

Parâmetros de query da listagem: registrationNumber, phoneNumber, status, initialDate, finalDate, page, size, orderBy. As datas seguem data civil.

Como preencher

Fora da Referência curada: phoneNumber, channel, acceptanceDate, authorizationLink, uY3Origin, additionalData, whatsAppValidation, weblinkValidation, motherName, auctionOfferValidation, channelValidation — estes campos pertencem às rotas do Crédito do Trabalhador, que a Referência de API não publica. Você não consegue conferi-los lá: as tabelas desta página são a fonte.

Corpo da autorização

additionalData — evidências do aceite

Se additionalData for enviado, ip, geoLocation e deviceModel passam a ser obrigatórios dentro do objeto. Enviar o objeto pela metade devolve 400.

Exemplo de request

curl --location --request POST '{{baseUrl}}/v1/DataprevEmployee/AuthorizationMargin' \
  --header 'Authorization: Bearer {{token}}' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
    "registrationNumber": "00000000000",
    "phoneNumber": "11900000000",
    "productId": "33333333-3333-3333-3333-333333333333",
    "channel": "LinkWeb",
    "acceptanceDate": "2026-08-25T14:30:00Z",
    "authorizationLink": "https://exemplo.com.br/termo/000123",
    "uY3Origin": false,
    "additionalData": {
      "ip": "203.0.113.10",
      "geoLocation": "-23.5505,-46.6333",
      "deviceModel": "Modelo Exemplo X1",
      "operationalSystem": "Android 14",
      "deviceType": "mobile",
      "weblinkValidation": true,
      "motherName": "MARIA F*** D*** S***",
      "birthDate": "1990-01-01"
    }
  }'

Repare no que não existe no corpo: nome completo, endereço, documento, vínculo empregatício, conta bancária. Nada disso é necessário para autorizar.

Exemplo de response

{
  "id": "44444444-4444-4444-4444-444444444444",
  "registrationNumber": "000.000.000-**",
  "phoneNumber": "(11) 9****-**00",
  "status": "Pending",
  "acceptanceDate": "2026-08-25T14:30:00Z",
  "nsu": 987654,
  "authorizationLink": "https://exemplo.com.br/termo/000123",
  "uy3Origin": false
}

O nsu é o número sequencial da autorização junto ao Crédito do Trabalhador. Guarde-o junto do id: é a referência usada em tratativa de suporte sobre uma autorização específica.

Códigos de retorno

Duração e validade

A pergunta prática é: por quanto tempo esta autorização continua servindo?

Consequência para quem integra — e é o ponto que evita retrabalho: não guarde "o trabalhador está autorizado" como um booleano permanente no seu lado, nem calcule a validade por conta própria a partir de um prazo fixo. O prazo vigente é parâmetro do Crédito do Trabalhador e pode mudar sem alteração no contrato da API.

O comportamento correto é:

1. Antes de cada consulta de margem, confira o status atual pela listagem, filtrando por registrationNumber e status=Approved.
2. Trate a recusa da consulta de margem por falta de autorização como o sinal definitivo — é ela, e não um cálculo seu, que decide se a autorização ainda vale.
3. Quando esse sinal aparecer, colete novo consentimento e registre nova autorização. Do ponto de vista do integrador, "expirada" e "inexistente" pedem exatamente a mesma ação.

Confirme com a UY3, no onboarding, o prazo vigente — para dimensionar em quanto tempo depois do aceite o seu funil precisa concluir a contratação.

Diferença em relação ao FGTS. No FGTS não existe autorização como registro estruturado: o consentimento é um documento anexado, e o prazo de validade é a política de retenção que você e o Compliance da UY3 definirem — não há prazo imposto por um órgão externo, e não há recusa automática de consulta por autorização vencida. É por isso que os dois módulos, embora espelhados na estrutura, divergem nesta etapa.

O que acontece depois

A autorização nasce Pending e passa a Approved quando o aceite do trabalhador é confirmado no canal. Só autorização Approved habilita a consulta de margem. Antes disso, a consulta responde que não há autorização válida.

Confirme o status pela listagem antes de seguir. As transições de status desta e das outras etapas estão em 4.1 Eventos e notificações.

Antes desta etapa

• 2. Pré-requisitos e cadastros — por que este é o primeiro cadastro e o que a UY3 provisiona.

Próxima etapa

• 2.2 Conta de liquidação — a conta de destino do valor liberado.
• A autorização é consumida pela consulta de margem, em 3. Operação.

Downloads

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