Manual INSS - Crédito Novo ou 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.

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

Request

Caso 1: Titular do benefício é o assinante do Termo de Autorização.

ENDPOINT

/social_security/benefits_request

METHOD

POST

Request Body

{
	"document_number": "\<CPF BENEFICIÁRIO\>",
	"authorization_term": {
		"document_number": "\<CPF BENEFICIÁRIO\>", 
		"signature": {
			"signer": {
				"name": "\<NOME BENEFICIÁRIO OU RESPONSÁVEL LEGAL\>",
				"email": "\<EMAIL ASSINANTE\>",
				"phone": {
					"number": "\<NUMERO ASSINANTE\>",
					"area_code": "\<DDD ASSINANTE\>",
					"country_code": "55"
				},
				"document_number": "\<CPF ASSINANTE\>"
			},
			"authentication_type": "opt_in",
			"authenticity": {
				"timestamp": "\<DATA E HORA DA ASSINATURA\>",
				"ip_address": "\<IP DO ASSINANTE\>",
				"fingerprint": {},
				"third_party_additional_data": {},
				"session_id": "\<ID DA SESSÃO DO ASSINANTE\>"
			},
			"signed_object": {
				"document_key": "\<CHAVE DO DOCUMENTO NA QI\>"
			}
		}
	}
}

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

ENDPOINT

/social_security/benefits_request

METHOD

POST

Request Body

{
	"document_number": "\<CPF BENEFICIÁRIO\>",
	"authorization_term": {
		"document_number": "\<CPF BENEFICIÁRIO\>",
		"legal_representative_document_number": "\<CPF DO ASSINANTE\>",
		"signature": {
			"signer": {
				"name": "\<NOME BENEFICIÁRIO OU RESPONSÁVEL LEGAL\>",
				"email": "\<EMAIL ASSINANTE\>",
				"phone": {
					"number": "\<NUMERO ASSINANTE\>",
					"area_code": "\<DDD ASSINANTE\>",
					"country_code": "55"
				},
				"document_number": "\<CPF ASSINANTE\>"
			},
			"authentication_type": "opt_in",
			"authenticity": {
				"timestamp": "\<DATA E HORA DA ASSINATURA\>",
				"ip_address": "\<IP DO ASSINANTE\>",
				"fingerprint": {},
				"third_party_additional_data": {},
				"session_id": "\<ID DA SESSÃO DO ASSINANTE\>"
			},
			"signed_object": {
				"document_key": "\<CHAVE DO DOCUMENTO NA QI\>"
			}
		}
	}
}

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

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

ENDPOINT

/social_security/benefits_request

METHOD

POST

Response Body

{
	"benefits_request_key": "\<GUID DA CONSULTA DE BENEFÍCIO\>",
	"status": "pending_search"
}

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

Webhooks

WEBHOOK_TYPE

social_security_benefits_request

STATUS

Success

Webhook Body

{
	"webhook_type": "social_security_benefits_request",
	"key": "\<GUID benefits_request_key\>",
	"event_datetime": "\<DATA E HORA DO ENVIO DO WEBHOOK\>",
	"status": "success",
	"data": [{
		"benefit_number": "\<No. DO BENEFÍCIO\>",
		"benefit_status": "inelegible",
        "grant_date": "2023-06-13"
	}]
}

Campo	Descrição	Valores
benefit_status	Status do beneficio	Enumeradores

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

WEBHOOK_TYPE

social_security_benefits_request

STATUS

Failure

Webhook Body

{
	"webhook_type": "social_security_benefits_request",
	"key": "\<GUID benefits_request_key\>",
	"event_datetime": "\<DATA E HORA DO ENVIO DO WEBHOOK\>",
	"status": "failure",
	"data": {
		"enumerator": "not_found_legal_representative",
		"description": "no legal representative for the beneficiary"
	}
}

Detalhamento de campos no webhook de falha

Campo	Descrição	Valores
enumerator	Retorno mapeado do código Dataprev	Enumeradores

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 CPF	Enumerador	Descrição
2	inexistent_beneficiary	no 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.

Enumerador	Descrição
mock_error	Informed document number is not a valid mock on test environment

2 - Consulta de dados do benefício:

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

Caso 1

Request

ENDPOINT

/social_security/balance_request

METHOD

POST

Request Body

{
	"document_number": "\<CPF BENEFICIÁRIO\>",
	"benefit_number": "\<No. DO BENEFÍCIO\>"
}

Response

ENDPOINT

/social_security/balance_request

METHOD

POST

Response Body

{
	"balance_request_key": "\<GUID DA CONSULTA DE DADOS DO BENEFÍCIO\>",
	"status": "pending_search"
}

Caso 2: Consulta de dados do benefício com envio do Termo de Autorização.

Caso 2

Request

ENDPOINT

/social_security/balance_request

METHOD

POST

Request Body

{
	"document_number": "\<CPF BENEFICIÁRIO\>",
	"benefit_number": "\<No. DO BENEFÍCIO\>",
	"authorization_term": {
		"document_number": "\<CPF BENEFICIÁRIO\>",
        "legal_representative_document_number": "\<CPF DO ASSINANTE\>", // CPF do representante legal (caso aplicável)
		"signature": {
			"signer": {
				"name": "\<NOME BENEFICIÁRIO OU RESPONSÁVEL LEGAL\>",
				"email": "\<EMAIL ASSINANTE\>",
				"phone": {
					"number": "\<NUMERO ASSINANTE\>",
					"area_code": "\<DDD ASSINANTE\>",
					"country_code": "55"
				},
				"document_number": "\<CPF ASSINANTE\>"
			},
			"authentication_type": "opt_in",
			"authenticity": {
				"timestamp": "\<DATA E HORA DA ASSINATURA\>",
				"ip_address": "\<IP DO ASSINANTE\>",
				"fingerprint": {},
				"third_party_additional_data": {},
				"session_id": "\<ID DA SESSÃO DO ASSINANTE\>"
			},
			"signed_object": {
				"document_key": "\<CHAVE DO DOCUMENTO NA QI\>"
			}
		}
	}
}

Atenção

Response

ENDPOINT

/social_security/balance_request

METHOD

POST

Response Body

{
	"balance_request_key": "\<GUID DA CONSULTA DE DADOS DO BENEFÍCIO\>",
	"status": "pending_authorization"
}

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

Webhooks

WEBHOOK_TYPE

social_security_balance_request

STATUS

Success

Webhook Body

{
	"webhook_type": "social_security_balance_request",
	"key": "\<GUID balance_request_key\>",
	"event_datetime": "\<DATA E HORA DO ENVIO DO WEBHOOK\>",
	"status": "success",
	"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
        }
}

Detalhamento de campos no webhook de sucesso

Campo	Descrição	Valores
assistance_type	Tipo do benefício	Enumeradores
benefit_status	Status do beneficio	Enumeradores
has_entity_representation	Possui entidade de representação (não permite averbação)	True ou False
alimony_code	Classificador da Pensão alimentícia	not_payer, payer, benefit
has_judicial_concession	Benefício concedido por liminar	True ou False
has_power_of_attorney	Possui procurador?	True ou False
credit_type	Tipo de crédito - recebimento do benefício	Magnetic_card, checking_account
benefit_situation	Situação do benefício	Enumeradores
used_total_balance	Valor total comprometido em averbações de empréstimos, reservado para portabilidade, refinanciamento, alterações, RMC e RCC	Numérico
max_total_balance	Valor comprometido possível para a respectiva espécie do benefício	Numérico
available_total_balance	Valor 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_date	Data 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_type	Tipo de bloqueio do benefício	Enumeradores
politically_exposed.type	Pessoa politicamente exposta	Enumeradores
is_politically_exposed	Pessoa politicamente exposta	True ou False

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

WEBHOOK_TYPE

social_security_balance_request

STATUS

Failure

Webhook Body

{
	"webhook_type": "social_security_balance_request",
	"key": "\<GUID balance_request_key\>",
	"event_datetime": "\<DATA E HORA DO ENVIO DO WEBHOOK\>",
	"status": "failure",
	"data": {
		"enumerator": "not_found_legal_representative",
		"description": "no legal representative for the beneficiary"
	}
}

