Pular para o conteúdo principal

Fluxo Completo - Portabilidade + Refinanciamento

Atenção!

Os webhooks da QI Tech não devem ser mapeadas de forma restrita. Campos adicionais podem ser incluídos aos payloads dos webhooks retornados em nossas APIs.

Reenvio de Webhooks

Você pode consultar e reenviar webhooks seguindo as instruções detalhadas na documentação: Reenvio de Webhooks.

Para iniciar o processo de Portabilidade + Refinanciamento - INSS, primeiramente é necessário coletar os dados do benefício para checagem da elegibilidade como também os dados da conta de pagamento do benefício. Os itens 1 e 2, descrevem o procedimento para consulta da lista de benefícios de um determinado beneficiário e procedimento para consulta dos dados do benefício.

Para acompanhamento dos status após a formalização, consulte Máquinas de Status.

1 - Consulta da lista de benefícios com formalização do Termo de Autorização realizada através do parceiro:​

        1.1. Titular do benefício é o assinante do Termo de Autorização.

        Request

  • ENDPOINT
    /social_security/benefits_request
  • MÉTODO
    POST
Testar no Playground

        Payload:

payload.json
{
	"document_number": "16514548091",
	"authorization_term": {
		"document_number": "16514548091",
		"signature": {
			"signer": {
				"name": "Nome Devedor",
				"phone": {
					"number": "887577622",
					"area_code": "19",
					"country_code": "55"
				},
				"document_number": "16514548091"
			},
			"authentication_type": "opt_in",
			"authenticity": {
				"timestamp": "2023-12-05T21:04:06",
				"ip_address": "200.223.171.82",
				"fingerprint": {
					"lat": "-44.00524157713981",
					"long": "-19.807649431219804",
					"name": "Nome Cliente",
					"model": "Mozilla/5.0 (iPhone; CPU iPhone OS 16_6_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/16.6 Mobile/15E148 Safari/604.1",
					"localeHashValue": "hash cliente"
				},
				"third_party_additional_data": {},
				"session_id": "3571e292-3a83-4011-904d-20ee963022ef"
			},
			"signed_object": {
				"document_key": "cfbc8469-89ea-4a80-9f64-ba7b1566c68b"
			}
		}
	}
}

        1.2. Titular do benefício não é o assinante do Termo de Autorização (com representante legal).

Atenção

Como o assinante do termo nesse caso é o representante legal, os dados que preenchem o objeto signer, são os dados do representante legal.

        Request

  • ENDPOINT
    /social_security/benefits_request
  • MÉTODO
    POST

        Payload:

payload.json
{
	"document_number": "16514548091",
	"authorization_term": {
		"document_number": "16514548091",
        "legal_representative_document_number": "70957091060",
		"signature": {
			"signer": {
				"name": "Nome Representante legal",
				"phone": {
					"number": "887577622",
					"area_code": "19",
					"country_code": "55"
				},
				"document_number": "70957091060"
			},
			"authentication_type": "opt_in",
			"authenticity": {
				"timestamp": "2023-12-05T21:04:06",
				"ip_address": "200.223.171.82",
				"fingerprint": {
					"lat": "-44.00524157713981",
					"long": "-19.807649431219804",
					"name": "Nome Cliente",
					"model": "Mozilla/5.0 (iPhone; CPU iPhone OS 16_6_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/16.6 Mobile/15E148 Safari/604.1",
					"localeHashValue": "hash cliente"
				},
				"third_party_additional_data": {},
				"session_id": "3571e292-3a83-4011-904d-20ee963022ef"
			},
			"signed_object": {
				"document_key": "cfbc8469-89ea-4a80-9f64-ba7b1566c68b"
			}
		}
	}
}


Atenção

Nos casos em que houver representante legal, é necessário preencher o campo "legal_representative_document_number" com o CPF do representante legal, e os dados do objeto "signer" devem ser preenchidos com os dados do mesmo.

        "document_key": utilizar a GUID retornada no endpoint /upload

informação

Ao invés da chave do documento pdf assinado no objeto "authorization_term.signed_object.document_key", também é possível enviar o texto corrido do Termo de Autorização, através do objeto "authorization_term.signed_object.raw_text".

        Response

  • MÉTODO
    POST
  • ENDPOINT
    social_security/benefits_request
body.json

{
    "benefits_request_key": "c9d2aa83-006b-4753-92ad-64411a7aa700",
    "document_number": "18028522041",
    "status": "pending_authorization",
    "authorization_term": {
        "authorization_term_key": "5a7b6489-8a47-4b61-a85a-6986b058fda6",
        "status": "signed"
    },
    "status_events": [
        {
            "status": "pending_authorization",
            "event_date": "2023-12-22T16:12:50"
        }
    ]
}

Em caso de sucesso na consulta da lista de benefícios:

        Webhook

  • WEBHOOK_TYPE
    social_security_benefits_request
  • STATUS
    Success
body.json
{
    "webhook": {
        "key": "54cddd0f-b976-4266-91ea-90279bfb49a1",
        "data": [
            {
                "grant_date": [
                    "2010-10-18"
                ],
                "benefit_number": 2052711150,
                "benefit_status": "elegible"
            }
        ],
        "status": "success",
        "webhook_type": "social_security_benefits_request",
        "event_datetime": "2023-12-22T13:20:44"
    }
}
CampoDescriçãoValores
benefit_numberNúmero do beneficio-
benefit_statusStatus do beneficioEnumeradores

Em caso de falha na consulta da lista de benefícios:

        Webhook

  • WEBHOOK_TYPE
    social_security_benefits_request
  • STATUS
    Failure
body.json

{
    "webhook": {
        "key": "0020653e-c3b0-4606-af31-2ea4a577a5ce",
        "data": {
            "enumerator": "inexistent_beneficiary",
            "description": "no beneficiary found"
        },
        "status": "failure",
        "webhook_type": "social_security_benefits_request",
        "event_datetime": "2023-12-22T15:46:31"
    }
}

Detalhamento de campos no webhook de falha​

CampoDescriçãoValores
enumeratorRetorno mapeado do código DataprevEnumeradores

Simulando cenários de sucesso e insucesso na consulta de benefício em Sandbox:​

A simulação de cenários é baseado no primeiro dígito do CPF informado na operação.

11.1. Para CPFs iniciados com o número 1, será retornado uma resposta assíncrona de sucesso através do Webhook.

11.2. Para os demais CPFs, será retornado uma resposta assíncrona de erro, baseado no primeiro dígito do CPF digitado, de acordo com a tabela abaixo.

Início do CPFEnumeradorDescrição
2inexistent_beneficiaryno beneficiary found
Atenção

Todos os CPFs que não tiverem um cenário mapeado para o primeiro dígito, receberão um webhook com um erro padrão de cenário de teste não mapeado.

EnumeradorDescrição
mock_errorInformed document number is not a valid mock on test environment

2 - Consulta de dados do benefício​

        2.1. Consulta de dados do benefício com o Termo de Autorização previamente enviado.

        Request

  • MÉTODO
    POST
  • ENDPOINT
    /social_security/balance_request
Testar no Playground

        Payload:

payload.json
{
    "document_number": "16514548091",
    "benefit_number": 2052711150
}

        Response

  • MÉTODO
    POST
  • ENDPOINT
    /social_security/balance_request
body.json
{
    "balance_request_key": "ffda1935-9cad-47df-b848-cd33c96024e4",
    "document_number": "16514548091",
    "status": "pending_authorization",
    "authorization_term": {
        "authorization_term_key": "19196811-366f-4422-a729-4d0aa552449b",
        "status": "allowed"
    },
    "status_events": [
        {
            "status": "pending_authorization",
            "event_date": "2023-12-22T16:18:18"
        }
    ]
}


        2.2. Consulta de dados do benefício com envio do Termo de Autorização.

        Request

  • MÉTODO
    POST
  • ENDPOINT
    /social_security/balance_request

        Payload:

payload.json
{
    "document_number": "14950479032",
    "benefit_number": 22255220,
	"authorization_term": {
		"document_number": "14950479032",
                "legal_representative_document_number": "32866210050", // CPF do representante legal (caso aplicável)
		"signature": {
			"signer": {
				"name": "Nome Cliente",
				"phone": {
					"number": "887577622",
					"area_code": "19",
					"country_code": "55"
				},
				"document_number": "14950479032"
			},
			"authentication_type": "opt_in",
			"authenticity": {
				"timestamp": "2023-12-05T21:04:06",
				"ip_address": "200.223.171.82",
				"fingerprint": {
					"lat": "-44.00524157713981",
					"long": "-19.807649431219804",
					"name": "Nome Cliente",
					"model": "Mozilla/5.0 (iPhone; CPU iPhone OS 16_6_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/16.6 Mobile/15E148 Safari/604.1",
					"localeHashValue": "hash cliente"
				},
				"third_party_additional_data": {},
				"session_id": "b75c7ac2-3be3-41b6-b769-4d982a5824a2"
			},
			"signed_object": {
				"document_key": "cfbc8469-89ea-4a80-9f64-ba7b1566c68b"
			}
		}
	}
}


