Manual Consignado Privado - Portabilidade: Consultas e Operações Pós-Proposta
Consulta de Lista de Participantes do CTC
ENDPOINT
/v2/credit_transfer/participantsMÉTODO
GETResposta
response.json
[
{
"name": "<NOME DO BANCO>",
"bank_code": "<CÓDIGO DO BANCO>",
"ispb": "<BASE DO CNPJ DO BANCO>"
}
]
Recuperar resposta da última request
O last response é uma forma de mapear, de forma simples e objetiva, a resposta da comunicação entre a QI e o empregador, possibilitando saber quando essa requisição foi feita e qual o retorno obtido (através de um enumerador). Os enumeradores estão divididos em duas formas: "errors" e "success".
Cada enumerador tem uma descrição detalhada e o código de referência. Podemos conferir abaixo, com mais detalhes, como serão apresentados os dados do last response.
Casos de sucesso
Requisição
ENDPOINT
/v2/credit_transfer/proposal/PROPOSAL-KEY/CREDIT-OPERATION-TYPE/collateralMÉTODO
GETPath Params credit-operation-type
| Enumerador | Descrição |
|---|---|
| refinancing_credit_operation | Operação de refinanciamento |
| portability_credit_operation | Operação de portabilidade |
Resposta
Response Body
{
"collateral_data": {
"employer_document_number": "<CNPJ DO EMPREGADOR>",
"registration_number": "<MATRÍCULA DO TRABALHADOR>",
"last_response": {
"success": [
{
"enumerator": "succesfully_included",
"reservation_method": "portability"
}
]
},
"last_response_event_datetime": "2023-05-22T19:13:02Z",
"status": "reserved"
},
"collateral_constituted": true,
"collateral_type": "private_payroll"
}
Detalhamento de campos no retorno da request
| Campo | Descrição | Valores |
|---|---|---|
| enumerator | Retorno mapeado do código de resposta | Consultas do Trabalhador |
| reservation_method | Método de averbação da reserva | portability, new_credit, refinancing |
Casos de erro
Requisição
ENDPOINT
/v2/credit_transfer/proposal/PROPOSAL-KEY/CREDIT-OPERATION-TYPE/collateralMÉTODO
GETResposta
Response Body
{
"collateral_constituted": false,
"collateral_type": "type",
"updated_at": "2023-05-24 19:13:02",
"collateral_data": {
"employer_document_number": "<CNPJ DO EMPREGADOR>",
"registration_number": "<MATRÍCULA DO TRABALHADOR>",
"status": "pending_reservation",
"last_response": {
"errors": [
{
"enumerator": "consignable_margin_exceeded",
"reservation_method": "portability"
},
{
"enumerator": "consignable_margin_exceeded",
"reservation_method": "new_credit"
}
]
},
"last_response_event_datetime": "2023-05-22T19:13:02Z"
}
}
Detalhamento de campos no webhook de falha
| Campo | Descrição | Valores |
|---|---|---|
| enumerator | Retorno mapeado do código de resposta | Consultas do Trabalhador |
| reservation_method | Método de averbação da reserva | portability, new_credit, refinancing |
Webhook de resposta da última tentativa de averbação
Caso a operação não tenha sucesso na averbação na folha do empregador, a mesma ficará em retentativa e será enviado o seguinte webhook, detalhando o motivo da não averbação, o horário desta tentativa e o método de averbação utilizado. Trata-se da reserva de margem (averbação) na folha de pagamento de funcionários de empresas privadas.
- Operação de portabilidade
- Operação de refinanciamento
WEBHOOK_TYPE
credit_transfer.proposal.collateral{
"webhook_type": "credit_transfer.proposal.collateral",
"proposal_key": "<PROPOSAL-KEY>",
"event_datetime": "2022-11-24T15:42:12",
"data": {
"credit_operation_type": "portability",
"credit_operation_key": "<CREDIT-OPERATION-KEY>",
"collateral_type": "private_payroll",
"collateral_constituted": false,
"collateral_data": {
"status": "pending_reservation",
"last_response": {
"errors": [
{
"enumerator": "consignable_margin_exceeded"
}
]
},
"last_response_event_datetime": "2023-05-22T19:13:02Z",
"reservation_method": "new_credit"
}
}
}
WEBHOOK_TYPE
credit_operation.collateral{
"webhook_type": "credit_operation.collateral",
"key": "<CREDIT-OPERATION-KEY>",
"event_time": "2022-11-24T15:42:12",
"data": {
"collateral_type": "private_payroll",
"collateral_constituted": false,
"collateral_data": {
"status": "pending_reservation",
"last_response": {
"errors": [
{
"enumerator": "consignable_margin_exceeded"
}
]
},
"last_response_event_datetime": "2023-05-22T19:13:02Z",
"reservation_method": "refinancing"
}
}
}
Detalhamento de campos no webhook de falha
| Campo | Descrição | Valores |
|---|---|---|
| enumerator | Retorno mapeado do código de resposta | Consultas do Trabalhador |
| reservation_method | Método de averbação da reserva | portability, new_credit, refinancing |
Consulta de portabilidade de origem
É possível consultar os dados da portabilidade do banco de origem como, por exemplo, o vínculo empregatício, a data de início da portabilidade, o número dos contratos excluídos, os valores das parcelas desaverbadas, ultima parcela paga, data de exclusão, entre outros.
ENDPOINT
/private_payroll/reservation/external_key/CREDIT-OPERATION-KEY/portability_origin_contractMÉTODO
POSTRequisição
request.json
{
"request_type": "portability_number",
"portability_number": "202402070000298096242"
}
Resposta
response.json
{
"origin_contract_request_key": "9bb68c89-4b88-400d-9359-99ad8d42a69e",
"status": "pending_search",
"status_events": [
{
"status": "pending_search"
}
]
}
Em caso de sucesso na consulta do vínculo empregatício
Webhook
WEBHOOK_TYPE
private_payroll_portability_origin_contract_request
STATUS
Success
response.json
{
"webhook": {
"key": "25e93655-4713-488b-8800-7ac4fddf745f",
"data": {
"portability_number": 9223372036854776000,
"portability_status": "open",
"employer_document_number": "<CNPJ DO EMPREGADOR>",
"registration_number": "<MATRÍCULA DO TRABALHADOR>",
"portability_start_date": "2024-02-22",
"deleted_contracts": [
{
"origin_bank": {
"bank_code": 752,
"name": "CETELEM-BNP"
},
"contract_number": "22-844817807/20",
"last_installment_paid": 84,
"exclusion_date": "22022024",
"period_amount": 165.73
}
]
},
"status": "success",
"webhook_type": "private_payroll_portability_origin_contract_request",
"event_datetime": "2024-02-26T21:36:22"
}
}
Em caso de falha na consulta do vínculo empregatício
Webhook
WEBHOOK_TYPE
private_payroll_portability_origin_contract_request
STATUS
Failure
response.json
{
"webhook": {
"key": "522b5d7d-2dfc-4e92-99b7-d4df3d97edb2",
"data": {
"enumerator": "invalid_bank_code",
"description": "Invalid bank code"
},
"status": "failure",
"webhook_type": "private_payroll_portability_origin_contract_request",
"event_datetime": "2024-02-26T21:36:22"
}
}
Diminuir o valor das parcelas
Este endpoint permite a redução do valor das parcelas de um contrato de portabilidade de crédito. Esta funcionalidade é especialmente útil em casos onde a margem consignável é excedida devido ao banco de origem desaverbar uma quantia menor do que a esperada.
ENDPOINT
/v2/credit_transfer/proposal/PROPOSAL-KEY/portability_credit_operationMÉTODO
PUTRequisição
request.json
{
"installment_face_value": 382.18
}
Resposta sucesso - HTTP 200
response.json
{
"credit_operation_key": "7aa77bca-c724-4c1a-bfae-9b1b7bd81ab2",
"contract_number": "0000000007/WO",
"document_key": "045a8f35-6170-4112-8d83-29a753d0c78e",
"document_url": "http://teste.com",
"signed_url": "signed_url_test",
"credit_operation_status": "waiting_signature",
"fine_configuration": {
"contract_fine_rate": 0.02,
"interest_base": "calendar_days",
"monthly_rate": 0.01
},
"disbursement_accounts": [
{
"account_digit": "3",
"account_branch": "0001",
"account_number": "94134",
"ispb": "32402502",
"name": "Wilker Teste",
"document_number": "37197645832"
}
],
"disbursement_options": [
{
"prefixed_interest_rate": {
"annual_rate": 3.0,
"daily_rate": 0.00385824,
"interest_base": "calendar_days",
"monthly_rate": 0.12246205
},
"total_iof": 7.03,
"external_contract_fee_amount": 0.0,
"external_contract_fees": [],
"contract_fee_amount": 0.0,
"number_of_installments": 3,
"contract_fees": [],
"disbursed_issue_amount": 1000.0,
"issue_amount": 1007.03,
"disbursement_date": "2022-08-24",
"cet": 12.6,
"annual_cet": 315.3944,
"installments": [
{
"business_due_date": "2022-08-30",
"calendar_days": 5,
"due_date": "2022-08-29",
"due_principal": 1007.03,
"installment_number": 1,
"pre_fixed_amount": 84.43554587915118,
"principal_amortization_amount": 297.73445412084885,
"total_amount": 382.17,
"workdays": 3
},
{
"business_due_date": "2022-09-30",
"calendar_days": 31,
"due_date": "2022-09-29",
"due_principal": 709.2955458791512,
"installment_number": 2,
"pre_fixed_amount": 47.97894031795043,
"principal_amortization_amount": 334.19105968204957,
"total_amount": 382.17,
"workdays": 22
},
{
"business_due_date": "2022-11-01",
"calendar_days": 32,
"due_date": "2022-10-31",
"due_principal": 375.1044861971016,
"installment_number": 3,
"pre_fixed_amount": 7.055513802898396,
"principal_amortization_amount": 375.1044861971016,
"total_amount": 382.16,
"workdays": 21
}
],
"final_disbursement_amount": 997.87
}
],
"final_disbursement_amount": 997.87,
"collateral_is_constituted": false
}
Incluir Fee na operação de portabilidade rebatido pela QI ao parceiro
Para inclusão do fee, é necessário que a operação esteja averbada, desembolsada e que não esteja cedida.
ENDPOINT
/v2/credit_transfer/proposal/PROPOSAL-KEY/portability_credit_operation/rebateMÉTODO
POSTRequisição
request.json
{
"amount": 20,
"rebate_bank_account": {
"name": "Teste Ltda",
"document_number": "18533555000164",
"account_digit": "0",
"account_number": "4290001",
"branch_number": "0001",
"bank_code": "329"
},
"amount_type": "percentage",
"fee_type": "spread"
}
Resposta
response.json
{}
Recibo do pagamento de portabilidade (STR00047)
Após o pagamento da portabilidade, é possível gerar o recibo da transação.
ENDPOINT
/v2/credit_transfer/proposal/PROPOSAL-KEY/receipt_str0047MÉTODO
POSTRequisição
request.json
{}
Resposta
response.json
{
"proposal_key": "CHAVE DA PROPOSTA",
"receipt_url": "URL DO RECIBO",
"receipt_document_key": "CHAVE DO RECIBO"
}