Manual Consignado Privado - Portabilidade: Digitação da Proposta

A digitação da proposta cria a operação de portabilidade e, opcionalmente, a operação de refinanciamento (Troco) na mesma requisição, por meio do endpoint POST /v2/credit_transfer/proposal.

ENDPOINT

/v2/credit_transfer/proposal

MÉTODO

POST

Testar no Playground

Atenção

Para que os pedidos de averbação, tanto da portabilidade quanto do refinanciamento, sejam criados com sucesso, é preciso que uma consulta de dados válida do trabalhador tenha sido feita previamente. Siga os passos de Consultas Prévias.

Estrutura da requisição

A requisição é composta por alguns campos no nível raiz e pelos objetos da operação. A estrutura geral é a seguinte — cada objeto é detalhado nas seções abaixo:

Estrutura geral
{
    "proposal_type": "private_company",
    "purchaser_document_number": "32402502000135",
    "borrower": { /* dados cadastrais do tomador */ },
    "related_parties": [ /* representante legal, quando houver */ ],
    "collaterals": [ /* garantia: folha de pagamento */ ],
    "portability_credit_operation": { /* operação portada */ },
    "refinancing_credit_operation": { /* Troco — opcional */ },
    "origin_contract": { /* contrato na instituição de origem */ },
    "additional_data": {}
}

Campo (raiz)	Tipo	Obrigatório	Descrição
`proposal_type`	string	✅	`"private_company"` para Consignado Privado.
`purchaser_document_number`	string	✅	CNPJ do comprador da operação.
`additional_data`	object	—	Dados complementares da operação.

Portabilidade sem refinanciamento

Para uma portabilidade pura, sem liberação de Troco, omita o objeto refinancing_credit_operation, mantendo portability_credit_operation e origin_contract.

`borrower` — dados do tomador

Dados cadastrais do tomador do crédito. Ver objeto compartilhado Borrower. Os documentos do tomador não são enviados na proposta — a formalização é feita via QI Sign. Ver Formalização.

{
    "person_type": "natural",
    "name": "Marilene da Silva",
    "mother_name": "Maria Mariane",
    "birth_date": "1990-05-06",
    "profession": "Desenvolvedora",
    "nationality": "Brasileira",
    "marital_status": "single",
    "is_pep": false,
    "individual_document_number": "20676928013",
    "document_identification_number": "381803326",
    "email": "marilene@email.com",
    "phone": {
        "country_code": "055",
        "area_code": "11",
        "number": "912828135"
    },
    "address": {
        "street": "Passagem Mariana",
        "state": "PA",
        "city": "Ananindeua",
        "neighborhood": "Águas Lindas",
        "number": "660",
        "postal_code": "67118003",
        "complement": "complemento"
    }
}

`related_parties` — representante legal (opcional)

Envie esta lista apenas quando a operação tem representante legal. Cada item deve conter os dados cadastrais do representante e o campo role_type com o valor issuer_legal_representative.

[
    {
        "name": "Nome Representante Legal",
        "email": "email@email.com.br",
        "birth_date": "2000-12-12",
        "is_pep": false,
        "mother_name": "maria",
        "phone": {
            "number": "991294043",
            "area_code": "11",
            "country_code": "055"
        },
        "address": {
            "street": "Avenida das Castanheiras",
            "state": "SP",
            "city": "Brasília",
            "neighborhood": "bairro",
            "number": "12",
            "postal_code": "71900100",
            "complement": ""
        },
        "role_type": "issuer_legal_representative",
        "person_type": "natural",
        "individual_document_number": "45102538004",
        "document_identification_type": "rg",
        "document_identification_number": "123456789"
    }
]

`collaterals` — garantia (folha de pagamento)

A garantia é a folha de pagamento de funcionários de empresas privadas. O collateral_data carrega o CNPJ do empregador e a matrícula do trabalhador.

[
    {
        "collateral_type": "private_payroll",
        "collateral_data": {
            "employer_document_number": "<CNPJ DO EMPREGADOR>",
            "registration_number": "<MATRÍCULA DO TRABALHADOR>"
        }
    }
]

`portability_credit_operation` — operação portada

Operação que assume (porta) o contrato de origem. Informe sempre number_of_installments e uma entre monthly_interest_rate ou installment_face_value.

{
    "financial": {
        "monthly_interest_rate": 0.0132,
        "number_of_installments": 10
    },
    "contract_number": "300523588PF"
}

`refinancing_credit_operation` — Troco (opcional)

Operação que quita a portabilidade e libera o Troco na conta do trabalhador. Como o refinanciamento não tem data de desembolso fixa, a mudança na data de desembolso altera os valores da operação — por isso é necessário fixar a taxa (monthly_interest_rate) ou o valor liberado ao cliente (disbursed_amount).

