# UY3 — Consignado privado (contexto completo para LLM)

Gerado do portal de documentação da UY3. Contém, em um único arquivo e na ordem da
navegação, todas as páginas do módulo Consignado privado — nada de outros produtos.

## Como ler este arquivo

- Cada página aparece como `## /guia/{id} — {título}`. Links internos no formato
  `/guia/{id}` apontam para outra seção deste mesmo arquivo.
- Placeholders dos exemplos: `{{baseUrl}}` (URL base da API) e `{{token}}`
  (token Bearer). Compatíveis com variáveis de environment do Postman.
- Formato de datas, de valores monetários e de identificadores: seção
  `/guia/convencoes-de-dados`. Vale para todos os campos de toda a documentação.
- Todos os dados de exemplo são fictícios e mascarados. Dado pessoal ou sensível
  deve ser mascarado em outputs, logs e exemplos.
- A ordem das páginas de um módulo é a ordem em que as etapas devem ser
  executadas. Ela não é arbitrária: reflete a dependência de negócio entre elas.

Escopo desta versão da documentação: **Consignado privado** e **FGTS**. Os demais
produtos do catálogo entram quando forem migrados para este mesmo padrão.

Referência de API gerada do contrato OpenAPI (fora deste arquivo):
- Crédito: /referencia/creditapi/llm.md

Collections Postman:
- /downloads/uy3-api-completa.postman_collection.json
- /downloads/uy3-consignado-privado.postman_collection.json
- /downloads/uy3-fgts.postman_collection.json

## Sumário

- CaaS Massificados / Consignado privado
  - /guia/consignado-privado-visao-geral — 1. Visão geral
  - /guia/consignado-privado-cadastros — 2. Pré-requisitos e cadastros
  - /guia/consignado-privado-cadastro-autorizacao — 2.1 Autorização de margem
  - /guia/consignado-privado-cadastro-conta — 2.2 Conta de liquidação
  - /guia/consignado-privado-cadastro-pessoa — 2.3 Cadastro do tomador
  - /guia/consignado-privado-operacao — 3. Operação
  - /guia/consignado-privado-consultas — 4. Consultas e acompanhamento
  - /guia/consignado-privado-eventos — 4.1 Eventos e notificações
  - /guia/consignado-privado-erros — 5. Erros e troubleshooting

# Seção: CaaS Massificados

## Módulo: Consignado privado

## /guia/consignado-privado-visao-geral — 1. Visão geral

# Consignado privado — Visão geral

**Desconto em folha do setor privado.** O Consignado privado é a operação de crédito do trabalhador com carteira assinada (o termo interno de uso corrente na UY3 é *CLT*): as parcelas são descontadas na folha de pagamento do empregador privado, e a margem consignável do trabalhador é averbada antes da liberação do dinheiro.

Esta página abre o módulo. Ela responde o que é o produto, para quem ele serve e qual é o caminho completo — do primeiro cadastro à consulta final. Cada passo do fluxo abaixo é um link para a página que o executa.

## O que é

O Consignado privado é um empréstimo com **garantia de margem em folha**. O que o diferencia de um empréstimo sem garantia é que a concessão não depende só do cadastro e da análise de crédito: depende de a UY3 conseguir **reservar a margem consignável** do trabalhador junto ao empregador, pelo Crédito do Trabalhador (CTPS Digital).

Três consequências práticas para quem integra:

- **A margem manda no valor.** O teto da parcela não é escolhido pelo parceiro: ele sai da consulta de margem livre do trabalhador.
- **A averbação acontece antes da liquidação.** A operação entra em uma etapa de garantia e só segue para liberação quando a reserva de margem é confirmada.
- **A periodicidade é mensal e fixa.** O desconto acompanha a folha; o cronograma de parcelas é mensal, a cada 1 mês.

O lastro da operação é registrado como garantia do tipo `DataprevEmployee` — ou `DataprevEmployeeRefinance`, quando a operação substitui um contrato consignado vigente. Quando os parâmetros do produto contratado permitem, saldo e multa rescisória do FGTS entram como **reforço** dessa mesma garantia (não como produto FGTS separado — para antecipar saque-aniversário, o produto é [FGTS](/guia/fgts-visao-geral)).

## Para quem serve

| Perfil | Serve? | Por quê |
|---|---|---|
| Trabalhador com carteira assinada no setor privado | **Sim** | É o público do produto: existe vínculo ativo e margem consignável averbável. |
| Servidor público, aposentado ou pensionista do INSS | Não | Produtos próprios, fora do escopo desta versão da documentação. |
| Trabalhador sem margem livre | Não | A consulta de margem devolve margem insuficiente e a proposta é barrada antes da operação. |
| Pessoa Jurídica | Não | Não há folha de pagamento a consignar. |

Quem consome esta documentação: times de integração de correspondentes bancários, fintechs parceiras e squads internas da UY3.

## Fluxo ponta a ponta

### Passo a passo

A ordem abaixo **não é arbitrária**: é a ordem em que o negócio permite executar cada etapa. Vale a pena reparar em um ponto que costuma surpreender: a autorização de margem é o **primeiro** passo, e ela acontece antes de o trabalhador existir como cadastro na UY3.

1. **Autorização de margem.** O consentimento do trabalhador se identifica por **CPF e telefone** — não exige tomador cadastrado. É o que permite capturar o aceite no seu funil, antes de qualquer cadastro. → [2.1 Autorização de margem](/guia/consignado-privado-cadastro-autorizacao)
2. **Cadastrar a conta de liquidação.** É a conta que vai receber o dinheiro liberado. Os dados são preparados aqui e enviados junto do cadastro do tomador. → [2.2 Conta de liquidação](/guia/consignado-privado-cadastro-conta)
3. **Cadastrar o tomador (Pessoa Física).** É aqui que o trabalhador passa a existir e a estar vinculado ao seu usuário/correspondente, com a conta do passo anterior no mesmo corpo. → [2.3 Cadastro do tomador](/guia/consignado-privado-cadastro-pessoa)
4. **Consultar a margem livre e simular.** A margem define o teto da parcela. A simulação tem **dois caminhos possíveis** — ofertas ou amortização (ver abaixo). → [3. Operação](/guia/consignado-privado-operacao)
5. **Enviar a proposta e criar a operação de crédito.** A operação nasce em rascunho, com a garantia de margem anexada. → [3. Operação](/guia/consignado-privado-operacao)
6. **Enviar para aprovação, assinar e aguardar a averbação.** A operação percorre as etapas de crédito, garantia e assinatura. → [3. Operação](/guia/consignado-privado-operacao)
7. **Acompanhar status, liquidação e comprovante.** Do envio até o encerramento, o acompanhamento é por consulta. → [4. Consultas e acompanhamento](/guia/consignado-privado-consultas)

Os eventos que marcam cada transição estão em [4.1 Eventos e notificações](/guia/consignado-privado-eventos). Quando algum passo falha, a causa e a ação corretiva estão em [5. Erros e troubleshooting](/guia/consignado-privado-erros).

### Diagrama do fluxo

```text
[2.1] Autorização de margem            (CPF + telefone — sem tomador cadastrado)
   |
[2.2] Dados da conta de liquidação     (preparados)
   |
[2.3] Cadastro do tomador (PF)         (com a conta no mesmo corpo -> personId)
   |
[3] Consulta de margem livre
   |
   +--> Caminho A: simulação de ofertas ---> proposta ao empregador
   |
   +--> Caminho B: simulação por amortização (plano de pagamento)
   |
[3] Criação da operação de crédito (garantia de margem anexada)
   |
[3] Envio para aprovação -> Crédito -> Garantia (averbação) -> Assinatura
   |
[3] Liquidação (Pix/TED na conta do tomador)
   |
[4] Acompanhamento: status, parcelas, comprovante
```

### Os dois caminhos de simulação

Este é um ponto em que a documentação anterior induzia ao erro: dava a impressão de que o fluxo de ofertas era o único possível. Não é. Os dois caminhos são válidos, levam à mesma criação de operação, e a escolha é sua.

| | **Caminho A — Simulação de ofertas** | **Caminho B — Simulação por amortização** |
|---|---|---|
| Pergunta que responde | *Quais produtos e condições cabem na margem deste trabalhador?* | *Como fica o plano de pagamento desta condição que eu já escolhi?* |
| Rota | `POST /v1/Amortization/DataprevEmployeeOffers` | `POST /v1/Amortization` |
| Você informa | CPF, vínculo e uma faixa (valor, prazo, parcela) | produto, valor, taxa e prazo exatos |
| Você recebe | uma **lista de ofertas** elegíveis, com prazo, parcela, taxa, CET e IOF | **um plano de pagamento** completo, parcela a parcela |
| Quando usar | vitrine para o trabalhador escolher; você não sabe ainda a condição | condição já definida (tabela negociada, escolha do cliente, recontratação) |
| Leva à proposta ao empregador? | Sim — a oferta escolhida gera o `offerRequestId` da proposta | Não passa pela proposta: vai direto à criação da operação |

Detalhe e exemplos dos dois caminhos em [3. Operação](/guia/consignado-privado-operacao). Ainda dentro do caminho A, é possível **simular um valor menor que a margem total disponível** — ver a seção de simulação abaixo da margem na mesma página.

## Regras de negócio que decidem o produto

| Regra | Por que existe | Efeito na integração |
|---|---|---|
| Periodicidade mensal obrigatória | O desconto acompanha a folha de pagamento, que é mensal. Não há folha quinzenal nem anual a consignar. | `paymentPeriodicity` precisa ser `{ "every": 1, "periodicity": "Monthly" }`. Qualquer outro valor é recusado. |
| Modelo de cálculo Price ou SAC | A averbadora precisa de um cronograma de parcelas previsível para reservar margem mês a mês. | O `amortizationType` enviado precisa coincidir com o do produto contratado. As rotas de oferta do Crédito do Trabalhador listam apenas produtos Price. |
| Margem livre suficiente | A parcela é descontada da folha: se não couber na margem, o empregador não tem de onde descontar. | A parcela simulada é validada contra a margem no momento da proposta — e revalidada quando o empregador aceita. |
| Garantia obrigatória para envio à aprovação | Sem a garantia de margem informada, não há o que averbar. | Sem ao menos uma garantia no corpo, o envio para aprovação é recusado. |

Os parâmetros de averbação (averbadora, faixa de taxa, faixa de prazo, dia de repasse) são provisionados **pela UY3** e referenciados por um identificador de produto. Você não os cria pela API: você recebe o `productId` e trabalha dentro dos limites dele.

Formato de datas, de valores monetários e de taxas: [Convenções de dados](/guia/convencoes-de-dados). É a mesma convenção em todos os campos deste módulo.

## O que este produto não é

- **Não é empréstimo sem garantia.** Aqui a concessão depende da reserva de margem junto ao empregador.
- **Não é antecipação de saque-aniversário.** Para isso, use [FGTS](/guia/fgts-visao-geral). Aqui o FGTS entra, quando entra, apenas como reforço da garantia de margem.
- **Não é consignado de servidor nem de benefício do INSS.** Produtos próprios, fora do escopo desta versão.

## Antes desta etapa

- [Primeiros passos](/guia/primeiros-passos) — como obter acesso e o `productId` do seu produto contratado.
- [Autenticação](/guia/autenticacao) — como emitir e renovar o token enviado em todas as chamadas.
- [Convenções de dados](/guia/convencoes-de-dados) — formatos de data, valor e taxa usados em todo o módulo.

## Próxima etapa

- [2. Pré-requisitos e cadastros](/guia/consignado-privado-cadastros) — o que precisa estar pronto e em que ordem.

## Downloads

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

---

## /guia/consignado-privado-cadastros — 2. Pré-requisitos e cadastros

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

| Pré-requisito | O que é | O que você recebe |
|---|---|---|
| Credencial de integração | Token de acesso do seu usuário/correspondente. | Credenciais para emitir o token — ver [Autenticação](/guia/autenticacao). |
| Produto contratado | Define modelo de cálculo (Price ou SAC), faixa de taxa e faixa de prazo do consignado privado. | `productId` (uuid). |
| Parâmetros de averbação | Averbadora e dia de repasse do produto. | Vinculados ao `productId`; nenhum campo a enviar. |
| Habilitação do Crédito do Trabalhador | Credenciais de integração da UY3 com o Crédito do Trabalhador (CTPS Digital). | Nada a enviar; habilitação por ambiente do parceiro. |

## 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](/guia/consignado-privado-cadastro-autorizacao)** — registra o consentimento do trabalhador. **Não exige tomador cadastrado.**
2. **[2.2 Conta de liquidação](/guia/consignado-privado-cadastro-conta)** — define a conta que recebe o valor liberado. Os dados são preparados aqui.
3. **[2.3 Cadastro do tomador](/guia/consignado-privado-cadastro-pessoa)** — 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:

| Etapa | O que você já tem do trabalhador | O que descobre |
|---|---|---|
| 1. Autorização | CPF e telefone | se o consentimento foi aceito |
| 2. Consulta de margem | o mesmo CPF | se há margem livre e qual é o vínculo ativo |
| 3. Simulação | margem e vínculo | quais condições cabem |
| 4. Cadastro completo | tudo acima, e o interesse confirmado | — |

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](/guia/consignado-privado-cadastro-autorizacao).

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:

```text
[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

| Cadastro | Serve para | Exige `personId`? | Consumido por |
|---|---|---|---|
| [Autorização de margem](/guia/consignado-privado-cadastro-autorizacao) | Registrar o consentimento do trabalhador para consulta de margem. | **Não** | Consulta de margem, em [3. Operação](/guia/consignado-privado-operacao) |
| [Conta de liquidação](/guia/consignado-privado-cadastro-conta) | Definir a conta que recebe o valor liberado. | Depende do caminho | Liquidação, em [3. Operação](/guia/consignado-privado-operacao) |
| [Cadastro do tomador](/guia/consignado-privado-cadastro-pessoa) | Identificar o trabalhador e registrar vínculo, cargo e renda. | Cria o `personId` | Criação da operação, em [3. Operação](/guia/consignado-privado-operacao) |

## Antes desta etapa

- [1. Visão geral](/guia/consignado-privado-visao-geral) — o que é o produto e o fluxo completo.
- [Convenções de dados](/guia/convencoes-de-dados) — formatos de data e de valor usados nos cadastros.

## Próxima etapa

- [2.1 Autorização de margem](/guia/consignado-privado-cadastro-autorizacao) — o primeiro cadastro da sequência.

## Downloads

- Contexto para LLM deste módulo: [llms-consignado-privado.txt](/downloads/llms-consignado-privado.txt)
- Collection Postman do módulo: [uy3-consignado-privado.postman_collection.json](/downloads/uy3-consignado-privado.postman_collection.json)
- Documentação consolidada para LLM: [llms.txt](/downloads/llms.txt)

---

## /guia/consignado-privado-cadastro-autorizacao — 2.1 Autorização de margem

# 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](/guia/convencoes-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](/guia/consignado-privado-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](/guia/autenticacao).
- 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

| Método | Rota | Uso |
|---|---|---|
| POST | `/v1/DataprevEmployee/AuthorizationMargin` | Registra a autorização de consulta de margem. |
| GET | `/v1/DataprevEmployee/AuthorizationMargin` | Lista autorizações por CPF, telefone, status e período, com paginação. |
| GET | `/v1/DataprevEmployee/AuthorizationMargin/{id}` | Consulta uma autorização por identificador. |

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](/referencia/creditapi) não publica. Você não consegue conferi-los lá: as tabelas desta página são a fonte.

### Corpo da autorização

| Campo | Tipo | Obrigatório | Como preencher | Exemplo |
|---|---|---|---|---|
| `registrationNumber` | string | Sim | CPF do trabalhador que está autorizando. É a chave que vai amarrar esta autorização ao cadastro do tomador mais tarde. | `000.000.000-00` |
| `phoneNumber` | string | Sim | Celular com DDD que recebeu (ou vai receber) a validação. Precisa ser o mesmo telefone que você usará no cadastro do tomador. | `(11) 9****-**00` |
| `productId` | string (uuid) | Não (envie) | Produto contratado para o qual a autorização vale. Sem ele a autorização é genérica e pode não casar com o produto da proposta. | `33333333-3333-3333-3333-333333333333` |
| `channel` | enum | Não (envie) | Canal em que o consentimento foi coletado: `WhatsappInbound`, `SMS` ou `LinkWeb`. Determina qual evidência é esperada em `additionalData`. | `LinkWeb` |
| `status` | enum | Não | `Pending`, `Approved` ou `Refused`. Omita na criação e deixe o fluxo do canal resolver; envie explicitamente só quando você mesmo coletou e validou o aceite. | `Pending` |
| `acceptanceDate` | `data e hora` | Não (envie) | Data e hora do aceite, em UTC com sufixo `Z`. Sem ela não há prova de quando o consentimento foi dado — e é dela que o prazo de validade conta. | `2026-08-25T14:30:00Z` |
| `authorizationLink` | string | Não | URL do termo apresentado ao trabalhador, quando o canal é `LinkWeb`. | `https://exemplo.com.br/termo/000123` |
| `uY3Origin` | booleano | Não | `true` quando a coleta do aceite foi feita em canal da UY3; `false` quando foi no seu canal. | `false` |
| `additionalData` | objeto | Não (envie) | Evidências técnicas do aceite. Ver a tabela abaixo. | ver exemplo |

### `additionalData` — evidências do aceite

| Campo | Tipo | Obrigatório | Como preencher | Exemplo |
|---|---|---|---|---|
| `ip` | string | Sim (no objeto) | IP de onde partiu o aceite. Evidência mínima de origem. | `203.0.113.10` |
| `geoLocation` | string | Sim (no objeto) | Latitude e longitude no momento do aceite, separadas por vírgula. | `-23.5505,-46.6333` |
| `deviceModel` | string | Sim (no objeto) | Modelo do aparelho usado no aceite. | `Modelo Exemplo X1` |
| `userAgent` | string | Não | User agent do navegador ou app. | `Mozilla/5.0 (...)` |
| `operationalSystem` | string | Não | Sistema operacional do aparelho. | `Android 14` |
| `deviceName` / `deviceType` | string | Não | Nome e tipo do aparelho (`mobile`, `desktop`). | `mobile` |
| `smsValidation` | booleano | Não | `true` se houve validação por SMS. | `true` |
| `whatsAppValidation` | booleano | Não | `true` se houve validação por WhatsApp. | `false` |
| `emailValidation` | booleano | Não | `true` se houve validação por e-mail. | `false` |
| `weblinkValidation` | booleano | Não | `true` se o aceite se deu por link web. | `true` |
| `motherName` | string | Não (envie) | Nome da mãe conferido no aceite. Segundo fator de identidade. | `MARIA F*** D*** S***` |
| `birthDate` | `data civil` | Não (envie) | Data de nascimento conferida no aceite. | `1990-01-01` |
| `auctionOfferValidation` | booleano | Não | `true` quando o aceite veio da aceitação de uma oferta de leilão CTPS. | `false` |
| `channelValidation` | string | Não | Identificador do desafio validado no canal (protocolo ou código). | `VAL-000123` |

> 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

```bash
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

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

| Código | Significado | O que fazer |
|---|---|---|
| `200` | Autorização registrada. | Guarde o `id` e o `nsu`. Acompanhe até `status = Approved`. |
| `400` | CPF ou telefone ausente/inválido, ou `additionalData` incompleto. | Confira as duas tabelas de preenchimento acima. |
| `401` | Token ausente, expirado ou inválido. | Renove o token — ver [Autenticação](/guia/autenticacao). |
| `403` | Sem permissão para registrar autorização neste ambiente. | Confirme a habilitação do Crédito do Trabalhador com a UY3. |
| `404` | Autorização inexistente (na consulta por `{id}`). | Confira o identificador. |

## Duração e validade

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

| | Consignado privado |
|---|---|
| O que define o prazo | Regra do **Crédito do Trabalhador**, não do parceiro nem do seu produto. |
| Quando começa a contar | Do **aceite** do trabalhador — `acceptanceDate` — e não da data em que você registrou o cadastro. |
| Onde ler a data-base | Campo `acceptanceDate` do retorno. |
| Existe campo de expiração no contrato? | **Não.** A autorização não expõe data de validade nem status `Expired`. |
| O que acontece quando expira | A autorização continua existindo com `status = Approved`, mas a **consulta de margem passa a ser recusada** por falta de autorização válida. |
| Como renovar | Colete um aceite novo e registre outra autorização (`POST`) para o mesmo CPF. Não há rota de renovação nem de extensão de prazo. |

**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](/guia/fgts-cadastro-autorizacao) 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](/guia/consignado-privado-eventos).

## Antes desta etapa

- [2. Pré-requisitos e cadastros](/guia/consignado-privado-cadastros) — por que este é o primeiro cadastro e o que a UY3 provisiona.

## Próxima etapa

- [2.2 Conta de liquidação](/guia/consignado-privado-cadastro-conta) — a conta de destino do valor liberado.
- A autorização é consumida pela consulta de margem, em [3. Operação](/guia/consignado-privado-operacao).

## Downloads

- Contexto para LLM deste módulo: [llms-consignado-privado.txt](/downloads/llms-consignado-privado.txt)
- Collection Postman do módulo: [uy3-consignado-privado.postman_collection.json](/downloads/uy3-consignado-privado.postman_collection.json)
- Documentação consolidada para LLM: [llms.txt](/downloads/llms.txt)

---

## /guia/consignado-privado-cadastro-conta — 2.2 Conta de liquidação

# Consignado privado — Conta de liquidação

Dado pessoal ou bancário deve ser **mascarado** em outputs, logs e exemplos. Todos os valores desta página são fictícios. Formatos de data e de valor: [Convenções de dados](/guia/convencoes-de-dados).

## O que é

A conta de liquidação é a conta bancária **do próprio tomador** que recebe o valor liberado do consignado privado. O identificador dela é o `bankAccountId` informado na criação da operação.

A liquidação do consignado privado é sempre por **transferência eletrônica** (Pix ou TED). Não há liquidação por boleto neste produto.

> **Como esta etapa se encaixa na ordem.** A conta é um dado **do tomador** — a rota dedicada dela pede o `personId` no caminho. Nesta etapa você **prepara e valida** os dados da conta; o envio acontece de uma das duas formas abaixo. É por isso que a conta aparece antes do cadastro do tomador na sequência: na prática você coleta os dados bancários junto com o interesse do trabalhador, e os envia **dentro** do cadastro dele.

## Os dois caminhos de envio

| | **Caminho A — junto do cadastro do tomador** | **Caminho B — depois do cadastro** |
|---|---|---|
| Como | Coleção `bankAccounts` no corpo de `POST /v1/NaturalPerson` | `POST /v1/NaturalPerson/{id}/BankAccount` |
| Exige `personId` antes? | **Não** | Sim |
| Chamadas | Uma | Duas |
| Quando usar | Fluxo novo — é o **caminho recomendado** nesta ordem de cadastros. | Trabalhador já cadastrado; troca ou acréscimo de conta. |

Os campos são **os mesmos** nos dois caminhos: o que muda é onde o objeto vai. As tabelas de preenchimento abaixo valem para os dois.

Se o tomador já tem conta cadastrada e ela continua válida, reaproveite o `bankAccountId` — não crie outra. Contas duplicadas geram escolha errada na liquidação.

## Quando usar

- Sempre, antes de criar a operação: sem conta não há para onde liberar o dinheiro.
- Para trocar a conta de destino antes de a operação ser liquidada (caminho B).

## Pré-requisitos

- Token válido — ver [Autenticação](/guia/autenticacao).
- Dados bancários do trabalhador, conferidos com ele.
- Para o **caminho B**: o `personId`, obtido em [2.3 Cadastro do tomador](/guia/consignado-privado-cadastro-pessoa).

## Endpoints do cadastro

| Método | Rota | Uso |
|---|---|---|
| POST | `/v1/NaturalPerson` | Caminho A: cria o tomador **com** a conta na coleção `bankAccounts`. |
| POST | `/v1/NaturalPerson/{id}/BankAccount` | Caminho B: cadastra uma ou mais contas para um tomador que já existe. |
| PUT | `/v1/NaturalPerson/{id}/BankAccount/{bankAccountId}` | Corrige os dados de uma conta já cadastrada. |
| DELETE | `/v1/NaturalPerson/{id}/BankAccount/{bankAccountId}` | Remove uma conta. Recusado quando a conta está amarrada a operação em andamento. |
| GET | `/v1/NaturalPerson/{id}` | Lista as contas do tomador, para reaproveitar o `bankAccountId`. |

## Como preencher

### Meio de liquidação

| Campo | Tipo | Obrigatório | Como preencher | Exemplo |
|---|---|---|---|---|
| `operationTypeValue` | enum | Sim | Meio de liquidação da conta: `Pix` ou `Transfer` (TED). Define quais dos campos abaixo passam a ser exigidos — decida isto primeiro. | `Pix` |
| `type` | enum | Não (envie) | Natureza da conta. Para o tomador PF, use `NaturalCheckingAccount` (corrente) ou `NaturalSavingsAccount` (poupança). | `NaturalCheckingAccount` |
| `jointAccount` | booleano | Não | `true` para conta conjunta. Conta conjunta pode exigir documento adicional na esteira. | `false` |

### Quando `operationTypeValue` é `Pix`

| Campo | Tipo | Obrigatório | Como preencher | Exemplo |
|---|---|---|---|---|
| `pixKeyTypeValue` | enum | Sim | Tipo da chave: `NaturalRegistrationNumber` (CPF), `Phone`, `Email`, `Automatic` (aleatória) ou `AgencyAndAccount`. | `NaturalRegistrationNumber` |
| `keyPix` | string | Sim | A chave, no formato do tipo escolhido. Com `NaturalRegistrationNumber`, use o **mesmo CPF** do tomador — chave de terceiro é recusada na liquidação. | `000.000.000-00` |
| `bankCode` | inteiro | Não | Código Compe do banco da chave. Ajuda a conciliação; não substitui a chave. | `341` |

### Quando `operationTypeValue` é `Transfer` (TED)

| Campo | Tipo | Obrigatório | Como preencher | Exemplo |
|---|---|---|---|---|
| `bankCode` | inteiro | Sim | Código Compe do banco (3 dígitos). Alternativa: informe `bankIspb`. | `341` |
| `bankIspb` | inteiro | Condicional | ISPB do banco, quando o código Compe não estiver disponível. | `60701190` |
| `agency` | string | Sim | Agência, até 4 dígitos, sem o dígito verificador. | `0001` |
| `agencyDigit` | string | Não | Dígito da agência, 1 caractere, quando o banco usar. | `0` |
| `account` | string | Sim | Número da conta, sem o dígito verificador e sem pontuação. | `12345678` |
| `accountDigit` | string | Sim | Dígito verificador da conta, 1 caractere. | `9` |

> **Titularidade.** A conta precisa ser do CPF do tomador; é conferido na liquidação. Chave Pix ou conta de terceiro reprova a liquidação e devolve a operação para revisão de pagamento — depois de a operação já estar assinada e averbada, que é o pior momento para descobrir. Confira antes.

## Exemplo de request

**Caminho A — a conta dentro do cadastro do tomador** (recomendado). O corpo completo do tomador está em [2.3 Cadastro do tomador](/guia/consignado-privado-cadastro-pessoa); aqui, só a parte da conta:

```bash
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": "JOAO D*** S*** SANTOS",
    "email": "tomador@exemplo.com.br",
    "phone": "11900000000",
    "bankAccounts": [
      {
        "operationTypeValue": "Pix",
        "type": "NaturalCheckingAccount",
        "pixKeyTypeValue": "NaturalRegistrationNumber",
        "keyPix": "00000000000",
        "bankCode": 341,
        "jointAccount": false
      }
    ]
  }'