Detalhamento de campos no webhook de falha

Campo	Descrição	Valores
enumerator	Retorno mapeado do código Dataprev	Enumeradores

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 CPF	Enumerador	Descrição
2	inexistent_beneficiary	no 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.

Enumerador	Descrição
mock_error	Informed document number is not a valid mock on test environment

3 - Simulação de operação em batch:

Request

ENDPOINT

/debt_simulation

METHOD

POST

Crédito Novo
Refinanciamento

{
	"complex_operation": true,
	"operation_batch": [{
			"borrower": {
				"person_type": "natural"
			},
			"financial": {
				"first_due_date": "2022-12-07",
				"installment_face_value": 100.0,
				"disbursement_date": "2022-11-03",
				"limit_days_to_disburse": 3,
				"number_of_installments": 24,
				"disbursed_amount": 1876,
				"interest_type": "pre_price_days",
				"fine_configuration": {
					"monthly_rate": 0.01,
					"interest_base": "calendar_days",
					"contract_fine_rate": 0.02
				},
				"credit_operation_type": "ccb",
				"interest_grace_period": 0,
				"principal_grace_period": 0
			},
			"collaterals": [{
				"collateral_type": "social_security"
			}]
		},
		{
			"borrower": {
				"person_type": "natural"
			},
			"financial": {
				"first_due_date": "2022-12-07",
				"installment_face_value": 100.0,
				"disbursement_date": "2022-11-03",
				"limit_days_to_disburse": 3,
				"number_of_installments": 48,
				"monthly_interest_rate": 0.018,
				"interest_type": "pre_price_days",
				"fine_configuration": {
					"monthly_rate": 0.01,
					"interest_base": "calendar_days",
					"contract_fine_rate": 0.02
				},
				"credit_operation_type": "ccb",
				"interest_grace_period": 0,
				"principal_grace_period": 0
			},
			"collaterals": [{
				"collateral_type": "social_security"
			}],
	}]}

{
	"complex_operation": true,
	"operation_batch": [{
			"borrower": {
				"person_type": "natural"
			},
			"financial": {
				"first_due_date": "2022-12-07",
				"installment_face_value": 100.0,
				"disbursement_date": "2022-11-03",
				"limit_days_to_disburse": 3,
				"number_of_installments": 24,
				"disbursed_amount": 1876,
				"interest_type": "pre_price_days",
				"fine_configuration": {
					"monthly_rate": 0.01,
					"interest_base": "calendar_days",
					"contract_fine_rate": 0.02
				},
				"credit_operation_type": "ccb",
				"interest_grace_period": 0,
				"principal_grace_period": 0
			},
			"collaterals": [{
				"collateral_type": "social_security"
			}],
            "refinanced_credit_operations": [
                {
                    "operation_key": "\<DEBT_KEY DA OPERAÇÃO REFINANCIADA\>"
                }
            ],
		},
		{
			"borrower": {
				"person_type": "natural"
			},
			"financial": {
				"first_due_date": "2022-12-07",
				"installment_face_value": 100.0,
				"disbursement_date": "2022-11-03",
				"limit_days_to_disburse": 3,
				"number_of_installments": 48,
				"monthly_interest_rate": 0.018,
				"interest_type": "pre_price_days",
				"fine_configuration": {
					"monthly_rate": 0.01,
					"interest_base": "calendar_days",
					"contract_fine_rate": 0.02
				},
				"credit_operation_type": "ccb",
				"interest_grace_period": 0,
				"principal_grace_period": 0
			},
			"collaterals": [{
				"collateral_type": "social_security"
			}],
            "refinanced_credit_operations": [
                {
                    "operation_key": "\<DEBT_KEY DA OPERAÇÃO REFINANCIADA\>"
                }
            ],
	}]}

info

Na request acima existem 2 simulações sendo realizadas. A primeira está fixando o valor desembolsado ao cliente (varia a taxa da operação) e a segunda, esta fixando a taxa da operação (varia o valor desembolsado).

Response

ENDPOINT

/debt_simulation

METHOD

POST

Response Body

{
	"data": [{
		"data": {
			"credit_operation_type": "ccb",
			"disbursement_options": [{
					"annual_cet": 0.275357735300064,
					"assignment_amount": 1947.75,
					"cet": 0.0205,
					"contract_fee_amount": 17.68,
					"contract_fees": [{
						"amount": 17.68,
						"amount_type": "absolute",
						"fee_amount": 17.68,
						"fee_type": "spread_cip_cost"
					}],
					"disbursed_issue_amount": 1876,
					"disbursement_date": "2022-11-03",
					"external_contract_fee_amount": 0,
					"external_contract_fees": [],
					"installments": [{
						"business_due_date": "2022-12-07",
						"calendar_days": 34,
						"due_date": "2022-12-07",
						"due_principal": 1930.07,
						"has_interest": true,
						"installment_number": 1,
						"post_fixed_amount": 0,
						"pre_fixed_amount": 38.88069301315790,
						"principal_amortization_amount": 61.12030698684210,
						"tax_amount": 0.17181040000000,
						"total_amount": 100.00,
						"workdays": 23
					}, "\< ... x24 \>" ],
					"iof_amount": 54.07,
					"issue_amount": 1930.07,
					"total_pre_fixed_amount": 469.9216389784704,
					"net_external_contract_fee_amount": 0,
					"prefixed_interest_rate": {
						"annual_rate": 0.23872147,
						"daily_rate": 0.00058669,
						"interest_base": "calendar_days",
						"monthly_rate": 0.018
					}
				}, {
					"annual_cet": 0.251704735300064,
					"assignment_amount": 1950.20,
					"cet": 0.0189,
					"contract_fee_amount": 17.68,
					"contract_fees": [{
						"amount": 17.68,
						"amount_type": "absolute",
						"fee_amount": 17.68,
						"fee_type": "spread_cip_cost"
					}],
					"disbursed_issue_amount": 1876,
					"disbursement_date": "2022-11-04",
					"external_contract_fee_amount": 0,
					"external_contract_fees": [],
					"installments": [{
						"business_due_date": "2023-01-09",
						"calendar_days": 66,
						"due_date": "2023-01-07",
						"due_principal": 1932.52,
						"has_interest": true,
						"installment_number": 1,
						"post_fixed_amount": 0,
						"pre_fixed_amount": 69.95069301315790,
						"principal_amortization_amount": 30.05030698684210,
						"tax_amount": 0.16051040000000,
						"total_amount": 100.00,
						"workdays": 45
					}, "\< ... x24 \>" ],
					"iof_amount": 56.52,
					"issue_amount": 1932.52,
					"total_pre_fixed_amount": 467.50,
					"net_external_contract_fee_amount": 0,
					"prefixed_interest_rate": {
						"annual_rate": 0.21731447,
						"daily_rate": 0.00053890,
						"interest_base": "calendar_days",
						"monthly_rate": 0.0165
					}
				}, "..." ],
			"interest_grace_period": 0,
			"interest_payment_month_period": 1,
			"interest_type": "pre_price_days",
			"issue_date": "2022-11-04",
			"number_of_installments": 24,
			"operation_type": "structured_operation",
			"post_fixed_interest_base": "workdays",
			"post_fixed_interest_rate": null,
			"prefixed_interest_rate": {
				"annual_rate": 0.23872147,
				"daily_rate": 0.00058669,
				"interest_base": "calendar_days",
				"monthly_rate": 0.018
			},
			"principal_amortization_month_period": 1,
			"principal_grace_period": 0,
			"requester_key": "c89a6b75-02c2-471c-a17d-95e381b6ce3d"
		},
		"event_datetime": "2022-11-03 10:00:22",
		"key": "a4dcd407-df75-46f0-b1f4-5b3a9f5d1bd6",
		"status": "finished",
		"type": "debt"
	}, {
		"data": {
			"credit_operation_type": "ccb",
			"disbursement_options": [{
					"annual_cet": 0.261477735300064,
					"assignment_amount": 3205.12,
					"cet": 0.0195,
					"contract_fee_amount": 17.68,
					"contract_fees": [{
						"amount": 17.68,
						"amount_type": "absolute",
						"fee_amount": 17.68,
						"fee_type": "spread_cip_cost"
					}],
					"disbursed_issue_amount": 3087,
					"disbursement_date": "2022-11-03",
					"external_contract_fee_amount": 0,
					"external_contract_fees": [],
					"installments": [{
						"business_due_date": "2022-12-07",
						"calendar_days": 34,
						"due_date": "2022-12-07",
						"due_principal": 3187.44,
						"has_interest": true,
						"installment_number": 1,
						"post_fixed_amount": 0,
						"pre_fixed_amount": 64.20069301315790,
						"principal_amortization_amount": 35.79930698684210,
						"tax_amount": 0.09981040000000,
						"total_amount": 100.00,
						"workdays": 23
					}, "\< ... x48 \>" ],
					"iof_amount": 100.44,
					"issue_amount": 3187.44,
					"total_pre_fixed_amount": 1612.5806389784704,
					"net_external_contract_fee_amount": 0,
					"prefixed_interest_rate": {
						"annual_rate": 0.23872147,
						"daily_rate": 0.00058669,
						"interest_base": "calendar_days",
						"monthly_rate": 0.018
					}
				},
				{
					"annual_cet": 0.261047735300064,
					"assignment_amount": 3150.54,
					"cet": 0.0195,
					"contract_fee_amount": 17.68,
					"contract_fees": [{
						"amount": 17.68,
						"amount_type": "absolute",
						"fee_amount": 17.68,
						"fee_type": "spread_cip_cost"
					}],
					"disbursed_issue_amount": 3031.72,
					"disbursement_date": "2022-11-04",
					"external_contract_fee_amount": 0,
					"external_contract_fees": [],
					"installments": [{
						"business_due_date": "2023-01-09",
						"calendar_days": 66,
						"due_date": "2023-01-07",
						"due_principal": 3132.86,
						"has_interest": true,
						"installment_number": 1,
						"post_fixed_amount": 0,
						"pre_fixed_amount": 123.65069301315790,
						"principal_amortization_amount": 0,
						"tax_amount": 0,
						"total_amount": 100.00,
						"workdays": 45
					}, "\< ... x48 \>" ],
					"iof_amount": 101.14,
					"issue_amount": 3132.86,
					"total_pre_fixed_amount": 1689.8006389784704,
					"net_external_contract_fee_amount": 0,
					"prefixed_interest_rate": {
						"annual_rate": 0.23872147,
						"daily_rate": 0.00058669,
						"interest_base": "calendar_days",
						"monthly_rate": 0.018
					}
				}, "..." ],
			"interest_grace_period": 0,
			"interest_payment_month_period": 1,
			"interest_type": "pre_price_days",
			"issue_date": "2022-11-03",
			"number_of_installments": 24,
			"operation_type": "structured_operation",
			"post_fixed_interest_base": "workdays",
			"post_fixed_interest_rate": null,
			"prefixed_interest_rate": {
				"annual_rate": 0.23872147,
				"daily_rate": 0.00058669,
				"interest_base": "calendar_days",
				"monthly_rate": 0.018
			},
			"principal_amortization_month_period": 1,
			"principal_grace_period": 0,
			"requester_key": "c89a6b75-02c2-471c-a17d-95e381b6ce3d"
		},
		"event_datetime": "2022-11-03 10:00:22",
		"key": "a4dcd407-df75-46f0-b1f4-5b3a9f5d1bd6",
		"status": "finished",
		"type": "debt"
	}]
}

