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.

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

Endpoints do fluxo principal

Passo 1 — Consultar a margem livre

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.

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

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

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

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:

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.

Data da primeira parcela

POST /v1/DataprevEmployee/FirstPaymentDate

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

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.

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)

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.

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:

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

POST /v1/CreditNote

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

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

POST /v1/CreditNote/{id}/submitapproval

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

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.

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

POST /v1/CreditNote/{id}/doneWarrantyRevision

Passo 9 — Cancelar, excluir ou restaurar

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.

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

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.

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

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:

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:

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:

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

Exemplo de response

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

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.

Antes desta etapa

• 2.3 Cadastro do tomador — o personId e o bankAccountId consumidos aqui.
• 2. Pré-requisitos e cadastros — índice dos três cadastros e a ordem entre eles.

Próxima etapa

• 4. Consultas e acompanhamento — status, parcelas e comprovante de transferência.
• 4.1 Eventos e notificações — o ciclo de vida completo, evento por evento.
• 5. Erros e troubleshooting — quando alguma etapa acima falhar.

Downloads

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