```

**Caminho B — conta para um tomador que já existe:**

```bash
curl --location --request POST '{{baseUrl}}/v1/NaturalPerson/11111111-1111-1111-1111-111111111111/BankAccount' \
  --header 'Authorization: Bearer {{token}}' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '[
    {
      "operationTypeValue": "Pix",
      "type": "NaturalCheckingAccount",
      "pixKeyTypeValue": "NaturalRegistrationNumber",
      "keyPix": "00000000000",
      "bankCode": 341,
      "jointAccount": false
    }
  ]'
```

## Exemplo de response

No caminho A, a conta volta dentro do cadastro do tomador:

```json
{
  "id": "11111111-1111-1111-1111-111111111111",
  "registrationNumber": "000.000.000-**",
  "bankAccounts": [
    {
      "id": "22222222-2222-2222-2222-222222222222",
      "operationTypeValue": "Pix",
      "pixKeyTypeValue": "NaturalRegistrationNumber",
      "keyPix": "000.000.000-**",
      "bankCode": 341
    }
  ]
}
```

No caminho B, volta a lista de contas criadas. Nos dois casos, o `id` **da conta** é o `bankAccountId` da criação da operação — não confunda com o `id` da pessoa, que é o `personId`.

## Códigos de retorno

| Código | Significado | O que fazer |
|---|---|---|
| `200` | Conta cadastrada. | Guarde o `id` da conta como `bankAccountId`. |
| `400` | Combinação inválida: `Pix` sem chave, `Transfer` sem agência/conta, dígito com mais de 1 caractere. | Confira a tabela do meio de liquidação escolhido. |
| `401` | Token ausente, expirado ou inválido. | Renove o token — ver [Autenticação](/guia/autenticacao). |
| `403` | Sem permissão sobre esse cadastro de pessoa. | Confirme o vínculo do cadastro com o seu usuário/correspondente. |
| `404` | `personId` ou `bankAccountId` inexistente (caminho B). | Confira os identificadores. |

## O que acontece depois

A conta fica disponível para ser escolhida na operação. Nada é debitado ou creditado neste momento: o cadastro apenas declara o destino do valor.

## Antes desta etapa

- [2.1 Autorização de margem](/guia/consignado-privado-cadastro-autorizacao) — o cadastro anterior da sequência.

## Próxima etapa

- [2.3 Cadastro do tomador](/guia/consignado-privado-cadastro-pessoa) — onde o objeto da conta é enviado, no caminho recomendado.
- O `bankAccountId` é consumido em [3. Operação](/guia/consignado-privado-operacao).

## Downloads

- Contexto para LLM deste módulo: [llms-consignado-privado.txt](/downloads/llms-consignado-privado.txt)
- Collection Postman do módulo: [uy3-consignado-privado.postman_collection.json](/downloads/uy3-consignado-privado.postman_collection.json)
- Documentação consolidada para LLM: [llms.txt](/downloads/llms.txt)

---

## /guia/consignado-privado-cadastro-pessoa — 2.3 Cadastro do tomador

# Consignado privado — Cadastro do tomador

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 e de valor: [Convenções de dados](/guia/convencoes-de-dados).

## O que é

O cadastro do tomador cria (ou atualiza) a **Pessoa Física** que vai contratar o consignado privado: o trabalhador com carteira assinada. O retorno traz o `personId`, identificador usado em todas as etapas seguintes.

É também o momento em que **o trabalhador passa a estar vinculado ao seu usuário/correspondente**. Até aqui existia apenas um consentimento associado a um CPF; a partir daqui existe um cadastro seu, e é esse vínculo que a criação da operação confere.

O cadastro é o mesmo recurso de Pessoa Física usado por outros produtos, mas o **preenchimento é específico deste produto**: aqui os campos de vínculo empregatício (empregador, matrícula, cargo, data de admissão, salário) deixam de ser opcionais na prática, porque são eles que a averbadora usa para localizar o vínculo e reservar a margem.

## Quando usar

- Depois da autorização e com os dados da conta em mãos, para o trabalhador que **tem margem e escolheu uma oferta**.
- Para atualizar dados de vínculo de um trabalhador já cadastrado (troca de empregador, mudança de cargo, novo salário).

Se o CPF já existir e estiver visível ao seu usuário, a criação **atualiza** o cadastro existente e devolve o `id` do registro que já havia — não cria duplicata. Coleções relacionadas (contas bancárias, documentos) são combinadas.

## Pré-requisitos

- Token válido — ver [Autenticação](/guia/autenticacao).
- **Autorização de margem já registrada para o mesmo CPF** — ver [2.1 Autorização de margem](/guia/consignado-privado-cadastro-autorizacao). É o CPF que amarra as duas coisas.
- Dados da conta de liquidação preparados — ver [2.2 Conta de liquidação](/guia/consignado-privado-cadastro-conta). Eles vão na coleção `bankAccounts` deste mesmo corpo.
- Dados do vínculo empregatício, obtidos na consulta de margem ou com o trabalhador.

## Endpoints do cadastro

| Método | Rota | Uso |
|---|---|---|
| POST | `/v1/NaturalPerson` | Cria ou atualiza a Pessoa Física, com a conta em `bankAccounts`, e devolve o `personId`. |
| GET | `/v1/NaturalPerson` | Busca por CPF, nome, e-mail ou telefone antes de criar. |
| GET | `/v1/NaturalPerson/{id}` | Consulta o cadastro completo por identificador. |
| PUT | `/v1/NaturalPerson/{id}` | Atualiza o cadastro. Coleções não enviadas são **excluídas** — envie `null` para preservá-las. |
| POST | `/v1/NaturalPerson/{id}/Upload` | Anexa documentos ao cadastro (identidade, comprovante de vínculo). |

> **Armadilha do `PUT`.** Uma atualização que omite `bankAccounts` apaga as contas do cadastro, e isso quebra operações em andamento que apontam para elas. Para mexer só na conta, use as rotas de [2.2 Conta de liquidação](/guia/consignado-privado-cadastro-conta).

## Como preencher

### Identificação (obrigatória em qualquer produto)

| Campo | Tipo | Obrigatório | Como preencher | Exemplo |
|---|---|---|---|---|
| `registrationNumber` | string | Sim | CPF do trabalhador, só dígitos. É a chave de deduplicação do cadastro **e** o que amarra este cadastro à autorização de margem já registrada. | `000.000.000-00` |
| `name` | string | Sim | Nome civil completo, como consta no documento de identidade. Sem abreviar. | `JOAO D*** S*** SANTOS` |
| `email` | string | Sim | E-mail válido do próprio trabalhador — é por ele que a assinatura eletrônica é enviada. | `tomador@exemplo.com.br` |
| `phone` | string | Sim | Celular com DDD. Use **o mesmo telefone** informado na autorização de margem: divergência entre os dois é causa comum de recusa na validação de identidade. | `(11) 9****-**00` |
| `birthDate` | `data civil` | Não (envie) | Data de nascimento. Usada na validação de identidade. | `1990-01-01` |
| `mothersName` | string | Não (envie) | Nome completo da mãe. Segundo fator da validação de identidade. | `MARIA F*** D*** S***` |
| `socialName` | string | Não | Nome social, quando houver. Não substitui `name` nos documentos. | `—` |
| `pep` | booleano | Não | `true` se o tomador é pessoa exposta politicamente. Afeta a análise de compliance. | `false` |

### Vínculo empregatício (o que este produto realmente exige)

Estes campos existem porque a **averbadora precisa localizar o vínculo** para reservar margem. Não são dado cadastral decorativo: sem eles, a garantia da operação fica sem a que se referir.

| Campo | Tipo | Obrigatório | Como preencher | Exemplo |
|---|---|---|---|---|
| `natureOfOccupation` | enum | Sim para este produto | Use `PrivateEmployee`. Qualquer outro valor descreve um público que não é o deste produto. | `PrivateEmployee` |
| `workplace` | string | Sim para este produto | Razão social do empregador privado, igual à do registro do empregador. | `EMPRESA EXEMPLO LTDA` |
| `workplaceCompanyRegistrationNumber` | string | Sim para este produto | CNPJ do empregador. É a chave que amarra o trabalhador ao registro do empregador na averbação. Use o valor devolvido pela consulta de margem. | `00.000.000/0000-00` |
| `employeeNumber` | string | Sim para este produto | Matrícula do trabalhador no empregador. Reaparece na garantia como código do empregado. | `MAT-000123` |
| `admissionDate` | `data civil` | Sim para este produto | Data de admissão. Compõe a identificação do vínculo na averbação. | `2022-03-01` |
| `occupation` | string | Não (envie) | Cargo em texto livre. | `ANALISTA ADMINISTRATIVO` |
| `netSalary` | `decimal em reais` | Não (envie) | Salário líquido mensal. Base de referência da margem. | `4500.00` |
| `otherIncome` | `decimal em reais` | Não | Outras rendas comprováveis. | `0.00` |
| `department` | string | Não | Departamento ou setor no empregador. | `ADMINISTRATIVO` |

> "Sim para este produto" significa: o contrato aceita a ausência, mas a averbação não encontra o vínculo sem o campo. Trate como obrigatório.

### Conta de liquidação

| Campo | Tipo | Obrigatório | Como preencher | Exemplo |
|---|---|---|---|---|
| `bankAccounts` | lista de objetos | Sim para este produto | A conta que vai receber o valor liberado. Campo a campo em [2.2 Conta de liquidação](/guia/consignado-privado-cadastro-conta) — enviar aqui é o caminho recomendado, e economiza uma chamada. | ver exemplo abaixo |

O `id` de cada item devolvido nesta coleção é o `bankAccountId` da criação da operação.

### Endereço e documento

| Campo | Tipo | Obrigatório | Como preencher | Exemplo |
|---|---|---|---|---|
| `address` | objeto | Não (envie) | Endereço residencial completo. Exigido na emissão do instrumento de crédito. Dentro do objeto, `addressName` (logradouro), `city` e `district` são **obrigatórios**. | ver exemplo abaixo |
| `documentType` | enum | Não (envie) | Tipo do documento de identidade apresentado. Aceitos: `RG`, `CPF`, `CNH`, `CTPS`. | `RG` |
| `documentNumber` | string | Não (envie) | Número do documento, como impresso. | `00.000.000-0` |
| `documentIssuer` | string | Não | Órgão emissor do documento. | `SSP/SP` |
| `documentDate` | `data civil` | Não | Data de emissão do documento. | `2015-06-10` |
| `uploads` | lista | Não | Documentos digitalizados. Alternativa: `POST /v1/NaturalPerson/{id}/Upload` depois de criar. | ver [3. Operação](/guia/consignado-privado-operacao) |

## Exemplo de request

```bash
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": "JOAO D*** S*** SANTOS",
    "email": "tomador@exemplo.com.br",
    "phone": "11900000000",
    "birthDate": "1990-01-01",
    "mothersName": "MARIA F*** D*** S***",
    "pep": false,
    "natureOfOccupation": "PrivateEmployee",
    "workplace": "EMPRESA EXEMPLO LTDA",
    "workplaceCompanyRegistrationNumber": "00000000000000",
    "employeeNumber": "MAT-000123",
    "admissionDate": "2022-03-01",
    "occupation": "ANALISTA ADMINISTRATIVO",
    "netSalary": 4500.00,
    "address": {
      "addressName": "Rua Exemplo",
      "number": "100",
      "district": "Centro",
      "city": "Sao Paulo",
      "uf": "SP",
      "zipCode": "00000000"
    },
    "bankAccounts": [
      {
        "operationTypeValue": "Pix",
        "type": "NaturalCheckingAccount",
        "pixKeyTypeValue": "NaturalRegistrationNumber",
        "keyPix": "00000000000",
        "bankCode": 341,
        "jointAccount": false
      }
    ]
  }'