Caso na request, seja enviado o objeto "operation_batch[i].financial.disbursed_amount", para cada opção de desembolso, será calculada uma "data[i].data.disbursement_options[i].prefixed_interest_rate" diferente.

Caso na request, seja enviado o objeto "operation_batch[i].financial.monthly_interest_rate", para cada opção de desembolso, será calculado um "data[i].data.disbursement_options[i].disbursed_amount" diferente.

info

Os objetos "data[i].data.prefixed_interest_rate" e "data[i].data.disbursement_options[i].disbursed_amount" são referentes ao valor da 1ª opção de desembolso.

4 - Emissão de Operação:

O campo "assistance_type", localizado dentro do objeto "collateral_data", refere-se ao tipo de benefício que está sendo utilizado para o empréstimo. O mesmo é retornado na consulta de dados do benefício. Para visualizar os valores possíveis (enumeradores), consultar a tabela Tabela de enumerador

Request

Caso 1: Emissão sem representante legal

ENDPOINT

/debt

METHOD

POST

Crédito Novo
Refinanciamento

Request Body
{
  "borrower": {
    "name": "\<NOME DEVEDOR\>",
    "email": "\<EMAIL DEVEDOR\>",
    "phone": {
      "number": "\<CELUAR DO DEVEDOR\>",
      "area_code": "\<DDD DO DEVEDOR\>",
      "country_code": "+55"
    },
    "address": {
      "city": "\<CIDADE DO DEVEDOR\>",
      "state": "\<ESTADO DO DEVEDOR\>",
      "number": "\<No. DO DEVEDOR\>",
      "street": "\<RUA DO DEVEDOR\>",
      "complement": "\<COMPLEMENTO DO DEVEDOR\>",
      "postal_code": "\<CEP DO DEVEDOR\>",
      "neighborhood": "\<BAIRRO DO DEVEDOR\>"
    },
    "role_type": "issuer",
    "birth_date": "\<DATA DE NASCIMENTO DO DEVEDOR\>",
    "mother_name": "\<NOME DA MÃE DO DEVEDOR\>",
    "person_type": "natural",
    "individual_document_number": "\<CPF DO DEVEDOR\>",
    "document_identification": "2893fc74-88fd-4cc9-a5c6-8a63d9d00f41",
    "document_identification_back": "e881ddf4-bc9a-48e0-9555-cac979f65431",
    "selfie": "ca37979e-6f11-4465-bf3b-69cd8307549c"
  },
  "financial": {
    "first_due_date": "2022-12-07",
    "installment_face_value": 100.0,
    "disbursement_date": "2022-11-03",
    "limit_days_to_disburse": 3,
    "number_of_installments": 24,
    "disbursed_amount": 1876,
    "interest_type": "pre_price_days",
    "fine_configuration": {
      "monthly_rate": 0.01,
      "interest_base": "calendar_days",
      "contract_fine_rate": 0.02
    },
    "credit_operation_type": "ccb",
    "interest_grace_period": 0,
    "principal_grace_period": 0
  },
  "simplified": true,
  "collaterals": [{
    "percentage": 1,
    "collateral_data": {
      	"benefit_number": "\<No. DO BENEFÍCIO\>",
      	"state": "\<ESTADO DO BENEFICIÁRIO\>",
		"assistance_type": "\<TIPO DE BENEFÍCIO\>",
		"subcorban_document_number": "12123456000101"
    },
    "collateral_type": "social_security"
  }],
  "requester_identifier_key": "\<ID DE CONTROLE DO PARCEIRO\>",
  "disbursement_bank_account": {
    "name": "\<NOME DO DEVEDOR\>",
    "bank_code": "104",
    "account_type": "checking_account",
    "account_digit": "1",
    "branch_number": "3880",
    "account_number": "000736703806",
    "document_number": "\<CPF DO DEVEDOR\>",
    "transfer_method": "pix"
  },
  "purchaser_document_number": "\<CNPJ DO CESSIONÁRIO\>",
} 

