Consignado privado — Pré-requisitos e cadastros

Esta página é o índice dos cadastros do módulo Consignado privado. 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.

Ordem dos cadastros

A ordem importa, e ela é diferente do que a intuição sugere. A sequência é:

1. 2.1 Autorização de margem — registra o consentimento do trabalhador. Não exige tomador cadastrado.
2. 2.2 Conta de liquidação — define a conta que recebe o valor liberado. Os dados são preparados aqui.
3. 2.3 Cadastro do tomador — cria a Pessoa Física, com a conta do passo 2 no mesmo corpo, e devolve o personId.

Por que a autorização vem antes do cadastro do tomador

Porque a autorização não se identifica pelo cadastro, e sim pela pessoa: o corpo dela pede registrationNumber (CPF) e phoneNumber, e nenhum personId. Isso não é um detalhe técnico — é uma escolha de produto, e ela existe por um motivo comercial concreto.

O consentimento para consultar margem é a primeira pergunta do funil, não a última. Na prática, o trabalhador chega ao seu canal, autoriza a consulta, e só então se descobre se existe margem e qual oferta cabe nela. Se o cadastro completo fosse pré-requisito da autorização, você teria de coletar nome, endereço, documento, vínculo e conta bancária de todo interessado — inclusive dos que não têm margem e nunca vão contratar. Seria cadastro descartado em volume, com dado pessoal coletado sem necessidade.

Com a ordem correta, o funil fica assim:

Você cadastra por inteiro só quem tem margem e escolheu uma oferta.

Quais informações a autorização exige

Só o que identifica a pessoa e comprova o aceite: CPF, telefone, o canal em que o consentimento foi coletado e as evidências técnicas do aceite (IP, geolocalização, aparelho). O productId é opcional, mas recomendado — ver 2.1 Autorização de margem.

Nada de nome, endereço, documento, vínculo ou conta. Esses dados pertencem ao passo 3.

Em que momento o trabalhador passa a estar cadastrado e vinculado

No passo 3, e não antes. O que amarra a autorização ao cadastro é o CPF: a autorização foi registrada para um registrationNumber, e quando você cria a Pessoa Física com esse mesmo CPF, as duas coisas passam a se referir ao mesmo trabalhador.

Duas consequências práticas:

• Antes do cadastro, a consulta de margem funciona identificando o trabalhador por registrationNumber (CPF). Ela não exige personId.
• Depois do cadastro, a consulta de margem aceita personId, e é essa a forma preferida — o identificador é estável e não trafega dado pessoal na query string.

O vínculo ao seu usuário/correspondente também nasce no passo 3, junto do cadastro. É esse vínculo 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 à consulta de margem e à proposta

Encadeando os identificadores:

[2.1] Autorização (CPF + telefone)  ->  status Approved
                |
                | mesmo CPF
                v
[3]  Consulta de margem por registrationNumber (ou personId, depois do cadastro)
                |
                | margem livre + vínculo ativo (empregador, matrícula)
                v
[3]  Simulação  ->  offerRequestId
                |
                v
[3]  Proposta ao empregador  ->  proposalNumber
                |
                | reaparece na garantia da operação
                v
[3]  Criação da operação (personId + garantia com o vínculo e a proposta)

A consulta de margem é recusada se não houver autorização Approved para aquele CPF. A proposta é recusada se a parcela não couber na margem apurada. E a criação da operação é recusada se o personId não estiver vinculado ao seu correspondente. Cada etapa cobra a anterior — é por isso que a ordem não é decorativa.

O que dá para encurtar

• Conta e tomador em uma chamada. É o caminho recomendado nesta ordem: envie a conta na coleção bankAccounts do próprio cadastro da Pessoa Física. Uma chamada em vez de duas.
• Tomador e conta dentro da criação da operação. O objeto newPersonAndAccount do POST /v1/CreditNote cria os dois no momento da operação. Útil quando o cadastro só se justifica se a operação for para frente.
• A autorização não tem atalho. Ela é sempre um registro próprio e sempre anterior à consulta de margem.

Cadastros deste módulo

Antes desta etapa

• 1. Visão geral — o que é o produto e o fluxo completo.
• Convenções de dados — formatos de data e de valor usados nos cadastros.

Próxima etapa

• 2.1 Autorização de margem — o primeiro cadastro da sequência.

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