A única diferença entre as duas formas está no objeto financial; disbursement_bank_account (conta de destino do Troco) e contract_number são iguais nos dois casos.

Fixando a taxa
Fixando o valor liberado

{
    "financial": {
        "monthly_interest_rate": 0.0132,
        "installment_face_value": 100,
        "number_of_installments": 10
    },
    "disbursement_bank_account": {
        "account_digit": "1",
        "account_number": "000059923",
        "ispb": "341",
        "bank_code": "341",
        "branch_number": "0155"
    },
    "contract_number": "200523588PK"
}

{
    "financial": {
        "disbursed_amount": 1000,
        "installment_face_value": 100,
        "number_of_installments": 10
    },
    "disbursement_bank_account": {
        "account_digit": "1",
        "account_number": "000059923",
        "ispb": "341",
        "bank_code": "341",
        "branch_number": "0155"
    },
    "contract_number": "200523588PK"
}

`origin_contract` — contrato de origem

Identifica a dívida na instituição credora original.

{
    "ispb": "60746948",
    "contract_number": "558472",
    "last_due_balance": 997.87
}

ISPB do credor original

O origin_contract.ispb é o ISPB da instituição credora original (a base do CNPJ da instituição). A lista completa de ISPBs das instituições participantes da CTC pode ser obtida pelo endpoint de consulta de participantes do CTC.

Campos das operações

Campo	Tipo	Obrigatório	Descrição
`collaterals[].collateral_type`	string	✅	`"private_payroll"`.
`collaterals[].collateral_data.employer_document_number`	string	✅	CNPJ do empregador.
`collaterals[].collateral_data.registration_number`	string	✅	Matrícula do trabalhador na folha do empregador.
`portability_credit_operation.financial.number_of_installments`	integer	✅	Número de parcelas.
`portability_credit_operation.financial.monthly_interest_rate` / `installment_face_value`	number	✅	Enviar uma das duas.
`portability_credit_operation.contract_number`	string	✅	Número do contrato de portabilidade gerado.
`refinancing_credit_operation.financial`	object	⚠️	Necessário quando há Troco. Fixar `monthly_interest_rate` (taxa) ou `disbursed_amount` (valor liberado).
`refinancing_credit_operation.disbursement_bank_account`	object	⚠️	Conta de destino do Troco.
`origin_contract.ispb`	string	✅	ISPB do credor original (base do CNPJ).
`origin_contract.contract_number`	string	✅	Número do contrato na instituição de origem.
`origin_contract.last_due_balance`	number	✅	Saldo devedor do contrato de origem.

Response

A criação da proposta retorna a proposal_key e, dentro de borrower e de cada item de related_parties, a related_party_key (identificador de cada parte na proposta).

Response Body (resumido)

{
    "proposal_key": "<PROPOSAL-KEY>",
    "status": "pending_submission",
    "borrower": {
        "name": "Marilene da Silva",
        "individual_document_number": "20676928013",
        "role_type": "issuer",
        "related_party_key": "511d7186-3c17-4f35-8887-c4aefaf270be"
    },
    "collaterals": [
        {
            "collateral_type": "private_payroll",
            "collateral_data": {
                "employer_document_number": "<CNPJ DO EMPREGADOR>",
                "registration_number": "<MATRÍCULA DO TRABALHADOR>"
            }
        }
    ],
    "portability_credit_operation": {
        "contract_number": "300523588PF"
    },
    "refinancing_credit_operation": {
        "contract_number": "200523588PK"
    },
    "origin_contract": {
        "ispb": "60746948",
        "contract_number": "558472",
        "last_due_balance": 997.87
    }
}

Recuperar dados de uma proposta

Em casos de timeout ou operação duplicada, é possível recuperar os dados de uma proposta enviando a requester_control_key no lugar da proposal_key. Ver Consultas e Operações Pós-Proposta.

Correção de dados

Após a digitação, dados da proposta podem ser corrigidos antes do avanço do fluxo — para a operação de refinanciamento, para a portabilidade, ou para ambas. Dependendo do dado alterado, pode ser necessária uma nova assinatura da CCB. As transições e o endpoint de atualização (PATCH /v2/credit_transfer/proposal/{PROPOSAL-KEY}) estão detalhados em Acompanhamento da Operação.

Estrutura da requisição​

borrower — dados do tomador​

related_parties — representante legal (opcional)​

collaterals — garantia (folha de pagamento)​

portability_credit_operation — operação portada​

refinancing_credit_operation — Troco (opcional)​

origin_contract — contrato de origem​

Campos das operações​

Response​

Correção de dados​