```

## Exemplo de response

```json
{
  "id": "11111111-1111-1111-1111-111111111111",
  "registrationNumber": "000.000.000-**",
  "name": "JOAO D*** S*** SANTOS",
  "natureOfOccupation": "PrivateEmployee",
  "workplaceCompanyRegistrationNumber": "00000000000000",
  "employeeNumber": "MAT-000123",
  "admissionDate": "2022-03-01T00:00:00Z",
  "bankAccounts": [
    {
      "id": "22222222-2222-2222-2222-222222222222",
      "operationTypeValue": "Pix",
      "pixKeyTypeValue": "NaturalRegistrationNumber",
      "keyPix": "000.000.000-**"
    }
  ]
}
```

Dois identificadores saem daqui, e são os dois que a operação pede:

- `id` da pessoa → **`personId`**
- `id` do item de `bankAccounts` → **`bankAccountId`**

## Códigos de retorno

| Código | Significado | O que fazer |
|---|---|---|
| `200` | Cadastro criado ou atualizado. | Guarde o `id` como `personId` e o `id` da conta como `bankAccountId`. |
| `400` | Corpo inválido: CPF malformado, e-mail inválido, campo obrigatório ausente, conta com combinação inválida. | Corrija o campo apontado na resposta e reenvie. |
| `401` | Token ausente, expirado ou inválido. | Renove o token — ver [Autenticação](/guia/autenticacao). |
| `403` | Sem permissão para criar ou ver esse cadastro. | Confirme o perfil do usuário/correspondente com a UY3. |
| `404` | Identificador inexistente (nas rotas com `{id}`). | Confira o `personId`. |

## O que acontece depois

O cadastro passa a existir vinculado ao seu usuário/correspondente. Esse vínculo é conferido em toda operação: sem ele, a criação da operação é recusada mesmo com `personId` válido.

A partir daqui, a consulta de margem pode ser feita por `personId` em vez de CPF — é a forma preferida, porque o identificador é estável e não trafega dado pessoal na query string.

Com os três cadastros prontos, o fluxo entra na operação.

## Antes desta etapa

- [2.2 Conta de liquidação](/guia/consignado-privado-cadastro-conta) — os campos da conta enviada aqui.
- [2.1 Autorização de margem](/guia/consignado-privado-cadastro-autorizacao) — a autorização que precisa existir para o mesmo CPF.

## Próxima etapa

- [3. Operação](/guia/consignado-privado-operacao) — consulta de margem, simulação, proposta e criação da operação.

## Downloads

- Contexto para LLM deste módulo: [llms-consignado-privado.txt](/downloads/llms-consignado-privado.txt)
- Collection Postman do módulo: [uy3-consignado-privado.postman_collection.json](/downloads/uy3-consignado-privado.postman_collection.json)
- Documentação consolidada para LLM: [llms.txt](/downloads/llms.txt)

---

## /guia/consignado-privado-operacao — 3. Operação

# Consignado privado — 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](/guia/convencoes-de-dados).

## O que é

Esta é a página do fluxo principal: da consulta de margem até a operação assinada e liquidada. Ela assume que os três cadastros de [2. Pré-requisitos e cadastros](/guia/consignado-privado-cadastros) já existem.

A sequência é rígida por um motivo de negócio: **a margem define o teto da parcela**, e a parcela define a condição que a operação pode carregar. Pular a consulta de margem produz operação que a averbação recusa.

O que **não** é rígido é o caminho da simulação: há dois, e os dois são válidos.

## Quando usar

- Sempre que houver um trabalhador cadastrado, com autorização `Approved`, e um valor a contratar.
- Para retomar uma operação em rascunho que precisa de correção antes do envio à aprovação.

## Pré-requisitos

| Item | Origem |
|---|---|
| Autorização `Approved` | [2.1 Autorização de margem](/guia/consignado-privado-cadastro-autorizacao) |
| `bankAccountId` | [2.2 Conta de liquidação](/guia/consignado-privado-cadastro-conta) |
| `personId` | [2.3 Cadastro do tomador](/guia/consignado-privado-cadastro-pessoa) |
| `productId` | Fornecido pela UY3 no onboarding |
| Token válido | [Autenticação](/guia/autenticacao) |

## Endpoints do fluxo principal

### Passo 1 — Consultar a margem livre

```http
POST /v1/DataprevEmployee/FreeMarginQuery
GET  /v1/DataprevEmployee/FreeMarginQuery
```

Dispara uma consulta nova de margem consignável no Crédito do Trabalhador. O `POST` consulta; o `GET` devolve o histórico de consultas já feitas, útil para não repetir chamada dentro da janela de cache.

| Parâmetro | Local | Obrigatório | Como preencher | Exemplo |
|---|---|---|---|---|
| `personId` | query | Condicional | Identificador do tomador cadastrado. **Forma preferida** — identificador estável e sem dado pessoal na query string. | `11111111-1111-1111-1111-111111111111` |
| `registrationNumber` | query | Condicional | CPF do trabalhador. Use este quando o tomador **ainda não** foi cadastrado — é o que permite consultar margem logo depois da autorização. | `00000000000` |
| `creditProductId` | query | Não (envie) | Produto contratado da consulta. Sem ele a margem volta sem o recorte do produto, e a simulação pode ofertar fora da faixa. | `33333333-3333-3333-3333-333333333333` |

```bash
curl --location --request POST '{{baseUrl}}/v1/DataprevEmployee/FreeMarginQuery?personId=11111111-1111-1111-1111-111111111111&creditProductId=33333333-3333-3333-3333-333333333333' \
  --header 'Authorization: Bearer {{token}}' \
  --header 'Accept: application/json'
```

O retorno traz o vínculo ativo do trabalhador e a margem consignável livre. É dele que saem `employeeCode`, o CNPJ do empregador e o valor de margem usados nas etapas seguintes. **Guarde esses valores**: eles reaparecem na garantia da operação.

Exige autorização `Approved` para o CPF. Se a consulta responder que não há autorização válida, volte a [2.1 Autorização de margem](/guia/consignado-privado-cadastro-autorizacao) — inclusive quando você acredita que a autorização existe: é essa recusa, e não um cálculo de prazo do seu lado, que decide se ela ainda vale.

### Passo 2 — Simular: dois caminhos

A partir daqui existem **dois caminhos**, e a escolha é sua. Eles não são etapas em sequência: são alternativas.

| | **Caminho A — Simulação de ofertas** | **Caminho B — Simulação por amortização** |
|---|---|---|
| Pergunta | *Quais condições cabem na margem?* | *Como fica o plano desta condição?* |
| Rota | `POST /v1/Amortization/DataprevEmployeeOffers` | `POST /v1/Amortization` |
| Entrada | CPF, vínculo e uma faixa | produto, valor, taxa e prazo exatos |
| Saída | lista de ofertas elegíveis | um plano de pagamento, parcela a parcela |
| Passa pela proposta ao empregador? | Sim | Não |
| Quando usar | vitrine para o trabalhador escolher | condição já definida |

Nada impede usar os dois: ofertas para o trabalhador escolher, amortização depois para conferir o plano completo da opção escolhida.

### Passo 2A — Caminho A: simulação de ofertas

```http
POST /v1/Amortization/DataprevEmployeeOffers
```

> **Fora da Referência curada:** `creditProductId`, `employerRegistrationNumber`, `productIds`, `productCategory`, `calculateByValue`, `requestedValue`, `rangePaymentAmounts`, `rangeNumberOfPayments`, `rateMode`, `interestRate`, `offerRequestId`, `proposalNumber`, `installmentCount`, `installmentAmountInCents`, `loanAmountInCents`, `releasedAmountInCents`, `iofAmountInCents`, `hasWarranty`, `fgtsBalanceInCents`, `fgtsRescissionPenaltyInCents`, `rescissionBenefitPercentage` — as rotas do Crédito do Trabalhador não são publicadas na [Referência de API](/referencia/creditapi). As tabelas desta página são a única fonte campo a campo desses payloads, e o `uy3_montar_requisicao` do MCP não consegue conferi-los.

Gera as ofertas dos produtos habilitados que caibam na margem. As rotas de oferta do Crédito do Trabalhador listam **apenas produtos com modelo de cálculo Price** — é por isso que o consignado privado não tem modelo de cálculo próprio.

| Campo | Tipo | Obrigatório | Como preencher | Exemplo |
|---|---|---|---|---|
| `registrationNumber` | string | Sim | CPF do trabalhador. | `00000000000` |
| `employerRegistrationNumber` | string | Não (envie) | CNPJ do empregador retornado na consulta de margem. Sem ele a simulação não sabe qual vínculo usar. | `00000000000000` |
| `employeeCode` | string | Não (envie) | Matrícula do trabalhador no empregador, como veio da consulta de margem. | `MAT-000123` |
| `productIds` | lista de uuid | Não | Restringe a simulação a produtos específicos. Omita para simular todos os habilitados. | `["3333...3333"]` |
| `productCategory` | string | Não | Restringe por categoria de produto contratado. | `CONSIGNADO PRIVADO` |
| `calculateByValue` | enum | Não (envie) | Base do cálculo: `Gross` (valor bruto), `Liquid` (valor líquido liberado) ou `Payment` (valor da parcela). | `Liquid` |
| `requestedValue` | `inteiro em centavos` | Condicional | Valor pretendido. Obrigatório quando `calculateByValue` é `Gross` ou `Liquid`. | `500000` (= R$ 5.000,00) |
| `rangePaymentAmounts` | lista de `inteiro em centavos` | Condicional | Faixa de valores de parcela. Use com `calculateByValue = Payment`. | `[30000, 50000]` |
| `rangeNumberOfPayments` | lista de inteiro | Não | Faixa de prazos a simular, em número de parcelas. | `[12, 24, 36]` |
| `rateMode` | enum | Não | `MinimumRate` ou `MaximumRate` — qual extremo da faixa de taxa do produto usar. | `MinimumRate` |
| `interestRate` | número | Não | Taxa mensal específica, em porcentagem, dentro da faixa do produto. | `2.15` |

```bash
curl --location --request POST '{{baseUrl}}/v1/Amortization/DataprevEmployeeOffers' \
  --header 'Authorization: Bearer {{token}}' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
    "registrationNumber": "00000000000",
    "employerRegistrationNumber": "00000000000000",
    "employeeCode": "MAT-000123",
    "rangeNumberOfPayments": [12, 24, 36],
    "rateMode": "MinimumRate"
  }'
```

Cada item do retorno é uma oferta com prazo, parcela, taxa mensal e anual, CET e IOF, e traz o `offerRequestId` que a proposta do passo 3 referencia.

#### Simulação abaixo da margem total

Por padrão a simulação usa a **margem total disponível** do trabalhador: ela responde "qual é o máximo que cabe". Isso não serve para o caso mais comum na prática, que é o trabalhador querer um valor menor do que o máximo.

Para simular **abaixo da margem total**, informe o valor pretendido junto da base de cálculo:

| O que você quer | Envie |
|---|---|
| Um valor líquido específico | `calculateByValue: "Liquid"` + `requestedValue` |
| Um valor bruto específico | `calculateByValue: "Gross"` + `requestedValue` |
| Uma parcela específica (ou faixa de parcela) | `calculateByValue: "Payment"` + `rangePaymentAmounts` |

```bash
curl --location --request POST '{{baseUrl}}/v1/Amortization/DataprevEmployeeOffers' \
  --header 'Authorization: Bearer {{token}}' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
    "registrationNumber": "00000000000",
    "employerRegistrationNumber": "00000000000000",
    "employeeCode": "MAT-000123",
    "calculateByValue": "Liquid",
    "requestedValue": 300000,
    "rangeNumberOfPayments": [12, 24, 36],
    "rateMode": "MinimumRate"
  }'
```

No exemplo, o trabalhador tem margem para mais, mas quer **R$ 3.000,00 líquidos** (`300000` em centavos). As ofertas voltam dimensionadas para esse valor, e não para o teto da margem.

> **Por que isso importa.** Simular sempre pelo teto empurra o trabalhador para o valor máximo e para a parcela máxima. Simular pelo valor que ele pediu é o que permite apresentar a oferta que ele de fato quer contratar — e reduz desistência entre a proposta e a assinatura.

O valor pedido continua limitado pela margem: pedir mais do que cabe devolve simulação sem resultado. Ver [5. Erros e troubleshooting](/guia/consignado-privado-erros).

#### Data da primeira parcela

```http
POST /v1/DataprevEmployee/FirstPaymentDate
```

| Parâmetro | Local | Obrigatório | Como preencher | Exemplo |
|---|---|---|---|---|
| `productId` | query | Sim | Produto contratado. O dia de repasse dele determina o vencimento. | `33333333-3333-3333-3333-333333333333` |
| `startDate` | query | Sim | Data base do contrato, no formato `data civil`. | `2026-08-25` |

Use o retorno em `firstPaymentDate`, na criação da operação. Não calcule a data por conta própria: o dia de repasse é parâmetro do produto.

### Passo 2B — Caminho B: simulação por amortização

```http
POST /v1/Amortization
GET  /v1/Amortization/{id}
POST /v1/Amortization/Batch
```

Use quando a condição **já está definida** — tabela negociada com o parceiro, recontratação, ou o trabalhador que já escolheu valor, taxa e prazo. Em vez de uma lista de ofertas, o retorno é **um plano de pagamento completo**: parcela a parcela, com CET, IOF e custo de emissão.

O objeto de cálculo é o **mesmo** enviado na criação da operação — as tabelas da seção **Como preencher** valem para os dois. Isso é uma vantagem prática: o que você simulou é o que você cria, sem tradução.

A diferença está no **envelope**: aqui o objeto de cálculo vai dentro de `amortization`, e a raiz exige `productId` e `legalPerson`. Na criação da operação, `productId` e `personId` é que ficam na raiz.

```bash
curl --location --request POST '{{baseUrl}}/v1/Amortization' \
  --header 'Authorization: Bearer {{token}}' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
    "productId": "33333333-3333-3333-3333-333333333333",
    "legalPerson": false,
    "amortization": {
      "amortizationType": "price",
      "requestedAmount": 500000,
      "apr": 2.15,
      "numberOfPayments": 24,
      "firstPaymentDate": "2026-10-05T00:00:00Z",
      "startDate": "2026-08-25T00:00:00Z",
      "calculationType": "V360DiasCorridos",
      "calculateByValueType": "Liquid",
      "dueDateOnBusinessDays": true,
      "paymentPeriodicity": { "every": 1, "periodicity": "Monthly" }
    }
  }'
```

Os três da raiz — `productId`, `legalPerson` e `amortization` — são **obrigatórios**. No consignado privado o tomador é pessoa física, então `legalPerson` é `false`.

`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 montar uma vitrine própria de prazos.

> A parcela resultante continua tendo de caber na margem apurada no passo 1. O caminho B não passa pela proposta ao empregador, mas a averbação, mais adiante, valida a parcela do mesmo jeito.

### Passo 3 — Enviar a proposta ao empregador (caminho A)