Atenção

Nos casos em que houver representante legal, é necessário preencher o campo "legal_representative_document_number" com o CPF do representante legal, e os dados do objeto "signer" devem ser preenchidos com os dados do mesmo.

        Response

  • MÉTODO
    POST
  • ENDPOINT
    /social_security/balance_request
body.json

{
    "balance_request_key": "ffda1935-9cad-47df-b848-cd33c96024e4",
    "document_number": "14950479032",
    "status": "pending_authorization",
    "authorization_term": {
        "authorization_term_key": "19196811-366f-4422-a729-4d0aa552449b",
        "status": "signed"
    },
    "status_events": [
        {
            "status": "pending_authorization",
            "event_date": "2023-12-22T16:18:18"
        }
    ]
}

Em caso de sucesso na consulta de dados do benefício

         Webhook

  • WEBHOOK_TYPE
    /social_security/balance_request
  • STATUS
    Success
body.json
{
    "webhook": {
        "key": "ffda1935-9cad-47df-b848-cd33c96024e4",
        "data": {
            "name": "IVOLANDO MIRANDA",
            "state": "SP",
            "alimony": "not_payer",
            "birth_date": "07021961",
            "grant_date": "2022-09-02",
            "credit_type": "checking_account",
            "block_type": "not_blocked",
            "benefit_card": {
                "limit": 2083.2,
                "balance": 0
            },
            "benefit_number": "22255220",
            "benefit_status": "elegible",
            "payroll_card": {
                "limit": 2083.2,
                "balance": 0
            },
            "assistance_type": "retirement_by_age",
            "document_number": "14950479032",
            "benefit_end_date": "2020-12-01",
            "consigned_credit": {
                "balance": 1000
            },
            "benefit_situation": "active",
            "max_total_balance": 2000,
            "used_total_balance": 1000,
            "politically_exposed": {
                "type": "politically_exposed_level_1",
                "is_politically_exposed": true
            },
            "has_power_of_attorney": false,
            "available_total_balance": 1000,
            "has_judicial_concession": false,
            "number_of_portabilities": 0,
            "disbursement_bank_account": {
                "bank_code": "341",
                "account_digit": "6",
                "account_branch": "0155",
                "account_number": "000059923"
            },
            "has_entity_representation": false,
            "social_benefit_max_balance": 2000,
            "social_benefit_used_balance": 1000,
            "benefit_quota_expiration_date": null,
            "number_of_active_reservations": 0,
            "number_of_suspended_reservations": 0,
            "number_of_refinanced_reservations": 0,
            "number_of_active_suspended_reservations": 3
        },
        "status": "success",
        "webhook_type": "social_security_balance_request",
        "event_datetime": "2023-12-22T16:18:21"
    }
}

Detalhamento de campos no webhook de sucesso​

CampoDescriçãoValores
assistance_typeTipo do benefícioEnumeradores
benefit_statusStatus do beneficioEnumeradores
has_entity_representationPossui entidade de representação (não permite averbação)True ou False
alimony_codeClassificador da Pensão alimentícianot_payer, payer, benefit
has_judicial_concessionBenefício concedido por liminarTrue ou False
has_power_of_attorneyPossui procurador?True ou False
credit_typeTipo de crédito - recebimento do benefícioMagnetic_card, checking_account
benefit_situationSituação do benefícioEnumeradores
used_total_balanceValor total comprometido em averbações de empréstimos, reservado para portabilidade, refinanciamento, alterações, RMC e RCCNumérico
max_total_balanceValor comprometido possível para a respectiva espécie do benefícioNumérico
available_total_balanceValor total disponível para empréstimo, somando todas as modalidades (diferença entre max_total_balance e used_total_balance)Numérico
benefit_quota_expiration_dateData de extinção do benefício. A informação está disponível apenas para alguns benefícios de pensão por morte.String ou nulo
block_typeTipo de bloqueio do benefícioEnumeradores
politically_exposed.typePessoa politicamente expostaEnumeradores
is_politically_exposedPessoa politicamente expostaTrue ou False

Em caso de falha na consulta da lista de benefícios

        Webhook

  • WEBHOOK_TYPE
    /social_security/balance_request
  • STATUS
    Failure
body.json
{
    "webhook": {
        "key": "37a14593-b934-457c-8cf6-e51f184b1f1c",
        "data": {
            "enumerator": "inexistent_beneficiary",
            "description": "no beneficiary found"
        },
        "status": "failure",
        "webhook_type": "social_security_balance_request",
        "event_datetime": "2023-12-22T16:22:29"
    }
}

Detalhamento de campos no webhook de falha​

CampoDescriçãoValores
enumeratorRetorno mapeado do código DataprevEnumeradores

Simulando cenários de sucesso e insucesso na consulta de dados do benefício em Sandbox:​

A simulação de cenários é baseado no primeiro dígito do CPF informado na operação.

11.1. Para CPFs iniciados com o número 1, será retornado uma resposta assíncrona de sucesso através do Webhook.

11.2. Para os demais CPFs, será retornado uma resposta assíncrona de erro, baseado no primeiro dígito do CPF digitado, de acordo com a tabela abaixo.

Início do CPFEnumeradorDescrição
2inexistent_beneficiaryno beneficiary found
Atenção

Todos os CPFs que não tiverem um cenário mapeado para o primeiro dígito, receberão um webhook com um erro padrão de cenário de teste não mapeado.

EnumeradorDescrição
mock_errorInformed document number is not a valid mock on test environment

3 - Simulando Proposta de Portabilidade e/ou Refinanciamento:​

Atenção

Para propostas que envolvam troco após o refinanciamento, é necessário o valor do troco calculado de acordo com as condições do contrato seja de pelo menos 5% da diferença entre a soma de todas as parcelas do refinanciamento subtraida da soma de todas as parcelas da portabilidade. Caso contrário, a requisição receberá o seguinte erro:

STATUS
400
Response Body
{
    "title": "Bad Request", 
    "code": "CT000118",
    "description": "The final disbursement amount is less than 5% of the sum of refinancing installment minus the sum of portability installment. The minimum final disbursement amount allowed is 500.00. Calculated final disbursement amount: 400.00.", 
    "translation": "O valor do troco é menor que 5% da soma do valor das parcelas do refinanciamento menos o valor soma das parcelas da portabilidade. O valor mínimo do troco permitido é de 500.00. Valor calculado do troco: 400.00."
}

        3.1. Simulação de Portabilidade com Refinanciamento: Antes de realizar a digitação da Proposta de Portabilidade com Refinanciamento, é possível simular as condições financeiras da proposta, sem a necessidade de coletar os dados cadastrais do cliente.

Ver exemplos de payload (Taxa Fixa / Valor Liberado Fixo)

        3.1.1. Simulação de Portabilidade com Refinanciamento, com taxa fixa: Assim como na Digitação da Proposta (4.1.1), é possível realizar a simulação fixando a taxa do contrato:

        Request

  • MÉTODO
    POST
  • STATUS
    /v2/credit_transfer/proposal_simulation

        Request:

body.json
{
	"borrower": {
		"person_type": "natural"
	},
	"collaterals": [{
		"collateral_type": "social_security"
	}],
	"portability_credit_operation": {
		"financial": {
			"monthly_interest_rate": 0.0132,
			"number_of_installments": 10
		}
	},
	"refinancing_credit_operation": {
		"financial": {
                        "days_to_accrual": 0,
			"monthly_interest_rate": 0.0132,
			"installment_face_value": 100,
			"number_of_installments": 10
		}
	},
	"origin_contract": {
		"last_due_balance": 997.87
	}
}
informação

No payload acima, são descritos os dados mínimos para realização da simulação.

        Response

  • MÉTODO
    POST
  • STATUS
    /v2/credit_transfer/proposal_simulation

        Payload:

response.json