Request Body
{
  "borrower": {
    "name": "\<NOME DEVEDOR\>",
    "email": "\<EMAIL DEVEDOR\>",
    "phone": {
      "number": "\<CELUAR DO DEVEDOR\>",
      "area_code": "\<DDD DO DEVEDOR\>",
      "country_code": "+55"
    },
    "address": {
      "city": "\<CIDADE DO DEVEDOR\>",
      "state": "\<ESTADO DO DEVEDOR\>",
      "number": "\<No. DO DEVEDOR\>",
      "street": "\<RUA DO DEVEDOR\>",
      "complement": "\<COMPLEMENTO DO DEVEDOR\>",
      "postal_code": "\<CEP DO DEVEDOR\>",
      "neighborhood": "\<BAIRRO DO DEVEDOR\>"
    },
    "role_type": "issuer",
    "birth_date": "\<DATA DE NASCIMENTO DO DEVEDOR\>",
    "mother_name": "\<NOME DA MÃE DO DEVEDOR\>",
    "person_type": "natural",
    "individual_document_number": "\<CPF DO DEVEDOR\>",
    "document_identification": "2893fc74-88fd-4cc9-a5c6-8a63d9d00f41",
    "document_identification_back": "e881ddf4-bc9a-48e0-9555-cac979f65431",
    "selfie": "ca37979e-6f11-4465-bf3b-69cd8307549c"
  },
  "financial": {
    "first_due_date": "2022-12-07",
    "installment_face_value": 100.0,
    "disbursement_date": "2022-11-03",
    "limit_days_to_disburse": 3,
    "number_of_installments": 24,
    "disbursed_amount": 1876,
    "interest_type": "pre_price_days",
    "fine_configuration": {
      "monthly_rate": 0.01,
      "interest_base": "calendar_days",
      "contract_fine_rate": 0.02
    },
    "credit_operation_type": "ccb",
    "interest_grace_period": 0,
    "principal_grace_period": 0
  },
  "simplified": true,
  "collaterals": [{
    "percentage": 1,
    "collateral_data": {
      	"benefit_number": "\<No. DO BENEFÍCIO\>",
      	"state": "\<ESTADO DO BENEFICIÁRIO\>",
		"assistance_type": "\<TIPO DE BENEFÍCIO\>",
		"subcorban_document_number": "12123456000101"
		
    },
    "collateral_type": "social_security"
  }],
  "requester_identifier_key": "\<ID DE CONTROLE DO PARCEIRO\>",
  "disbursement_bank_account": {
    "name": "\<NOME DO DEVEDOR\>",
    "bank_code": "104",
    "account_type": "checking_account",
    "account_digit": "1",
    "branch_number": "3880",
    "account_number": "000736703806",
    "document_number": "\<CPF DO DEVEDOR\>",
    "transfer_method": "pix"
  },
  "refinanced_credit_operations": [
      {
          "operation_key": "\<DEBT_KEY DA OPERAÇÃO REFINANCIADA\>"
      }
  ],
  "purchaser_document_number": "\<CNPJ DO CESSIONÁRIO\>",
} 

Caso 2: Emissão com representante legal

ENDPOINT

/debt

METHOD

POST

Crédito Novo
Refinanciamento

{
	"borrower": {
		"name": "\<NOME DEVEDOR\>",
		"email": "\<EMAIL DEVEDOR\>",
		"phone": {
			"number": "\<CELUAR DO DEVEDOR\>",
			"area_code": "\<DDD DO DEVEDOR\>",
			"country_code": "+55"
		},
		"address": {
			"city": "\<CIDADE DO DEVEDOR\>",
			"state": "\<ESTADO DO DEVEDOR\>",
			"number": "\<No. DO DEVEDOR\>",
			"street": "\<RUA DO DEVEDOR\>",
			"complement": "\<COMPLEMENTO DO DEVEDOR\>",
			"postal_code": "\<CEP DO DEVEDOR\>",
			"neighborhood": "\<BAIRRO DO DEVEDOR\>"
		},
		"role_type": "issuer",
		"birth_date": "\<DATA DE NASCIMENTO DO DEVEDOR\>",
		"mother_name": "\<NOME DA MÃE DO DEVEDOR\>",
		"person_type": "natural",
		"individual_document_number": "\<CPF DO DEVEDOR\>",
		"document_identification": "2893fc74-88fd-4cc9-a5c6-8a63d9d00f41",
		"document_identification_back": "e881ddf4-bc9a-48e0-9555-cac979f65431",
		"selfie": "ca37979e-6f11-4465-bf3b-69cd8307549c"
	},
	"related_parties": [{
		"name": "\<NOME REPRESENTANTE LEGAL\>",
		"email": "beatriz@qitech.com.br",
		"phone": {
			"number": "991294043",
			"area_code": "55",
			"country_code": "055"
		},
		"address": {
			"street": "AV LEONOR",
			"state": "SP",
			"city": "GUARULHOS",
			"neighborhood": "",
			"number": "1",
			"postal_code": "07025200",
			"complement": ""
		},
		"role_type": "issuer_legal_representative",
		"person_type": "natural",
		"is_pep": false,
		"individual_document_number": "45102538004",
		"birth_date": "1970-04-20",
		"mother_name": " Ana Lúcia",
		"document_identification": "2893fc74-88fd-4cc9-a5c6-8a63d9d00f41",
		"document_identification_back": "e881ddf4-bc9a-48e0-9555-cac979f65431",
		"selfie": "ca37979e-6f11-4465-bf3b-69cd8307549c"
	}],
	"financial": {
		"first_due_date": "2022-12-07",
		"installment_face_value": 100.0,
		"disbursement_date": "2022-11-03",
		"limit_days_to_disburse": 3,
		"number_of_installments": 24,
		"disbursed_amount": 1876,
		"interest_type": "pre_price_days",
		"fine_configuration": {
			"monthly_rate": 0.01,
			"interest_base": "calendar_days",
			"contract_fine_rate": 0.02
		},
		"credit_operation_type": "ccb",
		"interest_grace_period": 0,
		"principal_grace_period": 0
	},
	"simplified": true,
	"collaterals": [{
		"percentage": 1,
		"collateral_data": {
			"benefit_number": "\<No. DO BENEFÍCIO\>",
			"state": "\<ESTADO DO BENEFICIÁRIO\>",
            "assistance_type": "\<TIPO DE BENEFÍCIO\>",
			"subcorban_document_number": "12123456000101"
		},
		"collateral_type": "social_security"
	}],
	"requester_identifier_key": "\<ID DE CONTROLE DO PARCEIRO\>",
	"disbursement_bank_account": {
		"name": "\<NOME DO DEVEDOR\>",
		"bank_code": "104",
		"account_type": "checking_account",
		"account_digit": "1",
		"branch_number": "3880",
		"account_number": "000736703806",
		"document_number": "\<CPF DO DEVEDOR\>",
		"transfer_method": "pix"
	},
	"purchaser_document_number": "\<CNPJ DO CESSIONÁRIO\>"
}

{
	"borrower": {
		"name": "\<NOME DEVEDOR\>",
		"email": "\<EMAIL DEVEDOR\>",
		"phone": {
			"number": "\<CELUAR DO DEVEDOR\>",
			"area_code": "\<DDD DO DEVEDOR\>",
			"country_code": "+55"
		},
		"address": {
			"city": "\<CIDADE DO DEVEDOR\>",
			"state": "\<ESTADO DO DEVEDOR\>",
			"number": "\<No. DO DEVEDOR\>",
			"street": "\<RUA DO DEVEDOR\>",
			"complement": "\<COMPLEMENTO DO DEVEDOR\>",
			"postal_code": "\<CEP DO DEVEDOR\>",
			"neighborhood": "\<BAIRRO DO DEVEDOR\>"
		},
		"role_type": "issuer",
		"birth_date": "\<DATA DE NASCIMENTO DO DEVEDOR\>",
		"mother_name": "\<NOME DA MÃE DO DEVEDOR\>",
		"person_type": "natural",
		"individual_document_number": "\<CPF DO DEVEDOR\>",
		"document_identification": "2893fc74-88fd-4cc9-a5c6-8a63d9d00f41",
		"document_identification_back": "e881ddf4-bc9a-48e0-9555-cac979f65431",
		"selfie": "ca37979e-6f11-4465-bf3b-69cd8307549c"
	},
	"related_parties": [{
		"name": "\<NOME REPRESENTANTE LEGAL\>",
		"email": "beatriz@qitech.com.br",
		"phone": {
			"number": "991294043",
			"area_code": "55",
			"country_code": "055"
		},
		"address": {
			"street": "AV LEONOR",
			"state": "SP",
			"city": "GUARULHOS",
			"neighborhood": "",
			"number": "1",
			"postal_code": "07025200",
			"complement": ""
		},
		"role_type": "issuer_legal_representative",
		"person_type": "natural",
		"is_pep": false,
		"individual_document_number": "45102538004",
		"birth_date": "1970-04-20",
		"mother_name": " Ana Lúcia",
		"document_identification": "2893fc74-88fd-4cc9-a5c6-8a63d9d00f41",
		"document_identification_back": "e881ddf4-bc9a-48e0-9555-cac979f65431",
		"selfie": "ca37979e-6f11-4465-bf3b-69cd8307549c"
	}],
	"financial": {
		"first_due_date": "2022-12-07",
		"installment_face_value": 100.0,
		"disbursement_date": "2022-11-03",
		"limit_days_to_disburse": 3,
		"number_of_installments": 24,
		"disbursed_amount": 1876,
		"interest_type": "pre_price_days",
		"fine_configuration": {
			"monthly_rate": 0.01,
			"interest_base": "calendar_days",
			"contract_fine_rate": 0.02
		},
		"credit_operation_type": "ccb",
		"interest_grace_period": 0,
		"principal_grace_period": 0
	},
	"simplified": true,
	"collaterals": [{
		"percentage": 1,
		"collateral_data": {
			"benefit_number": "\<No. DO BENEFÍCIO\>",
			"state": "\<ESTADO DO BENEFICIÁRIO\>",
            "assistance_type": "\<TIPO DE BENEFÍCIO\>",
			"subcorban_document_number": "12123456000101"
		},
		"collateral_type": "social_security"
	}],
	"requester_identifier_key": "\<ID DE CONTROLE DO PARCEIRO\>",
	"disbursement_bank_account": {
		"name": "\<NOME DO DEVEDOR\>",
		"bank_code": "104",
		"account_type": "checking_account",
		"account_digit": "1",
		"branch_number": "3880",
		"account_number": "000736703806",
		"document_number": "\<CPF DO DEVEDOR\>",
		"transfer_method": "pix"
	},
    "refinanced_credit_operations": [
        {
            "operation_key": "\<DEBT_KEY DA OPERAÇÃO REFINANCIADA\>"
        }
    ],
    "purchaser_document_number": "\<CNPJ DO CESSIONÁRIO\>",
}