```http
POST /v1/DataprevEmployee/OfferProposals
POST /v1/DataprevEmployee/OfferProposalsWarranty
```

`OfferProposals` envia **uma** proposta sem reforço de garantia FGTS. `OfferProposalsWarranty` recebe uma **lista** de propostas e aceita o bloco de reforço FGTS em cada item — use esta quando o produto contratado habilita saldo e multa rescisória do FGTS como reforço da margem.

| Campo | Tipo | Obrigatório | Como preencher | Exemplo |
|---|---|---|---|---|
| `offerRequestId` | inteiro | Sim | Identificador da solicitação de oferta devolvido na simulação. É o que amarra a proposta à oferta simulada. | `9876543` |
| `expirationDate` | `data e hora` | Sim | Validade da proposta, em UTC. Depois dela o empregador não consegue mais aceitar. | `2026-09-05T23:59:59Z` |
| `proposalNumber` | string | Não (envie) | Seu número de controle da proposta. Reaparece na garantia da operação — é o que liga as duas pontas. | `PROP-000123` |
| `installmentCount` | inteiro | Não (envie) | Número de parcelas da oferta escolhida. | `24` |
| `installmentAmountInCents` | `inteiro em centavos` | Não (envie) | Valor da parcela. Precisa caber na margem livre. | `28500` (= R$ 285,00) |
| `loanAmountInCents` | `inteiro em centavos` | Não (envie) | Valor bruto contratado. | `500000` |
| `releasedAmountInCents` | `inteiro em centavos` | Não (envie) | Valor líquido liberado ao trabalhador. | `487500` |
| `iofAmountInCents` | `inteiro em centavos` | Não | IOF. | `12500` |
| `monthlyInterestRate` / `yearlyInterestRate` | número | Não (envie) | Taxa de juros mensal e anual, em porcentagem. | `2.15` / `29.07` |
| `monthlyCet` / `yearlyCet` | número | Não | CET mensal e anual, em porcentagem. | `2.42` / `33.25` |
| `contacts[].type` | enum | Sim (no item) | Tipo do contato do trabalhador para a comunicação da proposta. | `Celular` |
| `contacts[].contact` | string | Sim (no item) | O contato em si, no formato do tipo. | `11900000000` |
| `warranty.hasWarranty` | booleano | Não | Só em `OfferProposalsWarranty`. `true` para incluir reforço FGTS. | `true` |
| `warranty.fgtsBalanceInCents` | `inteiro em centavos` | Condicional | Saldo FGTS oferecido como reforço. Exigido quando `hasWarranty` é `true`. | `150000` |
| `warranty.fgtsRescissionPenaltyInCents` | `inteiro em centavos` | Condicional | Multa rescisória FGTS oferecida como reforço. | `60000` |
| `warranty.rescissionBenefitPercentage` | número | Não | Percentual da multa rescisória considerado no reforço, em porcentagem. | `40.0` |

```bash
curl --location --request POST '{{baseUrl}}/v1/DataprevEmployee/OfferProposalsWarranty' \
  --header 'Authorization: Bearer {{token}}' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '[
    {
      "offerRequestId": 9876543,
      "proposalNumber": "PROP-000123",
      "expirationDate": "2026-09-05T23:59:59Z",
      "installmentCount": 24,
      "installmentAmountInCents": 28500,
      "loanAmountInCents": 500000,
      "releasedAmountInCents": 487500,
      "iofAmountInCents": 12500,
      "monthlyInterestRate": 2.15,
      "yearlyInterestRate": 29.07,
      "contacts": [ { "type": "Celular", "contact": "11900000000" } ],
      "warranty": {
        "hasWarranty": true,
        "fgtsBalanceInCents": 150000,
        "fgtsRescissionPenaltyInCents": 60000,
        "rescissionBenefitPercentage": 40.0
      }
    }
  ]'
```

No fluxo de **leilão CTPS**, quando o empregador abre o link de contratação, revalide a oferta antes de criar a operação:

```http
GET /v1/AuctionCTPS/OfferProposals/{id}/simulation
```

A revalidação confere o prazo de expiração, re-simula e valida a parcela contra a margem **atual**. Se a margem caiu desde a proposta, é aqui que isso aparece — antes de a operação existir.

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

```http
POST /v1/CreditNote
```

| Parâmetro | Local | Obrigatório | Como preencher | Exemplo |
|---|---|---|---|---|
| `updateStartDate` | query | Não | `true` para a API reposicionar a data de início no dia da criação. | `true` |
| `returnValue` | query | Não | `true` para o retorno vir com a operação completa em vez de apenas o identificador. | `true` |

Corpo: ver **Como preencher** abaixo. A operação nasce em `Draft` (rascunho) ou já em `ComplianceApproval`, conforme a configuração do produto contratado.

### Passo 5 — Garantia e documentos

```http
PUT /v1/CreditNote/{id}/warranty
PUT /v1/CreditNote/{id}/upload
PUT /v1/CreditNote/{id}
```

Tanto a garantia quanto os documentos podem ir **no corpo da criação** (coleções `warranty` e `uploads`) **ou** ser anexados depois, pelas rotas acima. Ver a seção **Garantia e documentos: `warranty` e `uploads`** em Como preencher.

`PUT /v1/CreditNote/{id}` corrige atributos da operação — permitido apenas nos status `Draft`, `Revision`, `Disapproved` e `Error`.

### Passo 6 — Enviar para aprovação

```http
POST /v1/CreditNote/{id}/submitapproval
```

| Parâmetro | Local | Obrigatório | Como preencher | Exemplo |
|---|---|---|---|---|
| `id` | rota | Sim | Identificador da operação criada no passo 4. | `55555555-5555-5555-5555-555555555555` |
| `updateStartDate` | query | Não | `true` para reposicionar a data de início no envio. | `false` |

```bash
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 é recusado sem ao menos uma garantia informada — o caso do consignado privado, em que o produto exige lastro.

### Passo 7 — Assinatura eletrônica

```http
GET /v1/CreditNote/{id}/SignUrl
```

Devolve as URLs de assinatura para você entregar ao signatário. 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 8 — Averbação da margem

A averbação **não é uma rota que você chama**: é uma etapa da esteira. Depois da aprovação de crédito, a operação assume o status de garantia (`Warranty` ou `MarginReserveApproval`) e aguarda a confirmação da reserva de margem junto ao empregador. Você acompanha por consulta — ver [4. Consultas e acompanhamento](/guia/consignado-privado-consultas).

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

```http
POST /v1/CreditNote/{id}/doneWarrantyRevision
```

### Passo 9 — Cancelar, excluir ou restaurar

```http
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 tratamento da reserva de margem faz parte do processamento do cancelamento pela esteira. Não há flag para pedir ou dispensar o estorno da margem.

| Campo | Tipo | Obrigatório | Como preencher | Exemplo |
|---|---|---|---|---|
| `message` | corpo | Não (envie) | Motivo do cancelamento, em texto. Fica no histórico da operação e é o que a mesa lê. | `Desistencia do tomador` |

```bash
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 tomador" }'
```

**Acompanhe até `Canceled`.** O cancelamento não é instantâneo: se a operação já estava averbada, a liberação da margem faz parte do processamento e o status é o sinal de que terminou. Só contrate de novo para o mesmo trabalhador depois de a operação estar em `Canceled` — antes disso a margem pode ainda estar comprometida 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`

| Campo | Tipo | Obrigatório | Como preencher | Exemplo |
|---|---|---|---|---|
| `productId` | string (uuid) | Sim | Produto contratado de consignado privado, fornecido pela UY3. Define o modelo de cálculo e as faixas de taxa e prazo. | `33333333-3333-3333-3333-333333333333` |
| `personId` | string (uuid) | Sim | O tomador. Precisa estar vinculado ao seu usuário/correspondente. | `11111111-1111-1111-1111-111111111111` |
| `amortization` | objeto | Sim | Objeto de cálculo. Ver a tabela do modelo Price abaixo. | ver abaixo |
| `warranty` | lista de objetos | Sim na prática | Garantia de margem. Sem ela o envio para aprovação é recusado. | ver abaixo |
| `uploads` | lista de objetos | Não (envie) | Documentos da operação. Ver a seção sobre `warranty` e `uploads` abaixo. | ver abaixo |
| `liquidationType` | enum | Sim para este produto | Use `EletronicTransfer`. `Invoice` (boleto) não se aplica ao consignado privado. | `EletronicTransfer` |
| `bankAccountId` | string (uuid) | Sim para este produto | Conta de destino do valor liberado. | `22222222-2222-2222-2222-222222222222` |
| `emissionDate` | `data e hora` | Não | Data de emissão do instrumento. Omita para usar a data da criação. | `2026-08-25T00:00:00Z` |
| `dataprevOfferCTPSRequestId` | inteiro | Condicional | `offerRequestId` da oferta de leilão CTPS de origem. Preencha **somente** quando a operação nasce do leilão. | `9876543` |
| `newPersonAndAccount` | objeto | Não | Cria tomador e conta na própria criação, dispensando os cadastros 2.2 e 2.3. Alternativa a `personId` + `bankAccountId`. | ver [2.3 Cadastro do tomador](/guia/consignado-privado-cadastro-pessoa) |
| `observations` | string | Não | Observação livre para a mesa de crédito. | `Proposta PROP-000123` |
| `insurance` | booleano | Não | `true` quando o produto contratado embute seguro prestamista. | `false` |
| `isByxCreation` | booleano | Não | `true` quando a criação vem do canal parceiro BYX. | `false` |

### Objeto de cálculo — modelo Price (o do consignado privado)

O `amortizationType` enviado **precisa coincidir** com o modelo de cálculo do produto contratado. Para consignado privado, é `price` (ou `sac`, quando o produto for de amortização constante). O valor legado `consignado` não é aceito.

| Campo | Tipo | Obrigatório | Como preencher | Exemplo |
|---|---|---|---|---|
| `amortizationType` | string | Sim | Discriminador do modelo. `price` ou `sac`, conforme o produto. Comparação sem distinção de caixa. | `price` |
| `requestedAmount` | `inteiro em centavos` | Sim | Valor contratado. **Não tem sufixo `InCents` e ainda assim é em centavos** — a confusão mais comum do módulo. | `500000` (= R$ 5.000,00) |
| `apr` | número | Sim | Taxa de juros **mensal**, em porcentagem. Precisa estar na faixa do produto e ser maior que zero. | `2.15` |
| `numberOfPayments` | inteiro | Sim | Número de parcelas. Precisa estar na faixa de prazo do produto. | `24` |
| `firstPaymentDate` | `data e hora` | Sim | Data da primeira parcela. Use o retorno de `POST /v1/DataprevEmployee/FirstPaymentDate`. | `2026-10-05T00:00:00Z` |
| `calculationType` | enum | Sim | Critério de contagem de dias: `V252DiasUteis`, `V252MesesX21`, `V360DiasCorridos`, `V360Meses`, `V365DiasCorridos`, `V365Meses` ou `Irregular`. Siga o critério do produto contratado. **Não é `Price`/`SAC`** — esse é o `amortizationType`. | `V360DiasCorridos` |
| `paymentPeriodicity` | objeto | Sim | **Precisa ser** `{ "every": 1, "periodicity": "Monthly" }`. Qualquer outro valor é recusado no consignado privado. | ver exemplo |
| `startDate` | `data e hora` | Não (envie) | Data base de cálculo do contrato. | `2026-08-25T00:00:00Z` |
| `calculateByValueType` | enum | Não | `Gross`, `Liquid` ou `Payment` — de qual valor o cálculo parte. Suportado por Price e SAC. | `Liquid` |
| `financeTaxExempted` | booleano | Não | `true` para não financiar o IOF. | `false` |
| `numberOfInterestPayments` | inteiro | Não | Parcelas somente de juros antes da amortização. | `0` |
| `dueDateOnBusinessDays` | booleano | Não | `true` para deslocar vencimentos que caiam em dia não útil. | `true` |
| `includePaymentFixedCosts` | booleano | Não | `true` para embutir custos fixos na parcela. | `false` |

**Não envie** neste produto: `paymentDay`, `absAmortizationInMonths`, `absInterestInMonths`, `daysInYear`, `periodicity`, `termInMonths`, `paymentMonth`, `indexer`, `indexerValue`, `fiduciaryGuarantee`. Esses campos pertencem a outros modelos de cálculo e indicam objeto errado.

### Garantia de margem

| Campo | Tipo | Obrigatório | Como preencher | Exemplo |
|---|---|---|---|---|
| `warrantyType` | enum | Sim | `DataprevEmployee` para consignado novo; `DataprevEmployeeRefinance` quando a operação substitui contrato consignado vigente. | `DataprevEmployee` |
| `dataprev_EmployeeCode` | string | Sim | Matrícula do trabalhador no empregador, como veio da consulta de margem. | `MAT-000123` |
| `dataprev_EmployerRegistrationCode` | inteiro | Sim | Código do registro do empregador na averbadora, devolvido na consulta de margem. | `100234` |
| `dataprev_EmployerName` | string | Sim | Razão social do empregador. | `EMPRESA EXEMPLO LTDA` |
| `dataprev_EmployerRegistrationNumber` | string | Sim | CNPJ do empregador, só dígitos. | `00000000000000` |
| `dataprev_DiscountStartPeriod` | `competência` | Sim | Competência do **primeiro desconto em folha**, com dia, mês e ano — use o primeiro dia do mês da competência. Escrever só `AAAA-MM` não é aceito. Ver [Convenções de dados](/guia/convencoes-de-dados). | `2026-10-01` |
| `dataprev_EmployeeAdmissionDate` | `data e hora` | Sim | Data de admissão do trabalhador. Compõe a identificação do vínculo. | `2022-03-01T00:00:00Z` |
| `totalValue` | `decimal em reais` | Sim | Valor total garantido pela margem. **Em reais, não em centavos** — ao contrário de `requestedAmount`, no mesmo corpo. | `6840.00` |
| `dataprev_OriginalMargin` | `decimal em reais` | Não (envie) | Margem livre apurada na consulta. Registra a base da decisão. | `1200.00` |
| `dataprev_EmployeePositionCBOCode` | inteiro | Não (envie) | Código CBO do cargo do trabalhador. | `411005` |
| `dataprev_CtpsDigitalAuthorizationNumber` | string | Não (envie) | Número da autorização da CTPS Digital. Amarra a operação ao consentimento. | `AUT-000123` |
| `dataprev_ProposalNumber` | string | Não (envie) | `proposalNumber` enviado na proposta. Amarra a operação à proposta aceita. | `PROP-000123` |
| `dataprev_HasWarranty` | booleano | Não | `true` quando há reforço de garantia FGTS. | `true` |
| `dataprev_WarrantyFgtsBalanceInCents` | `inteiro em centavos` | Condicional | Saldo FGTS de reforço. Exigido quando `dataprev_HasWarranty` é `true`. | `150000` |
| `dataprev_WarrantyFgtsRescissionPenaltyInCents` | `inteiro em centavos` | Condicional | Multa rescisória FGTS de reforço. | `60000` |
| `dataprev_WarrantyRescissionBenefitPercentage` | número | Não | Percentual da multa rescisória considerado, em porcentagem. | `40.0` |
| `admissionDate` | `data e hora` | Não | Data de admissão no nível genérico da garantia. Mantenha igual a `dataprev_EmployeeAdmissionDate`. | `2022-03-01T00:00:00Z` |
| `employeeCode` | string | Não | Matrícula no nível genérico da garantia. Mantenha igual a `dataprev_EmployeeCode`. | `MAT-000123` |

### Garantia e documentos: `warranty` e `uploads`

O `POST /v1/CreditNote` aceita documento em **duas coleções diferentes**, e elas não são intercambiáveis:

| Coleção | O que vai nela | Quando usar |
|---|---|---|
| `warranty` | Os **dados** da garantia de margem — vínculo, empregador, competência, valor. Não é arquivo. | Sempre. É o lastro da operação. |
| `uploads` | Os **arquivos** da operação — termo de autorização, instrumento assinado, comprovantes. | Sempre que houver documento a anexar. |

| Campo | Tipo | Obrigatório | Como preencher | Exemplo |
|---|---|---|---|---|
| `uploads[].fileType` | enum | Sim (no item) | Tipo do documento. `Authorization` para o termo de autorização de margem; `SignedContract` para o instrumento já assinado; `Others` para o resto. | `Authorization` |
| `uploads[].fileName` | string | Sim (no item) | Nome do arquivo, com extensão. | `autorizacao-margem.pdf` |
| `uploads[].displayName` | string | Não (envie) | Rótulo exibido na mesa. Sem ele a mesa vê só o nome do arquivo. | `Autorizacao de margem` |
| `uploads[].documentDate` | `data e hora` | Não | Data do documento. | `2026-08-25T00:00:00Z` |

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

Corpo completo, com as três coleções — `amortization`, `warranty` e `uploads`:

```bash
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": "Proposta PROP-000123",
    "amortization": {
      "amortizationType": "price",
      "requestedAmount": 500000,
      "apr": 2.15,
      "numberOfPayments": 24,
      "firstPaymentDate": "2026-10-05T00:00:00Z",
      "startDate": "2026-08-25T00:00:00Z",
      "calculationType": "V360DiasCorridos",
      "calculateByValueType": "Liquid",
      "dueDateOnBusinessDays": true,
      "paymentPeriodicity": { "every": 1, "periodicity": "Monthly" }
    },
    "warranty": [
      {
        "warrantyType": "DataprevEmployee",
        "dataprev_EmployeeCode": "MAT-000123",
        "dataprev_EmployerRegistrationCode": 100234,
        "dataprev_EmployerName": "EMPRESA EXEMPLO LTDA",
        "dataprev_EmployerRegistrationNumber": "00000000000000",
        "dataprev_DiscountStartPeriod": "2026-10-01",
        "dataprev_EmployeeAdmissionDate": "2022-03-01T00:00:00Z",
        "dataprev_OriginalMargin": 1200.00,
        "dataprev_EmployeePositionCBOCode": 411005,
        "dataprev_CtpsDigitalAuthorizationNumber": "AUT-000123",
        "dataprev_ProposalNumber": "PROP-000123",
        "dataprev_HasWarranty": true,
        "dataprev_WarrantyFgtsBalanceInCents": 150000,
        "dataprev_WarrantyFgtsRescissionPenaltyInCents": 60000,
        "totalValue": 6840.00
      }
    ],
    "uploads": [
      {
        "fileType": "Authorization",
        "fileName": "autorizacao-margem.pdf",
        "displayName": "Autorizacao de margem",
        "documentDate": "2026-08-25T00:00:00Z"
      }
    ]
  }'