{
    "borrower": {
        "individual_document_number": "98765432100",
        "related_party_key": "fa55dca3-3147-45d2-bb8d-941f2d7191da",
        "role_type": "issuer"
    },
    "portability_credit_operation": {
        "credit_operation_key": "a66675e6-bdc2-4468-8420-2889d5cec0a8",
        "credit_operation_status": "waiting_signature",
        "disbursement_accounts": [],
        "disbursement_options": [
            {
                "annual_cet": 0.173044,
                "cet": 0.0134,
                "contract_fee_amount": 0.0,
                "contract_fees": [
                    {
                        "amount": 0.5,
                        "amount_type": "percentage",
                        "fee_amount": 0.0,
                        "fee_type": "tac"
                    }
                ],
                "disbursed_issue_amount": 997.87,
                "disbursement_date": "2023-12-22",
                "external_contract_fee_amount": 0.0,
                "external_contract_fees": [
                    {
                        "amount": 0.0,
                        "amount_released": 0,
                        "amount_type": "absolute",
                        "cofins_amount": 0,
                        "csll_amount": 0,
                        "description": null,
                        "fee_amount": 0.0,
                        "fee_type": "spread",
                        "irrf_amount": 0,
                        "net_fee_amount": 0.0,
                        "pis_amount": 0,
                        "tax_amount": 0.0
                    },
                    {
                        "amount": 0.0,
                        "amount_released": 0,
                        "amount_type": "absolute",
                        "cofins_amount": 0,
                        "csll_amount": 0,
                        "description": null,
                        "fee_amount": 0.0,
                        "fee_type": "tac",
                        "irrf_amount": 0,
                        "net_fee_amount": 0.0,
                        "pis_amount": 0,
                        "tax_amount": 0.0
                    },
                    {
                        "amount": 0.0,
                        "amount_released": 0,
                        "amount_type": "absolute",
                        "cofins_amount": 0,
                        "csll_amount": 0,
                        "description": null,
                        "fee_amount": 0.0,
                        "fee_type": "insurance_premium",
                        "irrf_amount": 0,
                        "net_fee_amount": 0.0,
                        "pis_amount": 0,
                        "tax_amount": 0.0
                    }
                ],
                "installments": [
                    {
                        "business_due_date": "2024-02-22",
                        "calendar_days": 62,
                        "due_date": "2024-02-22",
                        "due_principal": 997.87,
                        "installment_number": 1,
                        "pre_fixed_amount": 27.413791524708554,
                        "principal_amortization_amount": 81.34620847529145,
                        "total_amount": 108.76,
                        "workdays": 40
                    },
                    {
                        "business_due_date": "2024-03-22",
                        "calendar_days": 29,
                        "due_date": "2024-03-22",
                        "due_principal": 916.5237915247086,
                        "installment_number": 2,
                        "pre_fixed_amount": 11.692366920719124,
                        "principal_amortization_amount": 97.06763307928088,
                        "total_amount": 108.76,
                        "workdays": 21
                    },
                    {
                        "business_due_date": "2024-04-22",
                        "calendar_days": 31,
                        "due_date": "2024-04-22",
                        "due_principal": 819.4561584454277,
                        "installment_number": 3,
                        "pre_fixed_amount": 11.179911547915339,
                        "principal_amortization_amount": 97.58008845208467,
                        "total_amount": 108.76,
                        "workdays": 20
                    },
                    {
                        "business_due_date": "2024-05-22",
                        "calendar_days": 30,
                        "due_date": "2024-05-22",
                        "due_principal": 721.876069993343,
                        "installment_number": 4,
                        "pre_fixed_amount": 9.5288330736045,
                        "principal_amortization_amount": 99.2311669263955,
                        "total_amount": 108.76,
                        "workdays": 21
                    },
                    {
                        "business_due_date": "2024-06-24",
                        "calendar_days": 33,
                        "due_date": "2024-06-24",
                        "due_principal": 622.6449030669476,
                        "installment_number": 5,
                        "pre_fixed_amount": 9.046812945831448,
                        "principal_amortization_amount": 99.71318705416856,
                        "total_amount": 108.76,
                        "workdays": 22
                    },
                    {
                        "business_due_date": "2024-07-22",
                        "calendar_days": 28,
                        "due_date": "2024-07-22",
                        "due_principal": 522.9317160127789,
                        "installment_number": 6,
                        "pre_fixed_amount": 6.439743824282488,
                        "principal_amortization_amount": 102.32025617571752,
                        "total_amount": 108.76,
                        "workdays": 20
                    },
                    {
                        "business_due_date": "2024-08-22",
                        "calendar_days": 31,
                        "due_date": "2024-08-22",
                        "due_principal": 420.61145983706143,
                        "installment_number": 7,
                        "pre_fixed_amount": 5.738438681013405,
                        "principal_amortization_amount": 103.0215613189866,
                        "total_amount": 108.76,
                        "workdays": 23
                    },
                    {
                        "business_due_date": "2024-09-23",
                        "calendar_days": 32,
                        "due_date": "2024-09-23",
                        "due_principal": 317.58989851807485,
                        "installment_number": 8,
                        "pre_fixed_amount": 4.473657660291388,
                        "principal_amortization_amount": 104.28634233970861,
                        "total_amount": 108.76,
                        "workdays": 22
                    },
                    {
                        "business_due_date": "2024-10-22",
                        "calendar_days": 29,
                        "due_date": "2024-10-22",
                        "due_principal": 213.30355617836625,
                        "installment_number": 9,
                        "pre_fixed_amount": 2.721176981322744,
                        "principal_amortization_amount": 106.03882301867725,
                        "total_amount": 108.76,
                        "workdays": 21
                    },
                    {
                        "business_due_date": "2024-11-22",
                        "calendar_days": 31,
                        "due_date": "2024-11-22",
                        "due_principal": 107.26473315968899,
                        "installment_number": 10,
                        "pre_fixed_amount": 1.4934220715493307,
                        "principal_amortization_amount": 107.26657792845067,
                        "total_amount": 108.76,
                        "workdays": 22
                    }
                ],
                "issue_amount": 997.87,
                "number_of_installments": 10,
                "prefixed_interest_rate": {
                    "annual_rate": 0.17042118,
                    "daily_rate": 0.00043722,
                    "interest_base": "calendar_days",
                    "monthly_rate": 0.0132
                },
                "total_iof": 0.0
            }
        ],
        "final_disbursement_amount": 0.0
    },
    "proposal_key": "28a925f6-570e-4724-9132-3bd42f267c4f",
    "proposal_number": "17032788499215403",
    "proposal_status": "pending_submission",
    "refinancing_credit_operation": {
        "credit_operation_key": "aaf9abe0-2b8a-4688-8e09-413e1bd5285e",
        "credit_operation_status": "waiting_signature",
        "disbursement_accounts": [],
        "disbursement_options": [
            {
                "annual_cet": 0.172031,
                "cet": 0.0133,
                "contract_fee_amount": -0.4,
                "contract_fees": [
                    {
                        "amount": 0.5,
                        "amount_type": "percentage",
                        "fee_amount": -0.4,
                        "fee_type": "tac"
                    }
                ],
                "disbursed_issue_amount": 918.04,
                "disbursement_date": "2023-12-22",
                "external_contract_fee_amount": 0.0,
                "external_contract_fees": [
                    {
                        "amount": 0.0,
                        "amount_released": 0,
                        "amount_type": "absolute",
                        "cofins_amount": 0,
                        "csll_amount": 0,
                        "description": null,
                        "fee_amount": 0.0,
                        "fee_type": "spread",
                        "irrf_amount": 0,
                        "net_fee_amount": 0.0,
                        "pis_amount": 0,
                        "tax_amount": 0.0
                    },
                    {
                        "amount": 0.0,
                        "amount_released": 0,
                        "amount_type": "absolute",
                        "cofins_amount": 0,
                        "csll_amount": 0,
                        "description": null,
                        "fee_amount": 0.0,
                        "fee_type": "tac",
                        "irrf_amount": 0,
                        "net_fee_amount": 0.0,
                        "pis_amount": 0,
                        "tax_amount": 0.0
                    },
                    {
                        "amount": 0.0,
                        "amount_released": 0,
                        "amount_type": "absolute",
                        "cofins_amount": 0,
                        "csll_amount": 0,
                        "description": null,
                        "fee_amount": 0.0,
                        "fee_type": "insurance_premium",
                        "irrf_amount": 0,
                        "net_fee_amount": 0.0,
                        "pis_amount": 0,
                        "tax_amount": 0.0
                    }
                ],
                "installments": [
                    {
                        "business_due_date": "2024-02-22",
                        "calendar_days": 62,
                        "due_date": "2024-02-22",
                        "due_principal": 917.64,
                        "installment_number": 1,
                        "pre_fixed_amount": 25.2095730147,
                        "principal_amortization_amount": 74.7904269853,
                        "total_amount": 100.0,
                        "workdays": 40
                    },
                    {
                        "business_due_date": "2024-03-22",
                        "calendar_days": 29,
                        "due_date": "2024-03-22",
                        "due_principal": 842.8495730147,
                        "installment_number": 2,
                        "pre_fixed_amount": 10.7524369787,
                        "principal_amortization_amount": 89.2475630213,
                        "total_amount": 100.0,
                        "workdays": 21
                    },
                    {
                        "business_due_date": "2024-04-22",
                        "calendar_days": 31,
                        "due_date": "2024-04-22",
                        "due_principal": 753.6020099934,
                        "installment_number": 3,
                        "pre_fixed_amount": 10.2814172859,
                        "principal_amortization_amount": 89.7185827141,
                        "total_amount": 100.0,
                        "workdays": 20
                    },
                    {
                        "business_due_date": "2024-05-22",
                        "calendar_days": 30,
                        "due_date": "2024-05-22",
                        "due_principal": 663.8834272793,
                        "installment_number": 4,
                        "pre_fixed_amount": 8.7632941742,
                        "principal_amortization_amount": 91.2367058258,
                        "total_amount": 100.0,
                        "workdays": 21
                    },
                    {
                        "business_due_date": "2024-06-24",
                        "calendar_days": 31,
                        "due_date": "2024-06-22",
                        "due_principal": 572.6467214535,
                        "installment_number": 5,
                        "pre_fixed_amount": 7.8126464787,
                        "principal_amortization_amount": 92.1873535213,
                        "total_amount": 100.0,
                        "workdays": 21
                    },
                    {
                        "business_due_date": "2024-07-22",
                        "calendar_days": 30,
                        "due_date": "2024-07-22",
                        "due_principal": 480.4593679322,
                        "installment_number": 6,
                        "pre_fixed_amount": 6.3420966342,
                        "principal_amortization_amount": 93.6579033658,
                        "total_amount": 100.0,
                        "workdays": 21
                    },
                    {
                        "business_due_date": "2024-08-22",
                        "calendar_days": 31,
                        "due_date": "2024-08-22",
                        "due_principal": 386.8014645664,
                        "installment_number": 7,
                        "pre_fixed_amount": 5.2771618926,
                        "principal_amortization_amount": 94.7228381074,
                        "total_amount": 100.0,
                        "workdays": 23
                    },
                    {
                        "business_due_date": "2024-09-23",
                        "calendar_days": 31,
                        "due_date": "2024-09-22",
                        "due_principal": 292.078626459,
                        "installment_number": 8,
                        "pre_fixed_amount": 3.9848593609,
                        "principal_amortization_amount": 96.0151406391,
                        "total_amount": 100.0,
                        "workdays": 21
                    },
                    {
                        "business_due_date": "2024-10-22",
                        "calendar_days": 30,
                        "due_date": "2024-10-22",
                        "due_principal": 196.0634858199,
                        "installment_number": 9,
                        "pre_fixed_amount": 2.5880710578,
                        "principal_amortization_amount": 97.4119289422,
                        "total_amount": 100.0,
                        "workdays": 22
                    },
                    {
                        "business_due_date": "2024-11-22",
                        "calendar_days": 31,
                        "due_date": "2024-11-22",
                        "due_principal": 98.6515568777,
                        "installment_number": 10,
                        "pre_fixed_amount": 1.3459361963,
                        "principal_amortization_amount": 98.6540638037,
                        "total_amount": 100.0,
                        "workdays": 22
                    }
                ],
                "issue_amount": 917.64,
                "number_of_installments": 10,
                "prefixed_interest_rate": {
                    "annual_rate": 0.17042118,
                    "daily_rate": 0.00043722,
                    "interest_base": "calendar_days",
                    "monthly_rate": 0.0132
                },
                "total_iof": 0.0
            }
        ],
        "final_disbursement_amount": -79.83
    }
}

        3.2. Simulação de Portabilidade: Também é possível simular as condições financeiras de uma Proposta de Portabilidade (Portabilidade Pura), sem a necessidade de coletar os dados cadastrais do cliente.

        Request

  • MÉTODO
    POST
  • STATUS
    /v2/credit_transfer/proposal_simulation

        Payload:

payload.json
{
	"borrower": {
		"person_type": "natural"
	},
	"collaterals": [{
		"collateral_type": "social_security"
	}],
	"portability_credit_operation": {
		"financial": {
			"monthly_interest_rate": 0.0132,
			"installment_face_value": 100,
			"number_of_installments": 10
		}
	},
	"origin_contract": {
		"last_due_balance": 997.87
	}
}

        Response

  • MÉTODO
    POST
  • STATUS
    /v2/credit_transfer/proposal_simulation

        Payload:

payload.json
{
	"portability_credit_operation": {
		"fine_configuration": {
			"contract_fine_rate": 0.02,
			"interest_base": "calendar_days",
			"monthly_rate": 0.01
		},
		"disbursement_options": [{
			"installments": [{
					"bank_slip_key": null,
					"digitable_line": null,
					"business_due_date": "2021-08-09",
					"calendar_days": 53,
					"due_date": "2021-08-08",
					"due_principal": 997.87,
					"installment_key": "e3bedf31-1e87-4ba4-a36c-d52f7f5c9036",
					"installment_number": 1,
					"pre_fixed_amount": 54.84865004983954,
					"principal_amortization_amount": 306.98134995016045,
					"total_amount": 361.83,
					"workdays": 37
				},
				{
					"bank_slip_key": null,
					"digitable_line": null,
					"business_due_date": "2021-09-08",
					"calendar_days": 31,
					"due_date": "2021-09-08",
					"due_principal": 690.89,
					"installment_key": "e8406cdb-844c-4e6d-9620-3635fab9d8d1",
					"installment_number": 2,
					"pre_fixed_amount": 21.964874249804833,
					"principal_amortization_amount": 339.86512575019515,
					"total_amount": 361.83,
					"workdays": 22
				}
			],
			"prefixed_interest_rate": {
				"annual_rate": 0.44556431,
				"daily_rate": 0.00564312,
				"monthly_rate": 0.0556431,
				"interest_base": "calendar_days_365"
			},
			"iof_amount": 0,
			"external_contract_fee_amount": 0,
			"external_contract_fees": [],
			"contract_fee_amount": 0,
			"contract_fees": [],
			"number_of_installments": 2,
			"disbursed_issue_amount": 1000,
			"issue_amount": 1000,
			"disbursement_date": "2021-05-31",
			"cet": 1.212,
			"annual_cet": 32.122
		}]
	}
}

4 - Digitação da Proposta:​

Atenção

Para que os pedidos de averbação, tanto da portabilidade, como do refinanciamento sejam criados com sucesso, é preciso que seja feita uma consulta de dados válida para o benefício previamente. Para isso basta seguir os passos do item 2 - Consulta de dados do benefício.

Assinatura em grupo (opcional)

Para reunir esta proposta com outras operações INSS do mesmo beneficiário e coletar uma única assinatura, envie document_batch_group_key na raiz do payload de criação da proposta. Nesse caso, a resposta não retorna signature_information — o link de assinatura é único e obtido no envio do grupo para assinatura. Consulte o fluxo de Assinatura em grupo.

Falha na averbação por falta de uma consulta de dados válida do benefício​

Se uma consulta dos dados do benefício não for realizada com sucesso antes do pedido de averbação, o status do pedido de averbação ficará como "aguardando ação do parceiro" e será enviado um webhook no seguinte formato para informar o ocorrido:

WEBHOOK_TYPE
social_security_success_balance_request_not_found
STATUS
Pending requester action
Webhook Body
{
    "webhook": {
        "key": "\<DEBT-KEY\>",
        "data": {
            "enumerator": "success_balance_request_not_found",
            "description": "Success balance request not found for the specified benefit number"
        },
        "status": "pending_requester_action",
        "webhook_type": "social_security_success_balance_request_not_found",
        "event_datetime": "2024-02-26T21:36:22"
    }
}

Para prosseguir, as seguintes ações deverão ser tomadas:

  1. Realizar a consulta dos dados do benefício em questão seguindo os passos do item 2 - Consulta de dados do benefício;
  2. Enviar uma requisição no formato abaixo para informar que a consulta foi realizada.
ENDPOINT
/social_security/reservation/external_key/DEBT-KEY/validate_reservation
MÉTODO
POST
Testar no Playground
Importante

Essa requisição não apenas confirma a existência de uma consulta válida dos dados do benefício, mas também verifica se as informações enviadas para a criação da averbação estão corretas, permitindo assim a continuidade do processo.

4.1. Digitação da Proposta de Portabilidade com Refinanciamento: Essa forma de digitação é utilizada para realizar a portabilidade de um contrato de crédito, liberando, ao final, mais dinheiro para o devedor. O valor liberado após a portabilidade é chamado de "Troco". A Proposta de Portabilidade e a Proposta de Refinanciamento podem ser geradas em uma mesma Request.

Para a digitação da proposta devem ser enviadas as seguintes informações:

  • Dados cadastrais do tomador do crédito.

  • Dados cadastrais do Representante Legal (caso aplicável).

  • Dados financeiros da operação de portabilidade informando sempre o número de parcelas e uma das opções entre taxa de juros e valor de face da parcela.

  • Dados financeiros da operação de refinanciamento (operação que quita a operação de portabilidade e libera o troco) juntamente com os dados de conta bancária para pagamento do troco, conforme retornado na consulta dos dados do benefício.

  • Agente de crédito responsável pela originação da proposta, também conhecido como 'pastinha.

  • Saldo devedor, número do contrato original e ispb do credor original. Como a operação de Refinanciamento não possui data de desembolso fixa, a mudança na data de desembolso altera os valores da operação, sendo necessário informar se a taxa ("monthly_interest_rate") deve ser fixa ou se o valor liberado ao cliente ("disbursed_amount") deve ser fixo.

Caso a proposta seja de cliente analfabeto, os dados do rogado e testemunhas devem ser enviados no campo additional_data do payload de criação da proposta. Porém, deve ser previamente alinhado com a QI Tech quais informações e formato serão utilizados

Ver exemplos de payload (Taxa Fixa / Valor Liberado Fixo)

        4.1.1. Digitação da Proposta de Portabilidade com Refinanciamento com taxa fixa: Segue abaixo, exemplo de digitação da proposta fixando a taxa da operação:

        Request

  • MÉTODO
    POST
  • STATUS
    /v2/credit_transfer/proposal