Exemplo de objeto financial com rebates

{
    "financial": {
        "first_due_date": "2022-12-07",
        "installment_face_value": 100,
        "disbursement_date": "2022-11-03",
        "limit_days_to_disburse": 3,
        "number_of_installments": 24,
        "disbursed_amount": 1876,
        "interest_type": "pre_price_days",
        "fine_configuration": {
            "monthly_rate": 0.01,
            "interest_base": "calendar_days",
            "contract_fine_rate": 0.02
        },
        "credit_operation_type": "ccb",
        "interest_grace_period": 0,
        "principal_grace_period": 0,
        "rebates": [
            {
                "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"
            }
        ]
    }
}

Response

ENDPOINT

/debt

METHOD

POST

Response Body

{
	"data": {
		"borrower": {
			"document_number": "\<CPF DEVEDOR\>",
			"name": "\<NOME DEVEDOR\>",
            "related_party_key": "1755ea25-f85a-4ca7-b4d5-4a198a43a2ca"
		},
		"collaterals": [{
			"absolute_amount": null,
			"collateral_constituted": false,
			"collateral_data": {
				"benefit_number": "\<No. DO BENEFÍCIO\>",
				"state": "\<ESTADO DO BENEFICIÁRIO\>",
                "assistance_type": "\<TIPO DE BENEFÍCIO\>",
                "subcorban_document_number": "12123456000101"
			},
			"collateral_key": "5e40c191-06ae-4da2-9d4b-3c0bf6eeb1a3",
			"collateral_type": "social_security",
			"created_at": "2022-11-03T20:56:09.200482",
			"external_key": "\<DEBT-KEY\>",
			"percentage": 1,
			"updated_at": "2022-11-03T20:56:09.200474"
		}],
		"contract": {
			"number": "BYX00000000001",
			"signature_information": [{
				"signature_url": null,
				"signer_document_number": "\<CPF ASSINANTE\>",
				"signer_email": "\<EMAIL ASSINANTE\>",
				"signer_external_key": null,
				"signer_name": "\<NOME ASSINANTE\>",
				"signer_role": "issuer"
			}],
			"urls": [
				"\<LINK URL DA CCB\>"
			]
		},
		"disbursement_options": [{
				"additional_iof": 24.220242,
				"annual_cet": "26.1457%",
				"assignment_amount": 3205.12,
				"base_iof": 176.6603785598479778,
				"cet": "1,9544%",
				"contract_fee_amount": 17.68,
				"contract_fees": [{
					"amount": 17.68,
					"amount_type": "absolute",
					"fee_amount": 17.68,
					"fee_type": "spread_cip_cost"
				}],
				"disbursement_date": "2022-11-03",
				"external_contract_fee_amount": 0,
				"external_contract_fees": [],
				"first_due_date": "2022-12-07",
				"installments": [{
						"additional_costs": [],
						"business_due_date": "2022-12-07",
						"calendar_days": 34,
						"due_date": "2022-12-07",
						"due_interest": 0,
						"due_principal": 3187.44,
						"fine_amount": null,
						"has_interest": true,
						"installment_number": 1,
						"installment_status": null,
						"installment_type": null,
						"post_fixed_amount": 0,
						"pre_fixed_amount": 64.20069301315790,
						"principal_amortization_amount": 35.79930698684210,
						"tax_amount": 0.10014353287723266,
						"total_amount": 100,
						"workdays": 23
					}
				],
				"issue_amount": 3187.44,
				"net_external_contract_fee_amount": 0,
				"total_iof": 100.44,
				"total_pre_fixed_amount": 3225.1656904289435
			},
			{
				"additional_iof": 24.220242,
				"annual_cet": "26.0057%",
				"assignment_amount": 3205.12,
				"base_iof": 176.6603785598479778,
				"cet": "1,9544%",
				"contract_fee_amount": 17.68,
				"contract_fees": [{
					"amount": 17.68,
					"amount_type": "absolute",
					"fee_amount": 17.68,
					"fee_type": "spread_cip_cost"
				}],
				"disbursement_date": "2022-11-04",
				"external_contract_fee_amount": 0,
				"external_contract_fees": [],
				"first_due_date": "2023-01-07",
				"installments": [{
						"additional_costs": [],
						"business_due_date": "2023-01-07",
						"calendar_days": 34,
						"due_date": "2022-12-07",
						"due_interest": 0,
						"due_principal": 3187.44,
						"fine_amount": null,
						"has_interest": true,
						"installment_number": 1,
						"installment_status": null,
						"installment_type": null,
						"post_fixed_amount": 0,
						"pre_fixed_amount": 64.20069301315790,
						"principal_amortization_amount": 35.79930698684210,
						"tax_amount": 0.10014353287723266,
						"total_amount": 100,
						"workdays": 23
					}
				],
				"issue_amount": 3187.44,
				"net_external_contract_fee_amount": 0,
				"total_iof": 100.44,
				"total_pre_fixed_amount": 3225.1656904289435
			},
			{
				"additional_iof": 24.220242,
				"annual_cet": "25.8457%",
				"assignment_amount": 3205.12,
				"base_iof": 176.6603785598479778,
				"cet": "1,9544%",
				"contract_fee_amount": 17.68,
				"contract_fees": [{
					"amount": 17.68,
					"amount_type": "absolute",
					"fee_amount": 17.68,
					"fee_type": "spread_cip_cost"
				}],
				"disbursement_date": "2022-11-05",
				"external_contract_fee_amount": 0,
				"external_contract_fees": [],
				"first_due_date": "2022-12-07",
				"installments": [{
						"additional_costs": [],
						"business_due_date": "2022-12-07",
						"calendar_days": 34,
						"due_date": "2022-12-07",
						"due_interest": 0,
						"due_principal": 3187.44,
						"fine_amount": null,
						"has_interest": true,
						"installment_number": 1,
						"installment_status": null,
						"installment_type": null,
						"post_fixed_amount": 0,
						"pre_fixed_amount": 64.20069301315790,
						"principal_amortization_amount": 35.79930698684210,
						"tax_amount": 0.10014353287723266,
						"total_amount": 100,
						"workdays": 23
					} 
				],
				"issue_amount": 3187.44,
				"net_external_contract_fee_amount": 0,
				"total_iof": 100.44,
				"total_pre_fixed_amount": 3225.1656904289435
			},
			{
				"additional_iof": 24.220242,
				"annual_cet": "26.1457%",
				"assignment_amount": 3205.12,
				"base_iof": 176.6603785598479778,
				"cet": "1,9544%",
				"contract_fee_amount": 17.68,
				"contract_fees": [{
					"amount": 17.68,
					"amount_type": "absolute",
					"fee_amount": 17.68,
					"fee_type": "spread_cip_cost"
				}],
				"disbursement_date": "2022-11-06",
				"external_contract_fee_amount": 0,
				"external_contract_fees": [],
				"first_due_date": "2022-12-07",
				"installments": [{
						"additional_costs": [],
						"business_due_date": "2022-12-07",
						"calendar_days": 34,
						"due_date": "2022-12-07",
						"due_interest": 0,
						"due_principal": 3187.44,
						"fine_amount": null,
						"has_interest": true,
						"installment_number": 1,
						"installment_status": null,
						"installment_type": null,
						"post_fixed_amount": 0,
						"pre_fixed_amount": 64.20069301315790,
						"principal_amortization_amount": 35.79930698684210,
						"tax_amount": 0.10014353287723266,
						"total_amount": 100,
						"workdays": 23
					} 
				],
				"issue_amount": 3187.44,
				"net_external_contract_fee_amount": 0,
				"total_iof": 100.44,
				"total_pre_fixed_amount": 3225.1656904289435
			}
		],
		"iof_charge_method": "financed",
		"requester_identifier_key": "3ed0744d-1f35-4688-aa65-739b8a3f9e89"
	},
	"event_datetime": "2022-11-07 13:54:58",
	"key": "3ed0744d-1f35-4688-aa65-739b8a3f9e89",
	"status": "waiting_signature",
	"webhook_type": "debt"
}