```

Para enviar o instrumento **já assinado** junto da criação, acrescente um item a `uploads`:

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

## Exemplo de response

```json
{
  "id": "55555555-5555-5555-5555-555555555555",
  "creditNoteNo": "2026/000123",
  "status": "Draft",
  "productId": "33333333-3333-3333-3333-333333333333",
  "personId": "11111111-1111-1111-1111-111111111111",
  "amortization": {
    "amortizationType": "price",
    "requestedAmount": 500000,
    "apr": 2.15,
    "numberOfPayments": 24,
    "firstPaymentDate": "2026-10-05T00:00:00Z",
    "paymentPeriodicity": { "every": 1, "periodicity": "Monthly" }
  },
  "warranty": [ { "warrantyType": "DataprevEmployee", "totalValue": 6840.00 } ],
  "uploads": [ { "fileType": "Authorization", "fileName": "autorizacao-margem.pdf" } ]
}
```

Guarde o `id`: é ele que identifica a operação em todas as etapas seguintes e nas consultas. Repare que `requestedAmount` volta em centavos e `totalValue` em reais — a mesma regra do request.

## Códigos de retorno

| Código | Significado | O que fazer |
|---|---|---|
| `200` | Etapa concluída. | Siga para a etapa seguinte com o `id` devolvido. |
| `400` | Validação de negócio ou de contrato: periodicidade diferente de mensal, taxa fora da faixa, prazo fora da faixa, modelo de cálculo divergente do produto, parcela acima da margem. | Ver [5. Erros e troubleshooting](/guia/consignado-privado-erros). |
| `401` | Token ausente, expirado ou inválido. | Renove o token — ver [Autenticação](/guia/autenticacao). |
| `403` | Sem permissão para a ação, ou tomador não vinculado ao usuário/correspondente. | Ver [5. Erros e troubleshooting](/guia/consignado-privado-erros). |
| `404` | Operação, tomador, conta ou produto inexistente. | Confira os identificadores das etapas anteriores. |
| `409` | Ação inválida para o status atual da operação. | Consulte o status antes de repetir — ver [4. Consultas e acompanhamento](/guia/consignado-privado-consultas). |

## O que acontece depois

Depois do `submitapproval`, a operação percorre a esteira: análise de crédito, compliance, **garantia (averbação da margem)**, 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.

Cada uma dessas transições é um evento observável. O ciclo completo, evento por evento, está em [4.1 Eventos e notificações](/guia/consignado-privado-eventos).

## Antes desta etapa

- [2.3 Cadastro do tomador](/guia/consignado-privado-cadastro-pessoa) — o `personId` e o `bankAccountId` consumidos aqui.
- [2. Pré-requisitos e cadastros](/guia/consignado-privado-cadastros) — índice dos três cadastros e a ordem entre eles.

## Próxima etapa

- [4. Consultas e acompanhamento](/guia/consignado-privado-consultas) — status, parcelas e comprovante de transferência.
- [4.1 Eventos e notificações](/guia/consignado-privado-eventos) — o ciclo de vida completo, evento por evento.
- [5. Erros e troubleshooting](/guia/consignado-privado-erros) — quando alguma etapa acima falhar.

## Downloads

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

---

## /guia/consignado-privado-consultas — 4. Consultas e acompanhamento

# Consignado privado — Consultas e acompanhamento

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 e de valor: [Convenções de dados](/guia/convencoes-de-dados).

## O que é

Depois do envio para aprovação a operação sai das suas mãos e percorre a esteira da UY3. Esta página reúne as consultas que respondem "onde está a operação, o que falta e o que já foi pago".

O acompanhamento do consignado privado é **por consulta**: você pergunta, a API responde com o status atual. O que cada transição de status significa, e o que fazer em cada uma, está em [4.1 Eventos e notificações](/guia/consignado-privado-eventos).

## Quando usar

- Entre o `submitapproval` e a liquidação, para saber em que etapa a operação está.
- Depois da liquidação, para obter o comprovante de transferência.
- Ao longo do contrato, para consultar o cronograma de parcelas e o saldo.
- Em rotina de reconciliação diária ou semanal da sua carteira.

## Pré-requisitos

- `id` da operação — devolvido em [3. Operação](/guia/consignado-privado-operacao).
- Token válido — ver [Autenticação](/guia/autenticacao).

## Endpoints de consulta

### Status e dados da operação

```http
GET /v1/CreditNote/{id}
GET /v1/CreditNote
```

`GET /v1/CreditNote/{id}` devolve a operação completa: status, cálculo, garantia, documentos, assinaturas e cronograma. É a consulta que responde "e agora?".

`GET /v1/CreditNote` lista operações com filtros. Os que interessam ao acompanhamento do consignado privado:

| Parâmetro | Local | Obrigatório | Como preencher | Exemplo |
|---|---|---|---|---|
| `status` | query | Não | Status a filtrar. Combine com paginação para varrer a fila de uma etapa. | `Warranty` |
| `personId` | query | Não | Todas as operações de um tomador. | `11111111-1111-1111-1111-111111111111` |
| `productId` | query | Não | Todas as operações de um produto contratado. | `33333333-3333-3333-3333-333333333333` |
| `creditNoteNo` | query | Não | Número da operação, quando você tem o número e não o `id`. | `2026/000123` |
| `initialDate` / `finalDate` | `data civil` (query) | Não | Janela de criação. Use para varredura incremental. | `2026-08-01` / `2026-08-31` |
| `initialPaymentDate` / `finalPaymentDate` | `data civil` (query) | Não | Janela de vencimento de parcela. | `2026-10-01` / `2026-10-31` |
| `minValue` / `maxValue` | `inteiro em centavos` (query) | Não | Faixa de valor contratado. | `100000` / `2000000` |
| `isDeleted` | query | Não | `true` para incluir operações excluídas logicamente. | `false` |
| `page` / `size` | query | Não | Paginação. Mantenha `size` moderado em varredura. | `1` / `50` |
| `orderBy` | query | Não | Campo de ordenação. | `createDate desc` |

```bash
curl --location --request GET '{{baseUrl}}/v1/CreditNote/55555555-5555-5555-5555-555555555555' \
  --header 'Authorization: Bearer {{token}}' \
  --header 'Accept: application/json'