Testar no Playground

        Payload:

Request Body

{
    "proposal_type": "inss",
    "purchaser_document_number": "32402502000135",
    "credit_agent": {
        "document_number": "87237271016",
        "name": "Agente de credito"
    },
    "borrower": {
        "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": "elaineisadoradacruz@hotmal.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"
        },
        "document_identification": "8b0d8c33-01c9-4cf5-a0fa-1d2a96f4b34d",
        "document_identification_back": "7b8f7848-78b5-405b-a62c-f23a432fde1a",
        "selfie": "2a2d000e-9f2b-4c4e-95f9-1561950db076"
    },
    "related_parties": [
        {
            "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": "20676928013",
            "document_identification": "359530eb-41dc-41bd-8385-b86d6bd6e650",
            "document_identification_type": "rg",
            "document_identification_back": "ae320312-532c-467c-b11f-48e3ec87452b",
            "document_identification_number": "123456789",
            "selfie": "f28e1a70-32e8-4620-9d72-c89ac8c7adb1"
        }
    ],
    "collaterals": [
        {
            "collateral_type": "social_security",
            "collateral_data": {
                "benefit_number": "22255220",
                "state": "SP",
            "subcorban_document_number": "12123456000101"
            }
        }
    ],
    "portability_credit_operation": {
        "financial": {
            "monthly_interest_rate": 0.0132,
            "number_of_installments": 10
        },
        "contract_number": "300523588BF"
    },
    "refinancing_credit_operation": {
        "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": "200523588BF"
    },
    "origin_contract": {
        "ispb": "60746948",
        "contract_number": "558472",
        "last_due_balance": 997.87
    },
    "additional_data": {}
}



Carência

Conforme mudança da IN 204, a partir de 19/05, as operações poderão ter carência. Para tal, basta digitar dentro do "collateral_data" o campo "number_of_grace_periods". contendo o valor do número de meses desejados de carência, como no exemplo abaixo:

"collaterals": [
    {
        "collateral_type": "social_security",
        "collateral_data": {
            "benefit_number": "22255220",
            "state": "RS",
            "number_of_grace_periods": 3,
            "subcorban_document_number": "12123456000101"
        }
    }
]
Atenção

A lista "related_parties", só deve ser enviada caso seja uma operação com Representante Legal. Quando enviado, deve conter os dados cadastrais do representante legal e o campo "role_type" deve ser enviado contendo o valor: "issuer_legal_representative".

informação

No campo "origin_contract.ispb" é informado o ISPB da instituição Credora Original. O ISPB é a base do CNPJ da instituição. Para ter acesso à lista completa de ISPB's de cada instituição participante do CTC - CIP (Central de Transferência de Crédito), basta utilizar o endpoint de consulta de participantes do CTC (índice):

        4.1.3. Response

  • MÉTODO
    POST
  • STATUS
    /v2/credit_transfer/proposal
body.json
{
    "borrower": {
        "individual_document_number": "90406718261",
        "name": "Elaine Isadora da Cruz",
        "related_party_key": "d7f84a9d-28ba-4355-8e5e-a436ff4c3c2d",
        "role_type": "issuer"
    },
    "portability_credit_operation": {
        "collateral_is_constituted": false,
        "contract_number": "3635259611",
        "credit_operation_key": "235ce3a5-eea1-4b13-9335-3de577318f8b",
        "credit_operation_status": "waiting_signature",
        "disbursement_accounts": [],
        "disbursement_options": [
            {
                "annual_cet": 0.17295,
                "cet": 0.0134,
                "contract_fee_amount": 0.0,
                "contract_fees": [
                    {
                        "amount": 0.5,
                        "amount_type": "percentage",
                        "fee_amount": 0.0,
                        "fee_type": "tac"
                    }
                ],
                "disbursed_issue_amount": 800.0,
                "disbursement_date": "2023-12-22",
                "external_contract_fee_amount": 0.0,
                "external_contract_fees": [
                    {
                        "amount": 0.0,
                        "amount_released": 0,
                        "amount_type": "absolute",
                        "cofins_amount": 0,
                        "csll_amount": 0,
                        "description": null,
                        "fee_amount": 0.0,
                        "fee_type": "spread",
                        "irrf_amount": 0,
                        "net_fee_amount": 0.0,
                        "pis_amount": 0,
                        "tax_amount": 0.0
                    },
                    {
                        "amount": 0.0,
                        "amount_released": 0,
                        "amount_type": "absolute",
                        "cofins_amount": 0,
                        "csll_amount": 0,
                        "description": null,
                        "fee_amount": 0.0,
                        "fee_type": "tac",
                        "irrf_amount": 0,
                        "net_fee_amount": 0.0,
                        "pis_amount": 0,
                        "tax_amount": 0.0
                    },
                    {
                        "amount": 0.0,
                        "amount_released": 0,
                        "amount_type": "absolute",
                        "cofins_amount": 0,
                        "csll_amount": 0,
                        "description": null,
                        "fee_amount": 0.0,
                        "fee_type": "insurance_premium",
                        "irrf_amount": 0,
                        "net_fee_amount": 0.0,
                        "pis_amount": 0,
                        "tax_amount": 0.0
                    }
                ],
                "installments": [
                    {
                        "business_due_date": "2024-02-22",
                        "calendar_days": 62,
                        "due_date": "2024-02-22",
                        "due_principal": 800.0,
                        "installment_number": 1,
                        "pre_fixed_amount": 21.977846031814607,
                        "principal_amortization_amount": 65.21215396818539,
                        "total_amount": 87.19,
                        "workdays": 40
                    },
                    {
                        "business_due_date": "2024-03-22",
                        "calendar_days": 29,
                        "due_date": "2024-03-22",
                        "due_principal": 734.7878460318146,
                        "installment_number": 2,
                        "pre_fixed_amount": 9.373907348762184,
                        "principal_amortization_amount": 77.81609265123781,
                        "total_amount": 87.19,
                        "workdays": 21
                    },
                    {
                        "business_due_date": "2024-11-22",
                        "calendar_days": 31,
                        "due_date": "2024-11-22",
                        "due_principal": 86.03031050776795,
                        "installment_number": 10,
                        "pre_fixed_amount": 1.1637189988799015,
                        "principal_amortization_amount": 86.0262810011201,
                        "total_amount": 87.19,
                        "workdays": 22
                    }
                ],
                "issue_amount": 800.0,
                "number_of_installments": 10,
                "prefixed_interest_rate": {
                    "annual_rate": 0.17042118,
                    "daily_rate": 0.00043722,
                    "interest_base": "calendar_days",
                    "monthly_rate": 0.0132
                },
                "total_iof": 0.0
            }
        ],
        "document_key": "c4cedeaf-23bf-450d-9fba-5ec6b5d45afb",
        "document_url": "https://storage.googleapis.com/sandbox-doc-api/documents/c4cedeaf-23bf-450d-9fba-5ec6b5d45afb/TESTEINSSS.A.-ELAINEISADORADACRUZ-CCB-3635259611.pdf",
        "final_disbursement_amount": 0.0
    },
    "proposal_key": "2f7e320c-2a35-4e78-bfd7-a298b28a7497",
    "proposal_number": "17032782193414588",
    "proposal_status": "pending_submission",
    "refinancing_credit_operation": {
        "collateral_is_constituted": false,
        "contract_number": "3635259663",
        "credit_operation_key": "f73ba4d2-cd0a-4405-a47e-a51f325a9756",
        "credit_operation_status": "waiting_signature",
        "disbursement_accounts": [
            {
                "account_branch": "0001",
                "account_digit": "1",
                "account_number": "00001",
                "bank_code": "033"
            }
        ],
        "disbursement_options": [
            {
                "annual_cet": 0.193423,
                "cet": 0.0148,
                "contract_fee_amount": 1.03,
                "disbursed_issue_amount": 1000.0,
                "disbursement_date": "2023-12-22",
                "issue_amount": 1005.24,
                "number_of_installments": 10,
                "final_disbursement_amount": 200.0
            }
        ],
        "document_key": "f4dfb505-3cec-4a97-9b16-dadc39bb4c7e",
        "document_url": "https://storage.googleapis.com/sandbox-doc-api/documents/f4dfb505-3cec-4a97-9b16-dadc39bb4c7e/TESTEINSSS.A.-ELAINEISADORADACRUZ-CCB-3635259663.pdf",
        "final_disbursement_amount": 200.0
    },
    "related_party_list": [
        {
            "individual_document_number": "45102538004",
            "name": "Nome Representante Legal",
            "related_party_key": "632fa6c5-40e8-4e76-862e-e10951ed8bff",
            "role_type": "issuer_legal_representative"
        }
    ]
}

Segue abaixo definições e descrições de alguns campos retornados na resposta da digitação da Proposta:

[A]: "portability_credit_operation.disbursement_options.iof_amount": Na Operação de Portabilidade o IOF sempre será zero.

[B]: "portability_credit_operation.disbursement_options.disbursed_issue_amount": É igual ao valor do saldo devedor do Contrato Original.