Caso a operação não seja assinada ou averbada até a última opção de data de desembolso o parceiro receberá um webhook informando a respeito do cancelamento da operação:

WEBHOOK_TYPE

debt

STATUS

Canceled

Webhook Body

{
	"key": "\<DEBT-KEY\>",
	"data": {
		"cancel_reason": "Operacao cancelada manualmente",
		"cancel_reason_enumerator": "manual"
	},
	"status": "canceled",
	"webhook_type": "debt",
	"event_datetime": "2022-11-01 03:46:31"
}

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 cpf	Enumerador	Descrição	Ação
2	invalid_disbursement_account	Invalid disbursemente bank account	cancel
3	operation_not_allowed_IR	Operation not allowed due to operation deadline greatter than benefit termination	cancel

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.

Enumerador	Descrição
mock_error	Informed document number is not a valid mock on test environment

5 - Envio de documentos

É obrigatório o envio (segundo IN 138 do INSS) 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ções	Valores
Formato	JPEG
Tamanho mínimo	250 x 250 px
Tamanho máximo	2 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.

Após o upload dos documentos, as chaves dos documentos enviados devem ser informadas no payload de criação da operação ou após, através do seguinte endpoint:

ENDPOINT

/debt/DEBT-KEY/related_party/RELATED-PARTY-KEY/attached_document

METHOD

POST

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

6 - Formalização da operação

Após o input dos documentos a operação pode seguir para formalização.

No caso de assinatura por parte do representante legal, no campo "data.contract.signers[i]" serão retornados os dados do representante legal, e o valor do objeto "data.contract.signers[i].signer_role" será "issuer_legal_representative".

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.

Request

ENDPOINT

/debt/DEBT-KEY/signed

METHOD

POST

Request Body

{
	...,
	"ip_address": "192.168.0.0",
	"signature_datetime": "2020-03-20T14:28:23.382748Z",
	"similarity_score": 0.98000,
    "biometry_analysis_reference": "serpro",
	"type": "data-signature"
}

Atenção

O payload de envio da assinatura varia de acordo com o processo de formalização do parceiro e deve ser alinhado com o time de integração da QI Tech.

Enumeradores Biometry Analysis Reference

Enumerador	Descrição
serpro	Utilizado 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)
tse	Utilizado quando o similarity_score for retornado através de consulta realizada na base de documentos com foto do TSE
not_found	Deve 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.

QI Sign

A QI Tech oferece o serviço de assinatura que atende ao determinado pela IN 138. Com biometria facial e envio de documentos.

Para receber uma cotação consulte nosso time comercial:

comercial@qitech.com.br ou (11) 2339-4763

Response

ENDPOINT

/debt/DEBT-KEY/signed

METHOD

POST

Response Body

{
  "data": {},
    "event_datetime": "2022-11-07 15:24:47",
    "key": "\<DEBT-KEY\>",
    "status": "signature_received",
    "webhook_type": "debt"
}

Após o recebimento da assinatura, uma validação dos documentos enviados e do campo assistance type será feita.

Caso seja enviado um tipo de benefício (assistance_type) que não esteja mapeado, a operação será cancelada permanentemente.

O mesmo vale para as validações de documentos, caso haja duplicidade, falta ou documentos fora dos padrões mínimos exigidos, a operação será cancelada permanente.

Em ambos os casos, um webhook será enviado com o seguinte payload:

WEBHOOK_TYPE

debt

STATUS

Canceled Permanently

Webhook Body

{
	"key": "<DEBT-KEY>",
	"data": {},
	"status": "canceled_permanently",
	"webhook_type": "debt",
	"event_datetime": "2022-11-01 03:46:31"
}

7 - Averbação e Desaverbação

Averbação

Em caso de sucesso na averbação o parceiro receberá o seguinte webhook:

WEBHOOK_TYPE

credit_operation.collateral

STATUS

Success

Webhook Body

{
	"key": "\<DEBT-KEY\>",
	"data": {
		"collateral_type": "social_security",
		"collateral_constituted": true
	},
	"event_time": "2022-10-31 15:23:46",
	"webhook_type": "credit_operation.collateral"
}

Desaverbação

O cancelmento definitivo de uma operação pode ocorrer de duas formas, manual e automática.

Para realizar o cancelamento definitivo de uma operação manualmente, com a desaverbação da margem consignável, deve ser utilizado o seguinte endpoint:

ENDPOINT

/debt/DEBT-KEY/cancel_permanently

METHOD

POST

O cancelamento definitivo de forma automática acontece quando uma operação está no status "canceled" por mais de 10 dias.

A reserva pode ir para esse status por diferentes motivos, tais como: erro no processo de desembolso, cancelamento manual ou falta de opções de desembolso.

Webhooks

WEBHOOK_TYPE

debt

STATUS

Canceled Permanently

Webhook Body

{
	"key": "\<DEBT-KEY\>",
	"data": {},
	"status": "canceled_permanently",
	"webhook_type": "debt",
	"event_datetime": "2022-11-01 03:46:31"
}

8 - Falha no desembolso

TED

Em caso de falha no desembolso via TED

WEBHOOK_TYPE

debt

STATUS

Canceled

Webhook Body

 {
 	"status": "canceled",
 	"key": "\<DEBT-KEY\>",
 	"data": {
 		"ted_refusal": {
 			"transaction_key": "16faabfc-3876-437d-a4f6-aae17a1d68c9",
 			"description": "341 0000 000000-7 12345678900 - NOME BENEFICIÁRIO",
 			"origin": {
 				"account_key": "a1d2dea5-fa90-4676-a125-da355fdc3ed0",
 				"account_number": "00086",
 				"bank_code": "329",
 				"name": "ACCOUNT TRANSITORY",
 				"type": "payment_account",
 				"document": "32402502000135",
 				"branch_digit": null,
 				"account_digit": "8",
 				"branch": "0001"
 			},
 			"fee": 0,
 			"reason_enumerator": "agencia_conta_invalida",
 			"timestamp": "2022-11-07T14:36:05",
 			"amount": 483.6,
 			"reason": "Agência ou Conta Destinatária do Crédito Inválida",
 			"destination": {
 				"branch": "0000",
 				"account_number": "000000",
 				"name": "NOME BENEFICIÁRIO",
 				"purpose": "Crédito em Conta",
 				"type": "checking_account",
 				"branch_digit": null,
 				"document": "12345678900",
 				"bank_code": "341",
 				"account_digit": "7"
 			}
 		},
 		"cancel_reason": "ted_refusal"
 	}
 }