```

### Assinatura

```http
GET /v1/CreditNote/{id}/SignUrl
```

Devolve as URLs de coleta de assinatura, para entregar ao tomador. Disponíveis a partir do status `Signatures`. O andamento da coleta é lido no próprio `GET /v1/CreditNote/{id}`.

### Liquidação e comprovante

```http
GET /v1/CreditNote/{id}/transferReceipt
```

Devolve o comprovante da transferência (Pix ou TED) feita ao tomador. Disponível a partir da liquidação.

### Cronograma de parcelas e quitação

```http
POST /v1/CreditNote/{id}/DuePaymentSchedule
GET  /v1/CreditNote/{id}/LiquidationScheduleCreditNote
```

`DuePaymentSchedule` calcula o calendário de quitação da operação — o que o tomador deve para liquidar antecipadamente em uma data.

### Consultas dos cadastros

```http
GET /v1/DataprevEmployee/AuthorizationMargin
GET /v1/DataprevEmployee/FreeMarginQuery
GET /v1/NaturalPerson/{id}
```

A listagem de autorizações confirma se o consentimento do trabalhador está `Approved` — é a consulta a fazer **antes de cada consulta de margem**, e não uma vez só por trabalhador. Ver [2.1 Autorização de margem](/guia/consignado-privado-cadastro-autorizacao).

O histórico de consultas de margem mostra as margens já apuradas, sem gerar consulta nova.

### Extração em lote

```http
GET /v1/CreditNote/Export/excel
GET /v1/CreditNote/related-operations
```

`Export/excel` exporta a carteira filtrada em planilha — use para conciliação periódica, não para acompanhamento de operação individual.

### Depois do encerramento

```http
POST /v1/DataprevEmployee/SendOperationFundOutstandingBalance
POST /v1/DataprevEmployee/SendRetroactiveOutstandingBalance
```

Envio do saldo devedor de operações **encerradas** ao Crédito do Trabalhador, uma operação por vez. Exige permissão de edição de operação e valida que a operação pertence ao ambiente autenticado e está encerrada. Valores em `inteiro em centavos`. `SendRetroactiveOutstandingBalance` dispara o envio retroativo de um lote e tem parâmetro `limit` de query — é feito em janela de baixo movimento por causa do limite de chamadas compartilhado com o leilão.

## Webhooks

O acompanhamento hoje é por consulta. O ciclo de vida completo — quais eventos existem, quando cada um acontece, quais exigem ação sua e o padrão de varredura recomendado — está na página dedicada:

**→ [4.1 Eventos e notificações](/guia/consignado-privado-eventos)**

## O que acontece depois

Com a operação em `Finished`, o ciclo de integração se encerra: as parcelas passam a ser descontadas em folha pelo empregador e amortizam o contrato. O que resta do seu lado é a conciliação periódica e, quando aplicável, o envio de saldo devedor.

## Antes desta etapa

- [3. Operação](/guia/consignado-privado-operacao) — é de lá que vem o `id` consultado aqui.

## Próxima etapa

- [4.1 Eventos e notificações](/guia/consignado-privado-eventos) — o significado de cada status e o que fazer em cada um.
- [5. Erros e troubleshooting](/guia/consignado-privado-erros) — quando uma consulta revelar reprovação, revisão ou erro.

## Downloads

- Contexto para LLM deste módulo: [llms-consignado-privado.txt](/downloads/llms-consignado-privado.txt)
- Collection Postman do módulo: [uy3-consignado-privado.postman_collection.json](/downloads/uy3-consignado-privado.postman_collection.json)
- Documentação consolidada para LLM: [llms.txt](/downloads/llms.txt)

---

## /guia/consignado-privado-eventos — 4.1 Eventos e notificações

# Consignado privado — Eventos e notificações

Dado pessoal ou sensível deve ser **mascarado** em outputs, logs e exemplos. Todos os valores desta página são fictícios.

## O que é

O ciclo de vida completo de uma operação de consignado privado, evento por evento: o que acontece, quando, o que aquilo significa e o que exige ação sua.

Esta página existe para que você **não descubra os eventos por tentativa e erro**. Depois do `submitapproval`, a operação percorre a esteira sozinha — e cada parada dela é um estado que você precisa saber ler.

> **O que é um "evento" aqui.** É uma **transição de status** da operação. Não há, hoje, um canal de notificação que empurre esses eventos para o seu sistema: você os observa consultando. A seção **Webhook de saída** no fim da página trata disso explicitamente.

## Quando usar

- Ao desenhar a máquina de estados do seu lado, antes de escrever o acompanhamento.
- Quando uma operação parou em um status e você não sabe se deve agir ou esperar.
- Ao definir alertas operacionais: quais estados são normais e quais pedem intervenção.

## Pré-requisitos

- `id` da operação — devolvido em [3. Operação](/guia/consignado-privado-operacao).
- Token válido — ver [Autenticação](/guia/autenticacao).

## Eventos do ciclo de vida

### Eventos da autorização de margem

Acontecem **antes** de existir operação. Leia pela listagem de autorizações — ver [2.1 Autorização de margem](/guia/consignado-privado-cadastro-autorizacao).

| Evento | Status | O que representa | Ação sua |
|---|---|---|---|
| Autorização registrada | `Pending` | O consentimento foi registrado e aguarda confirmação no canal. | Aguardar. Não consulte margem ainda. |
| Autorização aprovada | `Approved` | O trabalhador confirmou. **É o único estado que habilita a consulta de margem.** | Seguir para a consulta de margem. |
| Autorização recusada | `Refused` | O trabalhador recusou, ou a validação do canal falhou. | Conferir o telefone do cadastro e coletar novo consentimento. |

Não existe status de expiração. Uma autorização vencida continua `Approved`, e o sinal é a **recusa da consulta de margem** — ver a seção de duração em [2.1 Autorização de margem](/guia/consignado-privado-cadastro-autorizacao).

### Eventos da operação de crédito

Em ordem de percurso. A coluna **Ação sua** é a que importa: só quatro estados exigem que você faça algo.

| Evento | Status | Quando acontece | O que representa | Ação sua |
|---|---|---|---|---|
| Operação criada | `Draft` | No `POST /v1/CreditNote`. | Rascunho. Ainda editável por `PUT`. | **Sim** — completar garantia e documentos e chamar `submitapproval`. |
| Enviada à esteira | `ComplianceApproval` ou `CreditApproval` | No `submitapproval`. | Em análise. A operação não aceita mais alteração. | Aguardar. |
| Em análise de crédito | `CreditApproval` | Após compliance. | Mesa avaliando risco e política. | Aguardar. |
| Em averbação | `Warranty` | Após aprovação de crédito. | A UY3 pediu a reserva de margem ao empregador e aguarda o retorno. | Aguardar. |
| Aguardando aprovação da reserva | `MarginReserveApproval` | Durante a averbação. | A reserva voltou e aguarda aprovação. | Aguardar. |
| Averbação em tratamento manual | `ManualWarranty` | Quando a averbação eletrônica não conclui. | A mesa está tratando o caso à mão. | Aguardar contato da UY3. **Não** recrie a operação em paralelo. |
| Garantia devolvida | `WarrantyRevision` | Quando a mesa reprova algum dado da garantia. | Dado do empregador, competência de desconto ou margem divergentes. | **Sim** — corrigir e chamar `POST /v1/CreditNote/{id}/doneWarrantyRevision`. |
| Instrumento em aprovação | `InstrumentApproval` | Após a garantia confirmada. | Geração e conferência do instrumento de crédito. | Aguardar. |
| Coleta de assinaturas aberta | `Signatures` | Após aprovação do instrumento. | As URLs de assinatura passam a existir. | **Sim** — obter `GET /v1/CreditNote/{id}/SignUrl` e entregar ao tomador. |
| Assinaturas em validação | `SignaturesValidation` ou `PartnerSignaturesValidation` | Após a coleta. | Conferência das assinaturas colhidas. | Aguardar. |
| Aguardando liquidação | `WaitLiquidation` | Após as assinaturas validadas. | Na fila de pagamento. | Aguardar. |
| Em liquidação | `Liquidation` ou `ManualLiquidation` | No processamento do pagamento. | A transferência está sendo feita. | Aguardar. |
| Pagamento devolvido | `PaymentRevision` | Quando a transferência falha. | Conta inválida ou titularidade divergente do CPF do tomador. | **Sim** — corrigir a conta em [2.2 Conta de liquidação](/guia/consignado-privado-cadastro-conta). |
| Operação encerrada | `Finished` | Após a liquidação. | Contrato ativo; as parcelas passam a ser descontadas em folha. | Nada. Conciliação periódica. |
| Devolvida para revisão | `Revision` | A qualquer momento, por decisão da mesa. | Algum atributo precisa de correção. | **Sim** — corrigir por `PUT /v1/CreditNote/{id}` e reenviar. |
| Reprovada | `Disapproved` | Em qualquer etapa de análise. | A operação não segue. | Ler o motivo — ver [5. Erros e troubleshooting](/guia/consignado-privado-erros). |
| Cancelada | `Canceled` | Após `POST /v1/CreditNote/{id}/cancel`. | Cancelamento concluído, incluindo o tratamento da reserva de margem. | Só recontratar para o mesmo trabalhador **depois** deste estado. |
| Falha técnica | `Error` | Falha no processamento. | Erro interno, não decisão de negócio. | Acionar a UY3 com o `id` da operação. |

### Como ler o evento

Não há corpo de evento a receber: o "payload do evento" é a própria operação, lida por `GET /v1/CreditNote/{id}`. Os campos relevantes para o acompanhamento:

| Campo | Tipo | Para que serve no acompanhamento |
|---|---|---|
| `id` | string (uuid) | A chave da operação no seu lado. |
| `creditNoteNo` | string | O número que a mesa e o suporte usam. Guarde junto do `id`. |
| `status` | enum | O evento atual. É o campo que dispara a sua máquina de estados. |
| `amortization` | objeto | Confirma valor, taxa e prazo efetivamente contratados. |
| `warranty` | lista | Confirma a garantia registrada, com o vínculo e a competência. |
| `uploads` | lista | Confirma quais documentos estão no dossiê. |

## Como processar

O padrão recomendado, e as armadilhas de cada parte.

1. **Guarde `id`, `creditNoteNo` e o último `status` conhecido** de cada operação, no seu banco. Sem o último status conhecido não existe "mudou de estado", só "está neste estado".
2. **Varra por status e por janela de data.** `GET /v1/CreditNote` com `status` e `initialDate`/`finalDate`, com paginação. Varra os estados em que você tem operações abertas, não todos.
3. **Compare com o último status conhecido.** Só reaja quando houver diferença. Reagir a cada leitura gera ação repetida — por exemplo, reentregar a URL de assinatura ao tomador todo dia.
4. **Trate o seu handler como idempotente.** A consulta devolve estado, não evento: ler duas vezes o mesmo `Signatures` é o comportamento normal, não uma duplicidade da API. A proteção contra ação repetida é do seu lado.
5. **Não confie na ordem das leituras para reconstruir o caminho.** Entre duas varreduras a operação pode ter passado por vários estados. Se você precisa do histórico, guarde cada transição que observar — a API devolve o estado atual, não a trilha.
6. **Reaja apenas aos quatro estados que exigem ação:** `Draft`, `WarrantyRevision`, `Signatures`, `PaymentRevision`. Some `Revision` e `Disapproved` se o seu processo trata devolução e reprovação. Todo o resto é espera.
7. **Defina alerta operacional por tempo em estado**, não por estado. `Warranty` por algumas horas é normal; `Warranty` por dias merece chamado. É a única forma de distinguir "processando" de "travado".

Intervalo de varredura: comece em 15 a 30 minutos para operações abertas e ajuste pelo seu volume. Varredura de minuto em minuto sobre carteira inteira consome limite de chamadas sem ganho — os estados que dependem de terceiros (empregador, averbadora, provedor de assinatura) não mudam nessa velocidade.

## Webhook de saída

> **Não disponível hoje.** O contrato da API **não expõe** webhook de saída para o Consignado privado. Não existe endpoint para você registrar uma URL de callback, e nenhum evento desta página é entregue ativamente ao seu sistema.

As rotas de webhook que existem no contrato de Crédito (`/v1/WebhookAutovist`, `/v1/WebhookWarehouse`) são o **contrário** do que se procura aqui: são endpoints da UY3 que **recebem** callbacks de prestadores externos, em fluxos de outros produtos. Não são endereçadas ao parceiro e não notificam nada sobre consignado privado.

Portanto: **o acompanhamento por consulta descrito acima não é uma alternativa ao webhook — é o mecanismo.** Implemente a varredura.

### Estrutura prevista

Quando o recurso existir, a intenção é entregar os mesmos eventos desta página, com um envelope estável. O desenho previsto — **sujeito a mudança até a publicação, não implemente contra ele**:

- Registro da URL de callback por ambiente do parceiro, e não por operação.
- Envelope com identificador do evento, tipo do evento, momento em UTC, e o identificador da operação — sem dado pessoal no corpo.
- O corpo da notificação **não substitui a consulta**: ele diz "a operação X mudou", e você busca o estado por `GET /v1/CreditNote/{id}`. Isso mantém uma fonte de verdade só.
- Reenvio em caso de falha de entrega, com o mesmo identificador de evento — o que torna a deduplicação pelo identificador obrigatória do seu lado.

Duas consequências para quem está desenhando a integração agora:

- **Construa a varredura de qualquer forma.** Ela continua necessária como rede de segurança mesmo depois do webhook, para o caso de entrega perdida.
- **Guarde o identificador do evento quando ele existir.** Se o seu handler já é idempotente por operação e estado, a migração para webhook é de transporte, não de lógica.

Para acompanhar a disponibilidade, fale com a equipe de tecnologia da UY3.

## O que acontece depois

Com a máquina de estados montada e a varredura rodando, o acompanhamento deixa de ser manual: o seu sistema sabe quando pedir assinatura, quando corrigir conta e quando avisar o trabalhador de que o dinheiro saiu.

## Antes desta etapa

- [4. Consultas e acompanhamento](/guia/consignado-privado-consultas) — as rotas usadas na varredura.
- [3. Operação](/guia/consignado-privado-operacao) — as ações que cada evento pode pedir.

## Próxima etapa

- [5. Erros e troubleshooting](/guia/consignado-privado-erros) — o que fazer quando o evento é `Disapproved`, `Revision` ou `Error`.
- [FGTS — Eventos e notificações](/guia/fgts-eventos) — o mesmo ciclo no outro módulo, com as diferenças marcadas.

## Downloads

- Contexto para LLM deste módulo: [llms-consignado-privado.txt](/downloads/llms-consignado-privado.txt)
- Collection Postman do módulo: [uy3-consignado-privado.postman_collection.json](/downloads/uy3-consignado-privado.postman_collection.json)
- Documentação consolidada para LLM: [llms.txt](/downloads/llms.txt)

---

## /guia/consignado-privado-erros — 5. Erros e troubleshooting

# Consignado privado — Erros e troubleshooting

Dado pessoal ou sensível deve ser **mascarado** em outputs, logs e exemplos. Todos os valores desta página são fictícios.

## O que é

Os erros que aparecem de fato na integração do consignado privado, agrupados pela etapa em que aparecem, com causa e ação corretiva. Cada linha responde: por que aconteceu e o que fazer agora.

## Quando usar

- Quando uma chamada devolve `400`, `403` ou `409` e a mensagem não é autoexplicativa.
- Quando a operação entra em `Disapproved`, `Revision`, `WarrantyRevision` ou `PaymentRevision`.
- Antes de abrir chamado: a maior parte dos casos abaixo se resolve sem a UY3.

## Erros por etapa

### Autenticação

| Sintoma | Causa provável | Ação corretiva |
|---|---|---|
| `401` em qualquer rota | Token expirado ou header ausente. | Emita um token novo e reenvie. Ver [Autenticação](/guia/autenticacao). |
| `403` em todas as rotas do Crédito do Trabalhador | Ambiente do parceiro sem habilitação do Crédito do Trabalhador. | Acione a UY3: a habilitação é por ambiente, não por chamada. |

### Autorização de margem

| Sintoma | Causa provável | Ação corretiva |
|---|---|---|
| `400` ao registrar a autorização | `additionalData` enviado sem `ip`, `geoLocation` ou `deviceModel`. | Complete o objeto ou não o envie. Ver [2.1 Autorização de margem](/guia/consignado-privado-cadastro-autorizacao). |
| Autorização parada em `Pending` | O trabalhador ainda não concluiu o aceite no canal. | Aguardar. Se o canal é `LinkWeb`, confirme que o link foi entregue. |
| Autorização `Refused` | O trabalhador recusou, ou a validação do canal falhou — em geral porque o telefone informado não é o dele. | Confira o telefone e colete novo consentimento. |
| Tentativa de informar `personId` na autorização | O corpo da autorização **não tem** esse campo: ela se identifica por CPF e telefone. | Remova. A autorização vem antes do cadastro do tomador, por desenho. Ver [2. Pré-requisitos e cadastros](/guia/consignado-privado-cadastros). |

### Consulta de margem

| Sintoma | Causa provável | Ação corretiva |
|---|---|---|
| Consulta recusada por falta de autorização | Não existe autorização `Approved` para o CPF, **ou** a autorização existente já não é aceita. | Confirme o status na listagem. Se estiver `Approved` e a consulta continuar recusando, a autorização venceu: colete novo consentimento e registre outra. |
| Margem retornada zerada ou insuficiente | Trabalhador sem margem livre — em geral por outros contratos consignados ativos — ou vínculo encerrado. | Não há operação possível agora. Reconsulte mais tarde; não force a proposta. |
| Vínculo não encontrado | CNPJ do empregador ausente na consulta, ou empregador sem registro na averbadora. | Envie `employerRegistrationNumber` e confirme com a UY3 se o empregador está integrado. |
| Consulta por `personId` devolve vazio, por CPF funciona | O `personId` informado é de outro correspondente, ou o cadastro não existe ainda. | Antes do cadastro, consulte por `registrationNumber`. Depois dele, por `personId`. |

### Simulação

Duas coisas diferentes se parecem aqui, e confundi-las custa tempo. **Não haver oferta elegível** e **não haver resultado para uma simulação específica** têm causas e ações distintas.

| | **Sem oferta elegível** | **Sem resultado para esta simulação** |
|---|---|---|
| O que aconteceu | Nenhum produto habilitado atende àquele trabalhador, com aquela margem e aquele vínculo. | Existem ofertas para o trabalhador, mas nenhuma **com os parâmetros que você pediu**. |
| Como identificar | Uma simulação **sem restrição de valor nem de prazo** também volta vazia. | Uma simulação sem restrição volta com ofertas; a sua, com filtros, volta vazia. |
| Causa típica | Margem insuficiente, vínculo não localizado, nenhum produto Price habilitado para a categoria. | Valor pedido acima do que a margem suporta, prazo fora da faixa do produto, taxa fixada fora da faixa. |
| Ação | Reveja margem e vínculo. Se estiverem certos, é caso de habilitação de produto — acione a UY3. | Ajuste os parâmetros. Nenhuma chamada à UY3 é necessária. |

**Como diagnosticar, na prática:** repita a simulação **sem** `requestedValue`, sem `rangePaymentAmounts`, sem `rangeNumberOfPayments`, sem `productIds` e sem `interestRate` — só com CPF e vínculo. Essa chamada responde a pergunta "existe alguma oferta para este trabalhador?". Se ela volta com ofertas, o problema estava nos seus filtros; se volta vazia, o problema é elegibilidade.

> **Por que a etapa de ofertas parecia contradizer isso.** A simulação de ofertas devolve as condições **possíveis** para os parâmetros informados. Quando ela volta vazia, isso não significa que o trabalhador não tenha oferta nenhuma — significa que não há oferta *naquele recorte*. É por isso que a chamada sem filtros acima é o teste que separa os dois casos.

| Sintoma | Causa provável | Ação corretiva |
|---|---|---|
| Simulação vazia com filtros, cheia sem filtros | Filtros estreitos demais. | Amplie `rangeNumberOfPayments`, reduza `requestedValue` ou remova `productIds` e `interestRate`. |
| Simulação vazia também sem filtros | Margem insuficiente, vínculo não localizado, ou nenhum produto habilitado atende. | Reveja o passo de margem. Persistindo, é habilitação de produto — acione a UY3. |
| Simulação vazia só ao pedir um valor | O valor pedido não cabe na margem, ainda que a margem exista. | Reduza `requestedValue`, ou simule por parcela com `calculateByValue: "Payment"`. |
| `400` na simulação por valor | `calculateByValue` é `Gross`/`Liquid` sem `requestedValue`, ou `Payment` sem `rangePaymentAmounts`. | Preencha o par correspondente ao modo escolhido. |
| Simulação sempre no valor máximo | Nenhum valor pedido foi informado: o comportamento padrão é usar a margem total. | Informe `calculateByValue` + `requestedValue` para simular abaixo da margem — ver [3. Operação](/guia/consignado-privado-operacao). |
| Nenhuma oferta apesar de o produto estar habilitado | O produto não é do modelo de cálculo Price. As rotas de oferta do Crédito do Trabalhador listam só produtos Price. | Confirme o modelo de cálculo do produto contratado com a UY3, ou use a simulação por amortização (`POST /v1/Amortization`). |

### Proposta

| Sintoma | Causa provável | Ação corretiva |
|---|---|---|
| Proposta recusada por expiração | `expirationDate` no passado, ou empregador aceitou depois do prazo. | Gere nova proposta com validade futura. |
| Parcela recusada na revalidação da oferta de leilão | A margem caiu entre a proposta e o aceite do empregador. | Reconsulte a margem e refaça a simulação com o valor novo. |
| `400` com reforço FGTS | `hasWarranty` marcado como `true` sem o saldo FGTS informado. | Informe `fgtsBalanceInCents` (e a multa rescisória, quando houver) ou desligue o reforço. |

### Criação da operação

| Sintoma | Causa provável | Ação corretiva |
|---|---|---|
| Tomador não vinculado ao usuário ou correspondente selecionado | O `personId` existe, mas pertence a outro correspondente ou grupo. | Use um tomador do seu escopo, ou solicite a atribuição do cadastro ao seu correspondente. |
| `400` de periodicidade | `paymentPeriodicity` diferente de `{ "every": 1, "periodicity": "Monthly" }`. | O consignado privado é mensal a cada 1 mês, porque o desconto acompanha a folha. Corrija o objeto. |
| `400` de modelo de cálculo não suportado | `amortizationType` divergente do modelo do produto contratado, ou valor legado `consignado`. | Envie `price` ou `sac`, conforme o produto. |
| `400` em `calculationType` | Envio de `Price` ou `SAC` nesse campo. | `calculationType` é o critério de contagem de dias (`V360DiasCorridos` e afins). O modelo vai em `amortizationType`. |
| `400` de taxa fora da faixa | `apr` fora da faixa de taxa do produto, ou igual a zero. | Use a taxa devolvida pela simulação. `apr` é **mensal**, em porcentagem. |
| `400` de prazo fora da faixa | `numberOfPayments` fora da faixa de prazo do produto. | Use o prazo devolvido pela simulação. |
| Valor da operação cem vezes menor que o esperado | `requestedAmount` enviado em reais e não em **centavos**. | `500000` são R$ 5.000,00. Ver [Convenções de dados](/guia/convencoes-de-dados). |
| Garantia com valor absurdo | `totalValue` enviado em centavos. Ao contrário de `requestedAmount`, ele é em **reais**. | `6840.00` são R$ 6.840,00. Os dois campos convivem no mesmo corpo com unidades diferentes. |
| `400` na competência de desconto | `dataprev_DiscountStartPeriod` enviado como `2026-10` ou `10/2026`. | Envie a data civil completa, com dia, mês e ano: `2026-10-01`. |
| `400` com campos de outro modelo de cálculo | Envio de `paymentDay`, `termInMonths`, `periodicity`, `daysInYear` ou `paymentMonth`. | Remova. Esses campos pertencem a outros modelos — ver [3. Operação](/guia/consignado-privado-operacao). |
| `400` na conta de liquidação | `liquidationType` é `EletronicTransfer` sem `bankAccountId`. | Informe a conta cadastrada. |
| Averbação não localiza o vínculo | Cadastro do tomador sem `workplaceCompanyRegistrationNumber`, `employeeNumber` ou `admissionDate`. | Complete os campos de vínculo em [2.3 Cadastro do tomador](/guia/consignado-privado-cadastro-pessoa), usando os valores da consulta de margem. |

### Envio para aprovação e garantia

| Sintoma | Causa provável | Ação corretiva |
|---|---|---|
| É necessário informar ao menos uma garantia para enviar a operação para aprovação | Operação sem garantia, em produto que exige lastro. | Anexe a garantia de margem por `PUT /v1/CreditNote/{id}/warranty` e reenvie. |
| `409` ao reenviar `submitapproval` | A operação já saiu do rascunho: depois do envio ela não aceita alteração até o fim da análise. | Consulte o status antes de repetir. Ver [4.1 Eventos e notificações](/guia/consignado-privado-eventos). |
| Operação parada em `Warranty` por muito tempo | Averbação aguardando retorno do empregador ou da averbadora. | Aguardar. Se passar da janela combinada, acione a UY3 com o `id`. |
| Operação em `WarrantyRevision` | A mesa devolveu a garantia: dado do empregador, competência de desconto ou margem divergentes. | Corrija a garantia e encerre a revisão com `POST /v1/CreditNote/{id}/doneWarrantyRevision`. |
| Documento obrigatório ausente | Falta o termo de autorização de margem ou outro documento exigido pelo produto. | Anexe por `PUT /v1/CreditNote/{id}/upload` e reenvie. |
| Documento assinado enviado em rascunho não foi aproveitado | A coleção `uploads` foi enviada vazia, ou com `fileType` que não identifica o documento assinado. | Envie o item com `fileType: "SignedContract"`. Coleção vazia não reserva lugar — ver [3. Operação](/guia/consignado-privado-operacao). |
| Documento duplicado no dossiê | O mesmo arquivo foi reenviado em mais de uma etapa. | Envie uma vez. O documento permanece vinculado à operação. |

### Assinatura e liquidação

| Sintoma | Causa provável | Ação corretiva |
|---|---|---|
| Sem URL de assinatura | A operação ainda não chegou a `Signatures`. | Aguarde a aprovação do instrumento e reconsulte `SignUrl`. |
| Operação em `PaymentRevision` | Conta de liquidação inválida ou titularidade divergente do CPF do tomador. | Corrija a conta em [2.2 Conta de liquidação](/guia/consignado-privado-cadastro-conta). Chave Pix de terceiro é recusada. |
| Sem comprovante de transferência | A liquidação ainda não ocorreu. | Aguarde `Liquidation`/`Finished` e reconsulte. |

### Cancelamento

| Sintoma | Causa provável | Ação corretiva |
|---|---|---|
| Nova operação para o mesmo trabalhador recusada por falta de margem, logo após um cancelamento | O cancelamento ainda está em processamento: a margem só volta a ficar livre quando ele conclui. | Acompanhe a operação anterior até `Canceled` antes de recontratar. |
| `400` ao excluir a operação | Exclusão só é permitida em `Draft`, `Revision`, `Disapproved` e `Canceled`. | Cancele primeiro e depois exclua, se necessário. |

## Como reagir a cada erro

Ordem de diagnóstico, do mais provável ao menos:

1. **Releia a mensagem da resposta.** As validações de negócio do consignado privado (periodicidade, faixa de taxa, faixa de prazo, margem) vêm com texto explícito.
2. **Confira o status atual** com `GET /v1/CreditNote/{id}`. Boa parte dos `400` e `409` é ação certa no status errado — ver [4.1 Eventos e notificações](/guia/consignado-privado-eventos).
3. **Confira a unidade e o formato.** Valor em centavos contra valor em reais, e competência com dia, mês e ano. É a causa mais frequente de operação criada com número errado. Ver [Convenções de dados](/guia/convencoes-de-dados).
4. **Confira os identificadores** contra os cadastros: `personId`, `bankAccountId`, `productId` — e o CPF, que é o que liga a autorização ao cadastro.
5. **Isole a simulação.** Antes de concluir que não há oferta, rode a simulação sem filtros. Separa elegibilidade de parâmetro em uma chamada.
6. **Só então acione a UY3**, com o `id` da operação, o horário da chamada e o corpo enviado — **com os dados pessoais mascarados**.

> Orientação técnica. A classificação de dado pessoal, a base legal do tratamento e a guarda de documentos de 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

Erro corrigido no rascunho: reenvie para aprovação e a operação retoma o fluxo. Erro corrigido depois de uma devolução para revisão: encerre a revisão pela rota indicada e a operação volta para a etapa seguinte da esteira, sem recomeçar.

## Antes desta etapa

- [4.1 Eventos e notificações](/guia/consignado-privado-eventos) — é o status que revela em qual erro você caiu.
- [3. Operação](/guia/consignado-privado-operacao) — as tabelas de preenchimento que a maioria dos `400` aponta.

## Próxima etapa

- [1. Visão geral](/guia/consignado-privado-visao-geral) — voltar ao começo do fluxo com um novo tomador.
- [FGTS](/guia/fgts-visao-geral) — o outro módulo publicado neste padrão.

## Downloads

- Contexto para LLM deste módulo: [llms-consignado-privado.txt](/downloads/llms-consignado-privado.txt)
- Collection Postman do módulo: [uy3-consignado-privado.postman_collection.json](/downloads/uy3-consignado-privado.postman_collection.json)
- Documentação consolidada para LLM: [llms.txt](/downloads/llms.txt)

---