[C]: "portability_credit_operation.disbursement_options.issue_amount": É o valor da Operação de Portabilidade.

Relação
[C] = [A] + [B]

[D]: "refinancing_credit_operation.disbursement_options.iof_amount": Valor de IOF da Operação de Refinanciamento (Troco).

[E]: "refinancing_credit_operation.disbursement_options.disbursed_issue_amount": É o valor destinado à quitação do saldo devedor da Operação de Portabilidade.

Relação
[E] = [C]

[F]: "refinancing_credit_operation.disbursement_options.final_disbursement_amount": É o valor do Troco liberado para o cliente na conta de desembolso informada no momento da digitação da Proposta (deve ser a conta informação da consulta dos dados do benefício).

[G]: "refinancing_credit_operation.disbursement_options.issue_amount": É o valor do Refinanciamento.

Relação
[G] = [F] + [E] + [D]

Os campos "portability_credit_operation.disbursement_options.collateral_constituted" e "refinancing_credit_operation.disbursement_options.collateral_constituted" informam se a margem do cliente esta averbada na Dataprev. O processo de averbação da Portabilidade será iniciado assim que os recursos para quitação do contrato original forem enviados a Instituição Credora Original (Item 6.4.). O Processo de averbação do Refinanciamento é iniciado no momento em que o Parceiro decide por prosseguir com a Operação de Refinanciamento (Item 7.1.1. e 7.2.).

        4.2. Digitação da Proposta de Portabilidade:

        A Proposta de Portabilidade (Portabilidade Pura) deve ser digitada de forma semelhante ao descrito no item 4.1.1, porém deve ser enviada sem o objeto "refinancing_credit_operation".

        Request

  • MÉTODO
    POST
  • STATUS
    /v2/credit_transfer/proposal
body.json

{
	"proposal_type": "inss",
	"purchaser_document_number": "32402502000135",
    "credit_agent": {
        "document_number": "87237271016",
        "name": "Agente de credito"
    },
	"borrower": {
		"person_type": "natural",
		"name": "Elaine Isadora da Cruz",
		"mother_name": "Maria Mariane",
		"birth_date": "1990-05-06",
        "gender": "female",
		"profession": "Desenvolvedora",
		"nationality": "Brasileira",
		"marital_status": "single",
		"is_pep": false,
		"individual_document_number": "90406718261",
		"document_identification_number": "381803326",
        "document_identification_type": "rg",
         "document_identification_date": "2019-01-28",
		"email": "elaineisadoradacruz@hotmal.com",
		"phone": {
			"country_code": "055",
			"area_code": "11",
			"number": "996363253"
		},
		"address": {
			"street": "Passagem Mariana",
			"state": "PA",
			"city": "Ananindeua",
			"neighborhood": "Aguas Lindas",
			"number": "660",
			"postal_code": "67118003",
			"complement": "complemento"
		},
		"document_identification": "8b0d8c33-01c9-4cf5-a0fa-1d2a96f4b34d",
		"document_identification_back": "7b8f7848-78b5-405b-a62c-f23a432fde1a",
		"selfie": "2a2d000e-9f2b-4c4e-95f9-1561950db076"
	},
	"related_parties": [{
		"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": "359530eb-41dc-41bd-8385-b86d6bd6e650",
        "document_identification_type": "rg",
		"document_identification_back": "ae320312-532c-467c-b11f-48e3ec87452b",
        "document_identification_number": "123456789",
		"selfie": "f28e1a70-32e8-4620-9d72-c89ac8c7adb1"
	}],
	"collaterals": [{
		"collateral_type": "social_security",
		"collateral_data": {
			"benefit_number": "12345678",
			"state": "SP",
            "subcorban_document_number": "12123456000101"
		}
	}],
	"portability_credit_operation": {
		"financial": {
			"monthly_interest_rate": 0.0132,
			"number_of_installments": 10
		},
		"contract_number": "1020252636"
	},

	"origin_contract": {
		"ispb": "60746948",
		"contract_number": "558474520",
		"last_due_balance": 800
	},
    "additional_data": {}
}

        Response

  • MÉTODO
    POST
  • STATUS
    /v2/credit_transfer/proposal

        Payload:

payload.json
{
    "borrower": {
        "individual_document_number": "90406718261",
        "name": "Elaine Isadora da Cruz",
        "related_party_key": "f9fbaa93-4d57-494f-b60f-dcba8cb64a45",
        "role_type": "issuer"
    },
    "portability_credit_operation": {
        "collateral_is_constituted": false,
        "contract_number": "1020252636",
        "credit_operation_key": "1cd34a63-5a61-49a3-90a5-7a515ee98932",
        "credit_operation_status": "waiting_signature",
        "disbursement_accounts": [],
        "disbursement_options": [
            {
                "annual_cet": 0.17295,
                "cet": 0.0134,
                "disbursed_issue_amount": 800.0,
                "disbursement_date": "2023-12-22",
                "issue_amount": 800.0,
                "number_of_installments": 10,
                "prefixed_interest_rate": {
                    "annual_rate": 0.17042118,
                    "daily_rate": 0.00043722,
                    "interest_base": "calendar_days",
                    "monthly_rate": 0.0132
                },
                "total_iof": 0.0
            }
        ],
        "document_key": "2f9ac920-a5e8-4386-b049-dc971e1fc20b",
        "document_url": "https://storage.googleapis.com/sandbox-doc-api/documents/2f9ac920-a5e8-4386-b049-dc971e1fc20b/TESTEINSSS.A.-ELAINEISADORADACRUZ-CCB-1020252636.pdf",
        "final_disbursement_amount": 0.0
    },
    "proposal_key": "9661aef8-e897-4405-a44f-ca8a43d9cee3",
    "proposal_number": "17032785232138245",
    "proposal_status": "pending_submission",
    "related_party_list": [
        {
            "individual_document_number": "45102538004",
            "name": "Nome Representante Legal",
            "related_party_key": "c8166f37-b496-455a-96e7-f75e24f084a1",
            "role_type": "issuer_legal_representative"
        }
    ]
}

        4.3. Recuperando dados de uma proposta:

  • MÉTODO
    GET
  • STATUS
    /v2/credit_transfer/proposal/PROPOSAL-KEY ou REQUESTER_CONTROL_KEY

Path Params​

CampoTipoDescriçãoCaracteres
proposal_keystringChave identificadora da proposta-
requester_control_keystringChave identificadora do cliente para recuperar os dados de uma proposta (casos de timeout ou operação duplicada), enviar no lugar da proposal_key-

        Response:

response.json

{
    "borrower": {
        "address": {
            "city": "SAO PAULO",
            "complement": "Moradia",
            "neighborhood": "CENTRO",
            "number": "10",
            "postal_code": "01153000",
            "state": "SP",
            "street": "RUA CENTRAL"
        },
        "birth_date": "1976-05-25",
        "document_identification_number": "306385466",
        "email": "ivanete@windowslive.com",
        "individual_document_number": "25500337874",
        "is_pep": false,
        "marital_status": "single",
        "mother_name": "EDITE MARIA DANTAS",
        "name": "IVANETE SATURNINO DE SOUZA",
        "nationality": "Brasleira",
        "person_type": "natural",
        "phone": {
            "area_code": "11",
            "country_code": "055",
            "number": "985814768"
        },
        "profession": "Aposentado",
        "related_party_key": "511d7186-3c17-4f35-8887-c4aefaf270be",
        "role_type": "issuer"
    },
    "collaterals": [
        {
            "collateral_data": {
                "benefit_number": 2045043317,
                "state": "SP"
            },
            "collateral_type": "social_security"
        }
    ],
    "origin_operation": {
        "contract_date": "2025-06-02",
        "contract_number": "0123489618691",
        "financial_institution_code_number": "237",
        "installment_number": 84,
        "ispb_number": "60746948",
        "last_due_balance": 17879.22,
        "opened_installment_number": 67,
        "overdue_installment_number": 0
    },
    "portability_credit_operation": {
        "collateral_is_constituted": false,
        "contract_number": "CTC0000024971",
        "credit_operation_key": "e5bfbd28-0144-4eaa-b7f1-d0efb0b6b155",
        "credit_operation_status": "waiting_signature",
        "disbursement_accounts": [],
        "disbursement_options": [
            {
                "annual_cet": 0.2321,
                "cet": 0.0175,
                "disbursed_issue_amount": 17879.22,
                "disbursement_date": "2025-06-02",
                "issue_amount": 17879.22,
                "number_of_installments": 67,
                "prefixed_interest_rate": {
                    "annual_rate": 0.2285378296,
                    "daily_rate": 0.0005718988,
                    "interest_base": "calendar_days",
                    "monthly_rate": 0.0173
                },
                "total_iof": 0
            }
        ],
        "document_key": "f85d9799-e29f-4133-80c3-3e95f16f2a54",
        "document_url": "https://storage.googleapis.com/sandbox-doc-api/documents/f85d9799-e29f-4133-80c3-3e95f16f2a54/MMRIOLTDA-IVANETESATURNINODESOUZA-CCB-CTC0000024971.pdf",
        "final_disbursement_amount": 17879.22
    },
    "proposal_key": "1e1d3f4d-21aa-4b6f-8515-6d978dc2afa5",
    "proposal_number": "17488903030996687",
    "proposal_status": "pending_submission",
    "refinancing_credit_operation": {
        "collateral_is_constituted": false,
        "contract_number": "CTC0000024972",
        "credit_operation_key": "7cc4d931-34d5-4b03-b04b-9ae4b6721f45",
        "credit_operation_status": "waiting_signature",
        "disbursement_accounts": [
            {
                "account_branch": "1261",
                "account_digit": "1",
                "account_number": "000062293",
                "bank_code": "237"
            }
        ],
        "disbursement_options": [
            {
                "annual_cet": 0.2517,
                "cet": 0.0189,
                "disbursed_issue_amount": 20373.27,
                "disbursement_date": "2025-06-02",
                "final_disbursement_amount": 2494.05,
                "issue_amount": 20458.57,
                "number_of_installments": 96,
                "prefixed_interest_rate": {
                    "annual_rate": 0.2460411933,
                    "daily_rate": 0.0006112186,
                    "interest_base": "calendar_days",
                    "monthly_rate": 0.0185
                },
                "total_iof": 85.3
            }
        ],
        "document_key": "60763cba-da54-4826-bf76-b8f3d26c6326",
        "document_url": "https://storage.googleapis.com/sandbox-doc-api/documents/60763cba-da54-4826-bf76-b8f3d26c6326/MMRIOLTDA-A-CCB-CTC0000024972.pdf",
        "final_disbursement_amount": 2494.05
    },
    "requester_control_key": "0e856d23-0746-4444-a71a-2957a64c869a"
}