Pix

Em caso de falha no desembolso via Pix

WEBHOOK_TYPE

debt

STATUS

Canceled

Webhook Body

{
        "webhook_type": "debt",
        "data": {
          "pix_refusal": {
            "reason_enumerator": "invalid_document_number",
            "reason": "CPF/CNPJ do usuário recebedor não é compatível com o titular da conta de destino."
          },
          "cancel_reason": "pix_refusal"
        },
        "status": "canceled",
        "key": "\<DEBT-KEY\>",
        "event_datetime": "2022-11-07 15:29:37"
      }

9 - Reapresentação de Pagamento

Altera a data de desembolso sem afetar os valores financeiros da operação.

Request

ENDPOINT

/debt/DEBT-KEY/change_disbursement_date

MÉTODO

POST

Request Body

{
    "disbursement_date": "2022-11-04",
    "disbursement_bank_accounts": [
        {
            "branch_number": "1232",
            "account_digit": "4",
            "account_number": "412412412",
            "account_type": "checking_account",
            "document_number": "\<CPF BENEFICIÁRIO\>",
            "bank_code": 184,
            "ispb_number": "17298092",
            "name": "\<NOME BENEFICIÁRIO\>",
            "percentage_receivable": 100
        }
    ]
}

Response

ENDPOINT

/debt/DEBT-KEY/change_disbursement_date

MÉTODO

POST

Response Body

{
    "disbursement_accounts": [
        {
            "account_branch": "1232",
            "account_digit": "4",
            "account_number": "412412412",
            "account_type": "checking_account",
            "amount_receivable": null,
            "created_at": "2022-05-24T14:51:46",
            "digitable_line": null,
            "disbursement_type": "ted",
            "document_number": "37197645832",
            "financial_institutions": {
                "code_number": 184,
                "ispb": 17298092,
                "name": "BCO ITAÚ BBA S.A."
            },
            "financial_institutions_code_number": 184,
            "is_pix_disbursement": false,
            "ispb": "17298092",
            "name": "Márcio e Catarina Gráfica Ltda",
            "percentage_receivable": 50.0,
            "pix_key": null,
            "pix_transfer_key": null,
            "pix_type": null,
            "qr_code_key": null,
            "retry_counter": 0,
            "retry_vector": null,
            "transaction_key": null,
            "webhook_key": null
        }
    ],
    "disbursement_date": "2022-11-04"
}

Competence Diagram

10 - 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 a Dataprev, possibilitando saber quando essa requisição foi feita e qual o retorno obtido (através de um enumerador). Os enumeradores estão diretamente relacionados aos códigos de retorno da Dataprev e são divididos em duas formas: "errors" e "success".

Cada enumerador tem uma descrição detalhada e o código de referência da Dataprev. Podemos conferir abaixo, com mais detalhes, como serão apresentados os dados do last response.

Casos de sucesso

Request

ENDPOINT

/debt/DEBT-KEY/collateral

METHOD

GET

Response

Response Body

{
  "collateral_constituted": true,
  "collateral_type": "type",
  "updated_at": "2023-05-24 19:13:02",
  "collateral_data": {
    "state": "SP",
    "benefit_number": 1976703155,
    "status": "reserved",
    "last_response": {
      "success": [
        {
          "enumerator": "succesfully_included",
          "reservation_method" : "new_credit"
        }
      ]
    },
    "last_response_event_datetime": "2023-05-22T19:13:02Z"
  }
}

Detalhamento de campos no retorno da request

Campo	Descrição	Valores
enumerator	Retorno mapeado do código Dataprev	Enumeradores
reservation_method	Método de averbação da reserva	portability, new_credit, refinancing

Casos de erro

Request

ENDPOINT

/debt/DEBT-KEY/collateral

METHOD

GET

Response

Response Body

{
  "collateral_constituted": false,
  "collateral_type": "type",
  "updated_at": "2023-05-24 19:13:02",
  "collateral_data": {
    "state": "SP",
    "benefit_number": 1976703155,
    "status": "pending_reservation",
    "last_response": {
      "errors": [
        {
          "enumerator": "benefit_blocked_by_tbm",
          "reservation_method" : "new_credit"
        }
      ]
    },
    "last_response_event_datetime": "2023-05-22T19:13:02Z"
  }
}

Detalhamento de campos no retorno da request

Campo	Descrição	Valores
enumerator	Retorno mapeado do código Dataprev	Enumeradores
reservation_method	Método de averbação da reserva	portability, new_credit, refinancing

11 - Recuperar última consulta do benefício

Por esse endpoint é possível consultar quando foi a última consulta do benefício na Dataprev.

Request

ENDPOINT

/social_security/benefit/BENEFIT-NUMBER

MÉTODO

GET

Response

Response Body

{
    "last_balance_check": "2025-08-22T19:13:02Z",
    "status": "pending_balance_request"
}

12 - Webhook de resposta da última tentativa de averbação

Caso a operação não tenha sucesso na averbação, 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:

WEBHOOK_TYPE

credit_operation.collateral

Body:

body.json

{
	"webhook_type": "credit_operation.collateral",
	"key": "\<CREDIT-OPERATION-KEY\>",
	"event_time": "2022-11-24T15:42:12",
	"data": {
		"collateral_type": "social_security",
		"collateral_constituted": false,
		"collateral_data": {
			"status": "pending_reservation",
			"last_response": {
				"errors": [{
					"enumerator": "consignable_margin_excceded"
				}]
			},
			"last_response_event_datetime": "2023-05-22T19:13:02Z",
			"reservation_method": "new_credit",
		}
	}
}

13. Mapeamento de enumeradores

Tabela de retorno de erros Dataprev - averbação

Código Dataprev	Enumerador	Descrição	Ação Qi
HW	consignable_margin_excceded	Exceeded consignable margin	Teimosinha
IT	benefit_blocked_by_tbm	Benefit blocked due to benefit transfer	Teimosinha
IE	benefit_blocked_by_beneficiary	Benefit blocked by beneficiary	Teimosinha
AN	invalid_disbursement_account	Invalid disbursement bank account	Cancelar
HX	reservation_already_included	Reservation already included	Confirmar averbação
IF	benefit_blocked_by_granting_process	Benefit blocked during granting process	Teimosinha
AV	processing_payroll	Operation couldn`t be done during processing payroll period	Teimosinha
OF	invalid_cbc	Invalid cbc	Teimosinha
IA	first_name_mismatch	First name mismatch benefit owner or legal representative	Teimosinha
OS	legal_representative_document_number_mismatch	Document number mismatch legal representative	Teimosinha
AY	invalid_state	Invalid state	Teimosinha
HZ	operation_not_allowed_on_this_reservation_status	Operation couldn`t be done with current reservation status	Teimosinha
AP	invalid_contract_date	Accrual, end or start contract date is invalid	Teimosinha
GA	required_fields_missing	Required fields are missing	Teimosinha
BC	cbc_missing	CBC is missing	Teimosinha
NC	contract_number_missing	Contract number is missing	Teimosinha
NB	benefit_number_missing	Benefit number is missing	Teimosinha
CA	invalid_bank_code	Invalid bank code	Teimosinha
HR	exceeded_number_of_allowed_contracts	Amount of contracts is above the limit	Teimosinha
PV	invalid_image_format	Image with wrong format	Teimosinha
IR	operation_not_allowed_IR	Operation date is greater than benefit expiration	Cancelar
PK	wrong_bank_code_destination	Portability number was found with wrong bank code destination	Teimosinha
PH	wrong_benefit_number_on_portability	Portability number was found with wrong benefit number	Teimosinha
PI	invalid_contract_total_amount	Reservation contract total amount should be greater than Dataprev reference amount	Teimosinha

Tabela de retorno de sucesso - averbação

Código Dataprev	Enumerador	Descrição
BD	successfully_included	Inclusion has been successfully done
BF	successfully_removed	Removal has been successfully done
BR	successfully_reactivated	Reactivation has been successfully done
BS	successfully_suspended	Suspension has been successfully done

Tabela de retorno de erros na consulta de saldo