informação

No caso da recuperação dos dados de uma proposta de portabilidade pura o objeto "refinancing_credit_operation" não será retornado.

Correção de dados para refinanciamento com nova assinatura da CCB:​

É possível corrigir os dados financeiros e os bancários da operação de refinanciamento enquanto o refinanciamento original não for averbado.

ENDPOINT
/v2/credit_transfer/proposal/PROPOSAL-KEY/refinancing_credit_operation
MÉTODO
PUT
Testar no Playground
Request Body
{
    "financial": {
        "interest_type": "pre_price_days",
        "first_due_date": "2024-06-10",
        "fine_configuration": {
            "monthly_rate": 0.01,
            "interest_base": "calendar_days",
            "contract_fine_rate": 0.02
        },
        "credit_operation_type": "ccb",
        "monthly_interest_rate": 0.0167,
        "installment_face_value": 410,
        "limit_days_to_disburse": 7,
        "number_of_installments": 84
		},
    "disbursement_bank_account": {
        "account_digit": "1",
        "account_number": "00001",
        "bank_code": "033",
        "branch_number": "0001"
    }
}

        Response:

response.json


{
	"credit_operation_key": "\<CREDIT-OPERATION-KEY\>",
	"contract_number": "00000002",
	"document_key": "\<DOCUMENT-KEY da CCB de Refinanciamento\>",
	"document_url": "\<URL da CCB de Refinanciamento\>",
	"credit_operation_status": "issued",
	"fine_configuration": {
		"contract_fine_rate": 0.02,
		"interest_base": "calendar_days",
		"monthly_rate": 0.01
	},
	"disbursement_options": [{
		"installments": [{
				"additional_costs": [],
				"bank_slip_key": null,
				"business_due_date": "2021-08-09",
				"calendar_days": 53,
				"digitable_line": null,
				"due_date": "2021-08-08",
				"due_interest": 0,
				"due_principal": 997.87,
				"fine_amount": null,
				"has_interest": true,
				"installment_key": "e3bedf31-1e87-4ba4-a36c-d52f7f5c9036",
				"installment_number": 1,
				"installment_status": "created",
				"installment_type": "principal",
				"paid_amount": 0,
				"paid_at": null,
				"post_fixed_amount": 0,
				"pre_fixed_amount": 54.84865004983954,
				"principal_amortization_amount": 306.98134995016045,
				"total_amount": 361.83,
				"workdays": 37
			},
			{
				"additional_costs": [],
				"bank_slip_key": null,
				"business_due_date": "2021-09-08",
				"calendar_days": 31,
				"digitable_line": null,
				"due_date": "2021-09-08",
				"due_interest": 0,
				"due_principal": 690.8886500498395,
				"fine_amount": null,
				"has_interest": true,
				"installment_key": "e8406cdb-844c-4e6d-9620-3635fab9d8d1",
				"installment_number": 2,
				"installment_status": "created",
				"installment_type": "principal",
				"paid_amount": 0,
				"paid_at": null,
				"post_fixed_amount": 0,
				"pre_fixed_amount": 21.964874249804833,
				"principal_amortization_amount": 339.86512575019515,
				"tax_amount": 0,
				"total_amount": 361.83,
				"workdays": 22
			}
		],
		"prefixed_interest_rate": {
				"annual_rate": 0.44556431,
				"daily_rate": 0.00564312,
				"monthly_rate": 0.0556431,
				"interest_base": "calendar_days_365"
		},
		"iof_amount": 50,
		"external_contract_fee_amount": 0,
		"external_contract_fees": [],
		"contract_fee_amount": 0,
		"contract_fees": [],
		"number_of_installments": 2,
		"disbursed_issue_amount": 997.87,
		"final_disbursement_amount": 100,
		"issue_amount": 1147.87,
		"disbursement_date": "2021-05-31",
		"cet": 1.212,
		"annual_cet": 32.122
	}],
	"disbursement_bank_account": {
		"account_digit": "1",
		"account_number": "00001",
		"ispb": "00000000",
		"branch_number": "0001"
	}
}



cuidado

A key da operação de refinanciamento, a document key, a document url, a related_party_key e a borrower related_party_key mudarão após essa ação, sendo necessário a reassinatura da CCB.

Correção de dados para refinanciamento:​

É possível recalcular o valor da parcela da operação de refinanciamento sem gerar uma nova CCB. O novo valor de parcela deve ser menor que o valor original.

ENDPOINT
/v2/credit_transfer/proposal/PROPOSAL-KEY/refinancing_credit_operation/recalculate
MÉTODO
PUT
Testar no Playground
Request Body
{
    "financial": {
        "interest_type": "pre_price_days",
        "first_due_date": "2024-06-10",
        "fine_configuration": {
            "monthly_rate": 0.01,
            "interest_base": "calendar_days",
            "contract_fine_rate": 0.02
        },
        "credit_operation_type": "ccb",
        "monthly_interest_rate": 0.0167,
        "installment_face_value": 410,
        "limit_days_to_disburse": 7,
        "number_of_installments": 84
		},
    "disbursement_bank_account": {
        "account_digit": "1",
        "account_number": "00001",
        "bank_code": "033",
        "branch_number": "0001"
    }
}

        Response:

response.json


{
	"credit_operation_key": "\<CREDIT-OPERATION-KEY\>",
	"contract_number": "00000002",
	"document_key": "\<DOCUMENT-KEY da CCB de Refinanciamento\>",
	"document_url": "\<URL da CCB de Refinanciamento\>",
	"credit_operation_status": "issued",
	"fine_configuration": {
		"contract_fine_rate": 0.02,
		"interest_base": "calendar_days",
		"monthly_rate": 0.01
	},
	"disbursement_options": [{
		"installments": [{
				"additional_costs": [],
				"bank_slip_key": null,
				"business_due_date": "2021-08-09",
				"calendar_days": 53,
				"digitable_line": null,
				"due_date": "2021-08-08",
				"due_interest": 0,
				"due_principal": 997.87,
				"fine_amount": null,
				"has_interest": true,
				"installment_key": "e3bedf31-1e87-4ba4-a36c-d52f7f5c9036",
				"installment_number": 1,
				"installment_status": "created",
				"installment_type": "principal",
				"paid_amount": 0,
				"paid_at": null,
				"post_fixed_amount": 0,
				"pre_fixed_amount": 54.84865004983954,
				"principal_amortization_amount": 306.98134995016045,
				"total_amount": 361.83,
				"workdays": 37
			},
			{
				"additional_costs": [],
				"bank_slip_key": null,
				"business_due_date": "2021-09-08",
				"calendar_days": 31,
				"digitable_line": null,
				"due_date": "2021-09-08",
				"due_interest": 0,
				"due_principal": 690.8886500498395,
				"fine_amount": null,
				"has_interest": true,
				"installment_key": "e8406cdb-844c-4e6d-9620-3635fab9d8d1",
				"installment_number": 2,
				"installment_status": "created",
				"installment_type": "principal",
				"paid_amount": 0,
				"paid_at": null,
				"post_fixed_amount": 0,
				"pre_fixed_amount": 21.964874249804833,
				"principal_amortization_amount": 339.86512575019515,
				"tax_amount": 0,
				"total_amount": 361.83,
				"workdays": 22
			}
		],
		"prefixed_interest_rate": {
				"annual_rate": 0.44556431,
				"daily_rate": 0.00564312,
				"monthly_rate": 0.0556431,
				"interest_base": "calendar_days_365"
		},
		"iof_amount": 50,
		"external_contract_fee_amount": 0,
		"external_contract_fees": [],
		"contract_fee_amount": 0,
		"contract_fees": [],
		"number_of_installments": 2,
		"disbursed_issue_amount": 997.87,
		"final_disbursement_amount": 100,
		"issue_amount": 1147.87,
		"disbursement_date": "2021-05-31",
		"cet": 1.212,
		"annual_cet": 32.122
	}],
	"disbursement_bank_account": {
		"account_digit": "1",
		"account_number": "00001",
		"ispb": "00000000",
		"branch_number": "0001"
	}
}



Correção de dados para portabilidade e refin:​

É possível corrigir os dados bancários, número do benefício e nome até que o contrato de portabilidade seja averbado. Tanto os dados do operação de portabilidade quanto do refinanciamento serão ajustados. Para isso basta utilizar a seguinte chamada:

ENDPOINT
/v2/credit_transfer/proposal/PROPOSAL-KEY/collateral
MÉTODO
PATCH
Testar no Playground
Request Body
{
	"disbursement_bank_account": {
		"bank_code": "123",
		"account_digit": "1",
		"account_branch": "1234",
		"account_number": "5678",
		"document_number": "12345678901"
	}
}

Simulando cenários de sucesso e insucesso na averbação em Sandbox:​

A simulação de cenários é baseado no primeiro dígito do CPF informado na operação.

11.1. Para CPFs iniciados com o número 1, será retornado uma resposta assíncrona de sucesso através do Webhook.

11.2. Para os demais CPFs, será retornado uma resposta assíncrona de erro, baseado no primeiro dígito do CPF digitado, de acordo com a tabela abaixo.

11.3. Erros com Ação "cancel" receberá um webhook com o resultado final da operação.

Início do cpfEnumeradorDescriçãoAção
2invalid_disbursement_accountInvalid disbursemente bank accountcancel
3operation_not_allowed_IROperation not allowed due to operation deadline greatter than benefit terminationcancel
Atenção

Todos os CPFs que não tiverem um cenário mapeado para o primeiro dígito, receberão um webhook com um erro padrão de cenário de teste não mapeado.

EnumeradorDescrição
mock_errorInformed document number is not a valid mock on test environment

5 - Envio de documentos​

Segundo IN 138 do INSS é obrigatório o envio dos dados complementares do contrato.

Os documentos devem ser enviados através do endpoint de upload de documentos. e devem seguir a seguinte formatação:

ValidaçõesValores
FormatoJPEG
Tamanho mínimo250 x 250 px
Tamanho máximo2 MB
Atenção

Contratos que tiverem documentos vinculados que não respeitam as regras de tamanho mínimo ou máximo serão cancelados permanentemente.

Caso as validações não sejam atendidas, no momento que o parceiro seguir com a proposta após receber o saldo devedor, iremos devolver os seguintes erros :

Ver exemplos de erro
{
    "title": "Invalid document format",
    "description": "The document: document_identification_back should be in JPEG format.",
    "translation": "O documento: document_identification_back deve estar no formato JPEG.",
    "code": "SSC000061"
}

Após o upload de documentos, as chaves dos documentos enviados devem ser informadas no payload de criação da proposta no tópico anterior dentro do campo borrower ou dentro do objeto de related_parties* correspondente ao representante legal ("role_type": "issuer_legal_representative"):

{
    "document_identification": "2893fc74-88fd-4cc9-a5c6-8a63d9d00f41",
    "document_identification_back": "e881ddf4-bc9a-48e0-9555-cac979f65431",
    "selfie": "ca37979e-6f11-4465-bf3b-69cd8307549c"
}

Ou ainda, após a criação da proposta, podem ser informadas através do seguinte endpoint:

ENDPOINT
/v2/credit_transfer/proposal/PROPOSAL-KEY/related_party/RELATED-PARTY-KEY/attached_document
MÉTODO
POST
Testar no Playground
Request Body
{
    "document_identification": "2893fc74-88fd-4cc9-a5c6-8a63d9d00f41",
    "document_identification_back": "e881ddf4-bc9a-48e0-9555-cac979f65431",
    "selfie": "ca37979e-6f11-4465-bf3b-69cd8307549c"
}
Informação

A related_party_key é retornada na response da criação de dívida dentro do objeto borrower e dentro de cada uma das partes relacionadas dentro de related_party_list se for o caso.

6 - Formalização da Proposta:​

Atenção

Para propostas que envolvam troco após o refinanciamento, é necessário o valor do troco calculado de acordo com as condições do contrato seja de pelo menos 5% da diferença entre a soma de todas as parcelas do refinanciamento subtraida da soma de todas as parcelas da portabilidade. Caso contrário, a requisição receberá o seguinte erro:

STATUS
400
Response Body
{
    "title": "Bad Request", 
    "code": "CT000118",
    "description": "The final disbursement amount is less than 5% of the sum of refinancing installment minus the sum of portability installment. The minimum final disbursement amount allowed is 500.00. Calculated final disbursement amount: 400.00.", 
    "translation": "O valor do troco é menor que 5% da soma do valor das parcelas do refinanciamento menos o valor soma das parcelas da portabilidade. O valor mínimo do troco permitido é de 500.00. Valor calculado do troco: 400.00."
}

        Para formalização das operações de Portabilidade e/ou Refinanciamento (Troco), deve-se enviar as evidências de assinatura dos contratos gerados na digitação da Proposta.

No payload de assinatura devem conter os campos obrigatórios relacionados aos documentos enviados no item 5. Os campos obrigatórios são os seguintes: ip_address e signature_datetime.

        6.1. Para assinatura da Operação de Portabilidade o Parceiro deve realizar a seguinte chamada:

        Request

  • MÉTODO
    POST
  • STATUS
    /v2/credit_transfer/proposal/PROPOSAL-KEY/portability_credit_operation/signature
Testar no Playground

        Payload:

payload.json
{
    "type": "pdf-signature",
    "biometry_analysis_reference": "SERPRO",
    "signature_datetime": "2023-12-22T15:01:32.482Z",
    "signed_pdf_path": "https://termos-originacao.s3.amazonaws.com/5cd2a7f9",
    "ip_address": "179.145.48.219",
    "similarity_score": "0.9750000000000001"
}

Enumeradores Biometry Analysis Reference​

EnumeradorDescrição
serproUtilizado quando o similarity_score for retornado através de consulta realizada na base de documentos com foto do Detran (Serviço prestado através da Serpro)
tseUtilizado quando o similarity_score for retornado através de consulta realizada na base de documentos com foto do TSE
not_foundDeve ser informado quando a biometria facial não for localizada em nenhuma das bases governamentais anteriores (serpro ou tse). Neste caso o similarity_score deve ser null ou o grau de similaridade da selfie com o documento oficial com foto, retornado pelo parceiro.

        A conclusão da assinatura será notificada de forma assíncrona:

        Webhook

  • WEBHOOK_TYPE
    credit_transfer.proposal.credit_operation
body.json
{
	"webhook_type": "credit_transfer.proposal.credit_operation",
	"proposal_key": "\<PROPOSAL-KEY\>",
	"event_datetime": "2022-11-24T15:42:12",
	"data": {
		"credit_operation_type": "portability",
		"credit_operation_key": "\<CREDIT-OPERATION-KEY\>",
		"document_key": "\<GUID DO DOCUMENTO NA QI\>",
		"signed_document_url": "\<LINK DO URL DO PDF ASSINADO\>",
		"credit_operation_status": "signed"
	}
}

        6.2. Para assinatura da Operação de Refinanciamento (Troco) o Parceiro deve realizar a seguinte chamada:

        Request

  • MÉTODO
    POST
  • ENDPOINT
    /v2/credit_transfer/proposal/PROPOSAL-KEY/refinancing_credit_operation/signature
Testar no Playground

        Payload:

payload.json
{
    "type": "pdf-signature",
    "signed_pdf_path": "https://termos-originacao.s3.amazonaws.com/5cd2a7f9",
	"ip_address": "192.168.0.0",
	"signature_datetime": "2020-03-20T14:28:23.382748Z",
	"similarity_score": "0.98",
	"biometry_analysis_reference": "serpro"
}

        A conclusão da assinatura será notificada de forma assíncrona:

        Webhook

  • WEBHOOK_TYPE
    credit_transfer.proposal.credit_operation
body.json


{
	"webhook_type": "credit_transfer.proposal.credit_operation",
	"proposal_key": "\<PROPOSAL-KEY\>",
	"event_datetime": "2022-11-24T15:42:12",
	"data": {
		"credit_operation_type": "refinancing",
		"credit_operation_key": "\<CREDIT-OPERATION-KEY\>",
		"document_key": "\<GUID DO DOCUMENTO NA QI\>",
		"signed_document_url": "\<LINK DO URL DO PDF ASSINADO\>",
		"credit_operation_status": "signed"
	}
}