Código	Enumerador	Descrição
CR	not_found_legal_representative	no legal representative for the beneficiary
CD	inexistent_beneficiary	no beneficiary found
AS	benefity_without_legal_representative	beneficiary does not have a legal representative
BI	inexistent_benefit	no benefit found
D1	inconsistent_balance_benefit_data	The balance benefit data registered is either inconsistent, null or incomplete.

Tabela de retorno de erros na consulta de benefícios

Código	Enumerador	Descrição
CR	not_found_legal_representative	no legal representative for the beneficiary
CD	inexistent_beneficiary	no beneficiary found
AS	benefity_without_legal_representative	beneficiary does not have a legal representative

Tabela de situação de benefícios

Items
active
excluded
terminated
suspended
suspended_by_CONPAG
terminated_by_SISOBI
receiving_monthly_recover_6_months
receiving_monthly_recover_18_months
suspended_by_name_error
suspended_by_credentialed_payer
suspended_by_inspection
suspended_by_audit
terminated_by_inspection
terminated_by_audit
receiving_monthly_recover_6_months_inspection
receiving_monthly_recover_18_months_inspection
suspended_by_SISOBI
canceled_by_audit

Tabela de status de benefícios

Enumerador	Descrição
Elegible	Elegível para empréstimo
Inelegible	Benefício inelegível para empréstimo
Blocked	Benefício elegível, porém bloqueado para empréstimo

Tabela de tipos de bloqueio

Enumerador	Descrição
0	Sem bloqueio
1	Bloqueado pelo Segurado
2	Bloqueado por TBM
3	Bloqueado na Concessão

Tabela de tipos de politicamente exposto

Enumerador	Descrição
0	Pessoa Não Exposta Politicamente
1	Pessoa Exposta Politicamente - Nível 1

Tabela de benefícios

código	benefício
1	pension_by_death_rural_worker
2	pension_by_death_accident_rural_worker
3	pension_by_death_rural_employer
4	retirement_invalidity_rural_emploee
5	retirement_invalidity_accident_rural_worker
6	retirement_invalidity_rural_employer
7	retirement_by_eldness_rural_worker
8	retirement_by_age_rural_employer
9	complement_by_work_accident_rural_worker
11	support_invalidity_rural_worker
12	support_by_age_rural_worker
13	aid_sickness_rural_worker
15	aid_time_off_rural_worker
16	aid_federal
17	international_agreement
18	inclusion_benefit
19	pension_student_law7004
20	pension_by_death_diplomat
21	pension_by_death
22	pension_by_death_statute
23	pension_by_death_veteran
24	pension_special_institutional_act
25	aid_time_off
26	pension_by_death_special_law593
27	pension_by_death_federal_emploee
28	pension_by_death_general_regime_law20465
29	pension_by_death_marine_veteran
30	monthly_income_lifetime_invalidity
31	aid_sickness
32	retirement_invalidity_social_security
33	retirement_invalidity_aeronautic
34	retirement_invalidity_marine_law1756
35	aid_sickness_veteran
36	aid_social_security_accident
37	retirement_capin_extra_emploee
38	retirement_federal_extra_emploee
39	aid_invalidity_student_law7004
40	monthly_income_lifetime_by_age_upper70_law6179
41	retirement_by_age
42	retirement_by_contribution_time
43	retirement_by_time_of_service_veteran
44	retirement_special_aeronautic
45	retirement_by_time_of_service_journalist
46	retirement_special
47	allowance_25
48	allowance_20
49	retirement_ordinary
50	aid_sickness_extinct_basic_plan
51	retirement_invalidity_extinct_basic_plan
52	retirement_by_age_extinct_basic_plan
53	aid_time_off_extinct_basic_plan
54	pension_indemnity_federal
55	pension_by_death_extinct_basic_plan
56	pension_lifetime_syndrome_thalidomide
57	retirement_by_teacher_labor_time
58	retirement_anisty
59	pension_by_death_amnesty
60	indemnity
61	aid_birth
62	aid_funeral
63	aid_funeral_rural_worker
64	aid_funeral_rural_employer
65	savings_special_autarchy
67	savings_mandatory_ipase_law5128
68	savings_special_retirement_ps_affiliated_upper60
69	savings_student_law7004
70	restitution
71	monthly_income
72	retirement_by_time_of_service_law1756
73	monthly_income_family_statute
74	complement_pension_federal
75	complement_retirement_federal
76	monthly_income_statute
77	monthly_income_sinpas_family_statute
78	retirement_by_age_law1756
79	advantage
80	monthly_income_maternity
81	compulsory_retirement
82	retirement_by_time_of_service_sasse
83	retirement_invalidity_ex_sasse
84	pension_by_death_sasse
85	pension_lifetime_rubber_tapper_law7986
86	pension_lifetime_rubber_tapper_dependent_law7986
87	continuous_aid_physical_disabilities
88	continuous_aid_eldness
89	pension_special_hemodialysis_victim_caruaru
90	medic_assistency_work_accident
91	aid_sickness_by_work_accident
92	retirement_invalidity_work_accident
93	pension_by_death_work_accident
94	aid_work_accident
95	aid_additional_work_accident
96	pension_special_leprosy_law11520
97	savings_by_death_work_accident
98	aid_longshoreman
99	time_off_15

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

Request​

Response​

Webhooks​

Detalhamento de campos no webhook de falha​

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

2 - Consulta de dados do benefício:​

Caso 1​

Request​

Response​

Caso 2​

Request​

Response​

Webhooks​

Detalhamento de campos no webhook de sucesso​

Detalhamento de campos no webhook de falha​

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

3 - Simulação de operação em batch:​

Request​

Response​

4 - Emissão de Operação:​

Request​

Response​

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

5 - Envio de documentos​

6 - Formalização da operação​

Request​

Enumeradores Biometry Analysis Reference​

Response​

7 - Averbação e Desaverbação​

Averbação​

Desaverbação​

Webhooks​

8 - Falha no desembolso​

TED​

Pix​

9 - Reapresentação de Pagamento​

Request​

Response​

10 - Recuperar resposta da última request​

Casos de sucesso​

Request​

Response​

Detalhamento de campos no retorno da request​

Casos de erro​

Request​

Response​

Detalhamento de campos no retorno da request​

11 - Recuperar última consulta do benefício​

Request​

Response​

12 - Webhook de resposta da última tentativa de averbação​

13. Mapeamento de enumeradores​

Tabela de retorno de erros Dataprev - averbação​

Tabela de retorno de sucesso - averbação​

Tabela de retorno de erros na consulta de saldo​

Tabela de retorno de erros na consulta de benefícios​

Tabela de situação de benefícios​

Tabela de status de benefícios​

Tabela de tipos de bloqueio​

Tabela de tipos de politicamente exposto​

Tabela de benefícios​

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

Request

Response

Webhooks

Detalhamento de campos no webhook de falha

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

2 - Consulta de dados do benefício:

Caso 1

Request

Response

Caso 2

Request

Response

Webhooks

Detalhamento de campos no webhook de sucesso

Detalhamento de campos no webhook de falha

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

3 - Simulação de operação em batch:

Request

Response

4 - Emissão de Operação:

Request

Response

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

5 - Envio de documentos

6 - Formalização da operação

Request

Enumeradores Biometry Analysis Reference

Response

7 - Averbação e Desaverbação

Averbação

Desaverbação

Webhooks

8 - Falha no desembolso

TED

Pix

9 - Reapresentação de Pagamento

Request

Response

10 - Recuperar resposta da última request

Casos de sucesso

Request

Response

Detalhamento de campos no retorno da request

Casos de erro

Request

Response

Detalhamento de campos no retorno da request

11 - Recuperar última consulta do benefício

Request

Response

12 - Webhook de resposta da última tentativa de averbação

13. Mapeamento de enumeradores

Tabela de retorno de erros Dataprev - averbação

Tabela de retorno de sucesso - averbação

Tabela de retorno de erros na consulta de saldo

Tabela de retorno de erros na consulta de benefícios

Tabela de situação de benefícios

Tabela de status de benefícios

Tabela de tipos de bloqueio

Tabela de tipos de politicamente exposto

Tabela de benefícios