跳到主要内容

SIAPE/军队带找零转贷

合同列表查询​

注意

此功能仅适用于与军队 API 的集成。

持有CPF、军人注册编号和Token后，集成合作伙伴可通过以下端点查询可供购买的军人合同列表：

请求​

ENDPOINT
/military_payroll/portability_contracts_report
MÉTODO
POST
Request Body
{
    "document_number": "45507529710",
    "registration_code": "146254221",
    "token": "abc1234"
}
信息

CPF 必须以文本格式提供，最多 11 个字符，不含"."和"-"，左侧以零填充。

请求体参数​

字段类型描述
document_numberstring军人的 CPF。
registration_codestring军人注册编号。
tokenstring军人密码。

响应​

ENDPOINT
/military_payroll/portability_contracts_report
MÉTODO
POST
STATUS
201
Response Body
{
	"portability_contracts_report_key": "3e41a8afb-e1b2-4215-8093-c4b5feab529c" ,
	"status": "pending_search"
}

额度查询数据将通过 webhook 返回。

响应体参数​

字段类型描述
portability_contracts_report_keystring合同列表查询的识别键。
statusenum合同列表查询状态枚举值。

合同列表查询状态枚举值​

枚举值描述
pending_search合同列表查询等待军队系统响应。
failed合同列表查询失败。
succeeded合同列表查询成功。

查询成功​

成功 webhook 将以如下形式返回：

WEBHOOK_TYPE
military_payroll.portability_contracts_report
STATUS
succeeded
Body
{
	"webhook_type": "military_payroll.portability_contracts_report.status_change",
	"key": "3e41a8afb-e1b2-4215-8093-c4b5feab529c",
	"event_datetime": "2023-05-28T08:43:29Z",
	"status": "succeeded",
	"data": {
		"document_number": "45507529710",
		"contracts" : [
			{
				"econsig_id": "2361529",
				"installment_amount": 10.0,
				"number_of_installments": 5,
				"number_of_paid_installments": 1,
				"consignatory": "BANCO XPTO", 
				"contract_date": "2022-01-03T15:01:57Z",
				"contract_status": 	"accepted"			
			}
		]
		
	}
}

查询失败​

失败 webhook 将以如下形式返回：

WEBHOOK_TYPE
military_payroll.portability_contracts_report
STATUS
failed
Body
{
	"webhook_type": "military_payroll.portability_contracts_report.status_change",
	"key": "3e41a8afb-e1b2-4215-8093-c4b5feab529c",
	"event_datetime": "2023-05-28T08:43:29Z",
	"status": "failed",
	"data": { 
		"enumerator": "military_not_found" 
	}
}

每个 enumerator 都有更详细的描述，为便于查阅，下表列出了每种情况的对应关系。

failure_reason 枚举值​

枚举值描述Zetra 代码
contracts_not_found未找到与所提供数据匹配的合同294
invalid_registration_code提供的注册编号无效210
military_blocked查询无法完成，因为该军人已被封锁352
military_not_found未找到与所提供数据匹配的服务器293

个人信贷业务模拟​

首先需要计算清偿原信贷业务所需的个人信贷业务金额。

原债务的未偿余额应填写在 disbursed_amount 字段中。

注意

该业务必须以仅 1 期还款进行模拟，在 D0 放款，还款日期应为放款（付款）日期起的 D+5 个工作日。

请求​

ENDPOINT
/debt_simulation
MÉTODO
POST
Request Body
{
	"borrower": {
		"person_type": "natural"
	},
	"financial": {
		"disbursed_amount": 80492.95,
		"monthly_interest_rate": 0.03,
		"credit_operation_type": "ccb",
		"disbursement_date": "2023-03-17",
		"issue_date": "2023-03-17",
		"fine_configuration": {
			"contract_fine_rate": 0,
			"interest_base": "workdays",
			"monthly_rate": 0
		},
		"interest_grace_period": 0,
		"interest_type": "pre_price_days",
		"number_of_installments": 1,
		"principal_grace_period": 0,
		"first_due_date_delay": 5
	}
}

SIAPE/军队薪资贷款业务模拟​

SIAPE 薪资贷款业务的模拟，应模拟原合同的清偿以及根据可用额度和合同利率计算释放给客户的找零金额。

在此模拟中，所提供字段的值将按如下方式分配：

installment_face_value = 可扣除额度值

disbursement_date = 模拟时刻起 D+5 个工作日

due_balance = 个人信贷业务模拟中返回的第 1 期 total_amount

original_deadline = 个人信贷业务的总天数（5 天）

IOF

SIAPE 薪资贷款业务的 IOF 金额，由于其再融资个人信贷业务，将仅对应释放给客户的找零金额（新资金）。

请求​

ENDPOINT
/debt_simulation
MÉTODO
POST
Request Body
{
    "borrower": {
        "person_type": "natural"
    },
    "financial": {
        "first_due_date": "2023-06-10",
        "installment_face_value": 100.0,
        "disbursement_date": "2023-03-22",
        "number_of_installments": 96,
        "monthly_interest_rate": 0.0205,
        "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": "federal_payroll/military_payroll"
    }],
    "refinanced_credit_operations": [
        {
            "due_balance": 1250.20,
            "original_deadline": 120
        }
    ]
}

data.final_disbursement_amount 字段在模拟中返回的值即为支付给客户的找零金额。


查询个人信贷业务的还款期金额​

请求​

ENDPOINT
/debt?key=[DEBT-KEY]&eval_present_value=True&calculate_delay=True&calculate_spread=False
MÉTODO
GET
信息

DEBT-KEY 是业务创建响应中返回的键（/debt 的响应）


创建债务人名下账户​

在录入提案之前，需要在 QI Tech 为债务人开设账户。

该账户将用于接收个人信贷业务的放款，并通过其他银行（通过 Boleto、TED 或 Pix）支付原债务的未偿余额。

请求​

ENDPOINT
/account
MÉTODO
POST
Request Body
{
	"is_operation_account": true,
	"account_owner": {
		"address": {
			"city": "São Paulo",
			"complement": "s/c",
			"neighborhood": "Pinheiros",
			"number": "215",
			"postal_code": "12345012",
			"state": "SP",
			"street": "Gilberto Sabino"
		},
		"birth_date": "1961-01-30",
		"document_identification": "261a8fbc-d998-4dd7-8515-ddebb212ae27",
		"is_pep": false,
		"mother_name": "Nome da Mãe do Devedor",
		"nationality": "brasileiro",
		"email": "email@email.com",
		"individual_document_number": "12345678911",
		"name": "Nome do Devedor",
		"phone": {
			"area_code": "11",
			"country_code": "055",
			"number": "900000000"
		},
		"person_type": "natural"
	}
}
参数描述
account_owner债务人数据
is_operation_account表示该账户为业务账户。

响应​

ENDPOINT
/account
MÉTODO
POST
Response Body
{
	"data": {
		"account_info": {
			"account_branch": "0001",
			"account_digit": "3",
			"account_number": "1234567",
			"financial_institution_code": "329"
		},
		"account_owner": {
			"document_number": "12345678911",
			"name": "Nome do Devedor"
		}
	},
	"event_datetime": "2023-03-21 12:30:24",
	"key": "8ff1e73f-e87b-4641-99a6-3267030c6034",
	"status": "account_pending_operation",
	"webhook_type": "account"
}
信息

/account 返回的账户数据应用作个人信贷业务的放款账户

5xx 错误或超时​

在账户成功开设之前，流程不应继续。 对于失败情况，在可能的重试开户之前，应检查账户是否确实未为客户开设。

可以通过列出特定 CPF 的已开账户来检查账户是否已为客户开设。

请求​

ENDPOINT
/account
MÉTODO
POST
PARAMETER
owner_document_number, requester_key
参数描述
owner_document_number债务人的 CPF
requester_key集成的内部键。

响应​

STATUS
200
Response Body
{
	"data": [{
		...
		"account_branch": "0001",
		...
		"account_digit": "2",
		...
		"account_key": "f600a6a9-0845-454f-b25c-a6d108ea582e",
		"account_name": "Default",
		"account_number": "1467576",
		"account_status": {
			"created_at": "2019-10-11T18:58:31",
			"enumerator": "opened",
			"translation_path": "account.AccountStatus.opened"
		},
		...
		"owner_document_number": "09080702000105",
		"owner_name": "Nome do Devedor",
		...
	}],
	"pagination": {
		"current_page": 1,
		"next_page": null,
		"rows_per_page": 100,
		"total_pages": 1,
		"total_rows": 1
	}
}
信息

上述响应 payload 中仅列出了相关的可读字段。


业务发行​

个人信贷业务和 SIAPE 薪资贷款业务的创建，必须在同一时刻进行，每项业务具有以下配置

  • 个人信贷业务：应在 D0 放款发行，仅有一期还款，到期日为放款日起 D+5 个工作日。
  • SIAPE 薪资贷款业务：应在 D+0 放款发行，但放款选项可延至 D+15 个自然日，并按预期期数发行。
注意

发行个人信贷业务时，"financial"对象必须与其模拟时发送的信息完全相同。

发行 SIAPE 薪资贷款业务时，"financial"对象将有以下差异：

  • disbursement_date 字段应替换为 disbursement_start_date 和 disbursement_end_date 字段，两者之差必须为 15 个自然日。
  • refinanced_credit_operations[0].operation_key 字段必须包含个人信贷业务创建返回中返回的 DEBT-KEY。
信息

个人信贷业务只能在工作日放款，具体时间取决于原债务未偿余额的支付方式：

  • TED：放款时间在 6:30 至 17:15 之间
  • Boleto：放款时间在 7:00 至 22:00 之间
  • Pix：任意时间（但建议在商业时间内放款，因为若操作在深夜放款，例如，Pix 的入账可能因可疑欺诈而被拒绝）

个人信贷业务发行​

发行个人信贷业务时，需要发送放款后需要支付的 Boleto/TED/Pix 信息。

注意

合作伙伴必须生成业务的内部识别键，并在债务发行请求的"requester_identifier_key"字段中发送

请求示例​

ENDPOINT
/debt
MÉTODO
POST
Request Body
{
	"borrower": {
		"name": "Nome do Devedor",
		"email": "email@email.com",
		"phone": {
			"number": "900000000",
			"area_code": "11",
			"country_code": "055"
		},
		"address": {
			"city": "São Paulo",
			"state": "SP",
			"number": "215",
			"street": "Gilberto Sabino",
			"complement": "s/c",
			"postal_code": "12345012",
			"neighborhood": "Pinheiros"
		},
		"role_type": "issuer",
		"birth_date": "1969-05-01",
		"mother_name": "Nome da Mãe do Devedor",
		"person_type": "natural",
		"individual_document_number": "12345678911",
		"gender": "male",
		"nationality": "brasileiro",
		"is_pep": false,
		"marital_status": "married"
	},
	"financial": {
		"disbursed_amount": 80492.95,
		"annual_interest_rate": 0.20983,
		"credit_operation_type": "ccb",
		"disbursement_date": "2023-03-17",
		"issue_date": "2023-03-17",
		"fine_configuration": {
			"contract_fine_rate": 0,
			"interest_base": "workdays",
			"monthly_rate": 0
		},
		"interest_grace_period": 0,
		"interest_type": "pre_price_days",
		"number_of_installments": 1,
		"principal_grace_period": 0,
		"first_due_date_delay": 5
	},
	"simplified": true,
	"additional_data": {
		"debt_payment": [{
			"bank_slip": [{
                "digitable_line": "10495419967200010004900031456924592920008049295",
                "amount": "80492,95",
                "beneficiary": "CAIXA ECONÔMICA FEDERAL",
                "due_date": "2023-03-17"
            }],
			"funds_transfer": [],
			"pix": [],
			"financial_institution_code_number": "623"
		}],
		"issuer_account": {
			"account_digit": "0",
			"account_branch": "1234",
			"account_number": "123456",
			"financial_institution_code_number": "104"
		},
		"total_af_amount": 86186.52
	},
	"requester_identifier_key": "7ac52492-61c0-4dd6-a414-b0bf940fb7ca",
	"disbursement_bank_account": {
		"bank_code": "329",
		"account_digit": "3",
		"branch_number": "0001",
		"account_number": "1234567"
	},
	"after_disbursement_actions": [{
		"action_data": {
			"digitable_line": "10495419967200010004900031456924592920008049295"
		},
		"action_type": "bankslip_payment"
	}],
	"modality": {
        "code": "0203"
    }
}

婚姻状态枚举值​

枚举值描述
single单身
married已婚
widower丧偶
divorced离婚

5xx 错误或超时​

如果请求返回 5xx 或超时，为了确认操作确实未在 QI 中创建，建议合作伙伴查询返回 5xx 或超时的操作。

ENDPOINT
/debt?requester_identifier_key=34427233-925d-416d-93eb-c7f5084e8359
MÉTODO
GET

如果 GET 请求返回 200，合作伙伴不应重试创建操作，而应继续操作流程。 如果返回 404 - Not Found，合作伙伴应重试创建操作。

STATUS
200
Response Body
{
	"data": {
		"additional_iof": 307.166388,
		"annual_cet": "60,4731%",
		"assignment_amount": 80833.26,
		"base_iof": 33.141637696905995,
		"borrower": {
			"document_number": "12345678911",
			"name": "Nome do Devedor"
		},
		"cet": "4,0200%",
		"collaterals": [],
		"contract": {
			"external_contract_key": "351eada5-a626-404c-a3a3-f91c123270ce",
			"number": "0000000001/NDD",
			"signature_information": [{
				"signature_url": "https://sign.qitech.com.br/s/hNrwjda",
				"signer_document_number": "12345678911",
				"signer_email": "email@email.com",
				"signer_external_key": "56d105f3-a7f6-4442-95e9-71f44d2ae5fc",
				"signer_name": "Nome do Devedor",
				"signer_role": "issuer"
			}],
			"urls": [
				"https://storage.googleapis.com/live-doc-api/documents/45e5b9c0-0f56-40a8-aace-d206f72c164d/QISCD-NOME_DO_DEVEDOR-CCB-0001212121-20230317194512.pdf"
			]
		},
		"contract_fee_amount": 0,
		"contract_fees": [],
		"external_contract_fee_amount": 0,
		"external_contract_fees": [],
		"installments": [{
			"accrual_reference_date": null,
			"additional_costs": [],
			"advanced_paid_amount": 0,
			"bank_slip_key": null,
			"business_due_date": "2023-03-22",
			"calendar_days": 5,
			"digitable_line": null,
			"due_date": "2023-03-22",
			"due_interest": 0,
			"due_principal": 80833.26,
			"fine_amount": null,
			"has_interest": true,
			"installment_history": [],
			"installment_key": "75460851-2e82-4e3d-a805-b3e55b6b31d4",
			"installment_number": 1,
			"installment_payment": [],
			"installment_status": "created",
			"installment_type": "principal",
			"original_due_principal": 80833.26,
			"original_pre_fixed_amount": 183.5073246195304,
			"original_principal_amortization_amount": 80833.26267538047,
			"original_total_amount": 81016.77,
			"paid_amount": 0,
			"paid_at": null,
			"post_fixed_amount": 0,
			"pre_fixed_amount": 183.5073246195304,
			"principal_amortization_amount": 80833.26267538047,
			"qr_code_key": null,
			"qr_code_url": null,
			"renegotiation_proposal_key": null,
			"tax_amount": 33.141637696905995,
			"total_accrual_amount": null,
			"total_amount": 81016.77,
			"total_paid_amount": 0,
			"workdays": 3
		}],
		"iof_charge_method": "financed",
		"issue_amount": 80833.26,
		"net_external_contract_fee_amount": 0,
		"number_of_installments": 1,
		"prefixed_interest_rate": {
			"annual_rate": 0.20983,
			"created_at": "2023-03-17T19:45:11",
			"daily_rate": 0.00075616,
			"interest_base": "workdays",
			"monthly_rate": 0.01599997
		},
		"requester_identifier_key": "34427233-925d-416d-93eb-c7f5084e8359",
		"total_iof": 340.31,
		"total_pre_fixed_amount": 183.5073246195304
	},
	"event_datetime": "2023-03-17 19:45:19",
	"key": "052fe83c-37f6-4339-a831-127b50566745",
	"status": "waiting_signature",
	"webhook_type": "debt"
}
信息

操作创建响应中的"key"字段是 DEBT-KEY，即操作在 QI 内的唯一键。

签名​

与 SIAPE ML 操作相同的签名流程

授权放款​

操作签名后，需要授权操作进行放款。

注意

个人信贷业务的放款授权，必须在收到 SIAPE 中提案录入确认 webhook 后发送。

ENDPOINT
/debt/[DEBT-KEY]/allow_disbursement
MÉTODO
POST
Request Body
{
	"allow_disbursement": true
}

放款​

操作签名并授权放款后，将自动进入放款流水线。

放款处理完成后，合作伙伴将收到以下 webhook：

放款成功​

WEBHOOK_TYPE
debt
STATUS
Disbursed
Webhook Body
{
	"key": "052fe83c-37f6-4339-a831-127b50566745",
	"data": {
		"installments": [{
			"due_date": "2023-03-22",
			"total_amount": 81016.77,
			"installment_key": "75460851-2e82-4e3d-a805-b3e55b6b31d4",
			"pre_fixed_amount": 183.5073246195304,
			"principal_amortization_amount": 80833.26267538047
		}],
		"ted_receipt_list": []
	},
	"status": "disbursed",
	"webhook_type": "debt",
	"event_datetime": "2023-03-17 13:20:40"
}

放款后操作​

个人信贷业务放款至 QI 中创建的债务人账户后，将执行与清偿债务人原债务未偿余额相关的 boleto/TED/Pix 支付（放款后操作）

成功​

WEBHOOK_TYPE
after_disbursement_action_update
STATUS
Success
Webhook Body
{
	"key": "3bce3113-3644-4491-b87a-fe6551edff70",
	"data": {
		"status": "done",
		"action_key": "d25097e2-09f1-47fc-8b7f-d1988b1a7669",
		"error_data": null,
		"action_data": {
			"digitable_line": "10495419967200010004900031456924592920008049295"
		},
		"action_type": "bankslip_payment",
		"execution_data": {
			"bank_slip": {
				"payer": {
					"name": "Nome do Devedor",
					"document_number": "12345678911",
					"document_number_formatted": "123.456.789-11"
				},
				"beneficiary": {
					"name": "CAIXA ECONÔMICA FEDERAL",
					"document_number": "00360305000104",
					"document_number_formatted": "00.360.305/0001-04"
				},
				"payment_key": "500a496e-4cca-4b12-9dc8-254932ebbcac",
				"payment_date": "2023-03-08",
				"digitable_line": "10495419967200010004900031456924592920008049295",
				"expiration_date": "2023-03-10",
				"payment_date_formatted": "08/03/2023",
				"expiration_date_formatted": "10/03/2023",
				"financial_institution_name": "CAIXA ECONÔMICA FEDERAL",
				"financial_institution_compe_number": "104"
			},
			"origin_key": "dfac205a-bdef-4820-8608-2dc81d9e10d4",
			"transacted_at": "2023-03-08 16:07:58",
			"source_account": {
				"owner_name": "Nome do Devedor",
				"account_digit": "3",
				"account_branch": "0001",
				"account_number": "1234567",
				"owner_document_number": "12345678911",
				"financial_institution_name": "QI SCD S.A.",
				"owner_document_number_formatted": "123.456.789-11",
				"financial_institution_compe_number": 329
			},
			"source_subtype": "bank_slip_payment",
			"transaction_key": "86a4320d-a69d-4c14-8300-9a6f22d35fcb",
			"transacted_at_br": "2023-03-08 13:07:58",
			"pdf_encoded_string": "\<BASE 64 DO PDF DO COMPROVANTE\>",
			"transaction_amount": 3864.95,
			"transacted_at_formatted": "08/03/2023, 16:07:58",
			"transacted_at_br_formatted": "08/03/2023, 13:07:58",
			"transaction_amount_formatted": "R$ 3.864,95",
			"source_subtype_translation_ptbr": "Pagamento de Boleto"
		}
	},
	"webhook_type": "after_disbursement_action_update",
	"event_datetime": "2023-03-08 16:08:02"
}

放款后操作错误​

如果放款后操作支付发生错误，合作伙伴将通过以下 webhook 收到通知：

WEBHOOK_TYPE
after_disbursement_action_update
STATUS
Error
Webhook Body
{
	"key": "e358e7e3-17b8-4aab-9da1-92f6b78dea00",
	"data": {
		"status": "error",
		"action_key": "e2495e5a-df32-4826-b6f0-419014d3c35a",
		"error_data": {
			"error_code": "QIT000007",
			"description": "Account blocked balance cannot be negative."
		},
		"action_data": {
            "digitable_line": "10495419967200010004900031456924592920008049295"
		},
		"action_type": "bankslip_payment",
		"execution_data": null
	},
	"webhook_type": "after_disbursement_action_update",
	"event_datetime": "2023-03-22 12:06:38"
}

放款后操作的 TED 退款​

如果放款后操作中执行的 TED 被目标金融机构退回，合作伙伴将通过以下 webhook 收到通知：

WEBHOOK_TYPE
after_disbursement_action_update
STATUS
Refused
Webhook Body
{
	"key": "f4b5c36a-2aa1-4865-9678-e5a6fa585845",
	"data": {
		"status": "refused",
		"action_key": "cf3b8809-36dc-4574-8763-3600e413cf5c",
		"error_data": {
			"code": "agencia_conta_invalida",
			"description": "Agência ou Conta Destinatária do Crédito Inválida"
		},
		"action_data": {
			"destination": {
				"name": "SILVANA RAMOS DOS SANTOS",
				"account_digit": "1",
				"account_branch": "0150",
				"account_number": "301771620",
				"document_number": "30874011884",
				"financial_institution_code_number": "237"
			},
			"transaction_amount": 3200
		},
		"action_type": "funds_transfer",
		"action_amount": 3200.0
	},
	"webhook_type": "after_disbursement_action_update",
	"event_datetime": "2023-03-23 14:46:39"
}

重试失败的放款后操作​

如果放款后操作支付发生错误/退款，可通过以下端点重试 /baas/action/[ACTION-KEY]


SIAPE 薪资贷款业务发行​

SIAPE 薪资贷款业务必须清偿个人信贷业务，并向客户释放找零（如有）

请求​

ENDPOINT
/debt
MÉTODO
POST
Request Body
{
    "borrower": {
		"name": "Nome do Devedor",
		"email": "email@email.com",
		"phone": {
			"number": "900000000",
			"area_code": "11",
			"country_code": "055"
		},
		"address": {
			"city": "São Paulo",
			"state": "SP",
			"number": "215",
			"street": "Gilberto Sabino",
			"complement": "s/c",
			"postal_code": "12345012",
			"neighborhood": "Pinheiros"
		},
		"role_type": "issuer",
		"birth_date": "1969-05-01",
		"mother_name": "Nome da Mãe do Devedor",
		"person_type": "natural",
		"individual_document_number": "12345678911",
		"gender": "male",
		"nationality": "brasileiro",
		"is_pep": false,
		"marital_status": "married"
	},
    "financial": {
        "first_due_date": "2023-05-07",
        "installment_face_value": 100.0,
        "disbursement_date": "2023-03-22",
        "limit_days_to_disburse": 3,
        "number_of_installments": 96,
        "monthly_interest_rate": 0.0205,
        "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": {
            "reservation_type": "new_credit",
            "authority_code": "17000",
            "pensioner_registration_code": "",
            "registration_code": "12345678",
			"authority": {
				"description": "teste",
				"authority_document_number": "1234"
			}
        },
        "collateral_type": "federal_payroll"
    }],
    "requester_identifier_key": "13176f51-3cc8-46a3-96e9-df59d7e3960c",
    "disbursement_bank_account": {
		"bank_code": "329",
		"account_digit": "3",
		"branch_number": "0001",
		"account_number": "1234567"
	},
    "purchaser_document_number": "32402502000135",
	"modality": {
        "code": "0202"
    },
    "refinanced_credit_operations": [
        {
            "operation_key": "052fe83c-37f6-4339-a831-127b50566745"
        }
    ]
}

响应​

STATUS
200
Response Body
{
    "data": {
        "borrower": {
            "document_number": "12345678911",
            "name": "Nome do Devedor",
            "related_party_key": "c5584ee3-e077-41dc-a28e-c2ba97390bf1"
        },
        "collaterals": [{
            "absolute_amount": null,
            "collateral_constituted": false,
            "collateral_data": {
                "authority_code": "17000",
                "pensioner_registration_code": null,
                "registration_code": "12345678"
            },
            "collateral_key": "5e40c191-06ae-4da2-9d4b-3c0bf6eeb1a3",
            "collateral_type": "federal_payroll",
            "created_at": "2023-03-17T20:56:09.200482",
            "external_key": "8cda40d8-1593-4a1e-938f-5e1488e734d8",
            "percentage": 1,
            "updated_at": "2023-03-17T20:56:09.200474"
        }],
        "contract": {
            "number": "0000000002/NDD",
            "signature_information": [{
                "signature_url": null,
                "signer_document_number": "12345678911",
                "signer_email": "email@email.com",
                "signer_external_key": null,
                "signer_name": "Nome do Devedor",
                "signer_role": "issuer"
            }],
            "urls": [
                "https://storage.googleapis.com/live-doc-api/documents/45e5b9c0-0f56-40a8-aace-d206f72c164d/QISCD-NOME_DO_DEVEDOR-CCB-0000000002-20230317183044.pdf"
            ]
        },
        "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": "2023-03-22",
                "external_contract_fee_amount": 0,
                "external_contract_fees": [],
                "first_due_date": "2023-05-07",
                "installments": [{
                        "additional_costs": [],
                        "business_due_date": "2022-05-08",
                        "calendar_days": 34,
                        "due_date": "2023-05-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
                    }, 
                    ... 
                    x 96
                ],
                "issue_amount": 3187.44,
                "net_external_contract_fee_amount": 0,
                "total_iof": 100.44,
                "total_pre_fixed_amount": 3225.1656904289435
            },
            ...
            x 15
        ],
        "iof_charge_method": "financed",
        "requester_identifier_key": "13176f51-3cc8-46a3-96e9-df59d7e3960c"
    },
    "event_datetime": "2023-03-17 13:54:58",
    "key": "32f99efe-7654-4e74-a509-c7413341a831",
    "status": "waiting_signature",
    "webhook_type": "debt"
}

待同意 Webhook​

WEBHOOK_TYPE
credit_operation.collateral
STATUS
Pending Consent
Body
{
	"key": "\<DEBT-KEY\>",
	"data": {
        "collateral_data": {
			"reservation_status": "pending_consent"
		},
		"collateral_type": "federal_payroll",
		"collateral_constituted": false
	},
	"event_time": "2022-10-31 15:23:46",
	"webhook_type": "credit_operation.collateral"
}

注销登记​

SIAPE 薪资贷款业务创建后，QI 将启动业务的注销登记流程。

注销登记尝试流程从业务创建时开始，并将重试至业务最后一个放款选项日期。

录入完成后，QI 将通知合作伙伴注销登记的待同意情况：

WEBHOOK_TYPE
credit_operation.collateral
STATUS
Pending Consent
Body
{
	"key": "\<DEBT-KEY\>",
	"data": {
        "collateral_data": {
			"reservation_status": "pending_consent"
		},
		"collateral_type": "federal_payroll",
		"collateral_constituted": false
	},
	"event_time": "2022-10-31 15:23:46",
	"webhook_type": "credit_operation.collateral"
}

同意完成且额度注销登记确认后，QI 将通过以下 webhook 通知合作伙伴：

WEBHOOK_TYPE
credit_operation.collateral
STATUS
Success
Webhook Body
{
    "key": "32f99efe-7654-4e74-a509-c7413341a831",
    "data": {
        "collateral_type": "federal_payroll",
        "collateral_constituted": true
    },
    "event_time": "2022-03-22 15:23:46",
    "webhook_type": "credit_operation.collateral"
}

军队薪资贷款业务发行​

军队薪资贷款业务必须清偿个人信贷业务，并向客户释放找零（如有）

请求​

ENDPOINT
/debt
MÉTODO
POST
Request Body
{
    "borrower": {
		"name": "Nome do Devedor",
		"email": "email@email.com",
		"phone": {
			"number": "900000000",
			"area_code": "11",
			"country_code": "055"
		},
		"address": {
			"city": "São Paulo",
			"state": "SP",
			"number": "215",
			"street": "Gilberto Sabino",
			"complement": "s/c",
			"postal_code": "12345012",
			"neighborhood": "Pinheiros"
		},
		"role_type": "issuer",
		"birth_date": "1969-05-01",
		"mother_name": "Nome da Mãe do Devedor",
		"person_type": "natural",
		"individual_document_number": "12345678911",
		"gender": "male",
		"nationality": "brasileiro",
		"is_pep": false,
		"marital_status": "married"
	},
    "financial": {
        "first_due_date": "2023-05-07",
        "installment_face_value": 100.0,
        "disbursement_date": "2023-03-22",
        "limit_days_to_disburse": 3,
        "number_of_installments": 72,
        "monthly_interest_rate": 0.017,
        "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": {
            "reservation_type": "portability",
            "portability_data":{
                "token":"hw342y1h24",
                "origin_econsig_id":"2016587"
            },
            "registration_code": "12345678",
			"reservation_method": "creation"
        },
        "collateral_type": "military_payroll" 
    }],
    "requester_identifier_key": "7e000c2d-d381-470e-b233-416097504866",
    "disbursement_bank_account": {
		"bank_code": "341",
		"account_digit": "3",
		"branch_number": "1234",
		"account_number": "1234567"
	},
    "purchaser_document_number": "32402502000135",
	"modality": {
        "code": "0202"
    },
    "refinanced_credit_operations": [
        {
            "operation_key": "d2fd3f63-3d11-42a8-ab5c-9a84b5c58b6c"
        }
    ]
}

collateral_data 对象字段详情​

字段描述值
reservation_type预留类型枚举值
registration_code军人注册编号123456789
reservation_method确定何时开始尝试薪资贷款的注销登记，是在信贷业务创建时还是在发行时。枚举值
portability_data可携性数据可携性对象

预留类型表​

枚举值描述
new_credit新信贷
portability可携性
refinancing再融资

预留创建方法表​

注意

非常重要的字段，因为它直接决定何时向 Zetra 提交预留意向请求。

枚举值描述
creation注销登记尝试将在信贷业务创建时开始。
issuing注销登记尝试将在信贷业务发行时开始，即正式化之后。

portability_data 对象字段详情​

字段描述值
token军人提供的密码1234abcd
origin_econsig_idZetra 合同识别码1234567
origin_econsig_idsZetra 合同识别码列表[1234567, 1234568, 1234569]

响应​

STATUS
200
Response Body
{
    "data": {
        "borrower": {
            "document_number": "12345678911",
            "name": "Nome do Devedor",
            "related_party_key": "1fe936e7-0917-4c3d-9206-87958254fa1d"
        },
        "collaterals": [{
            "absolute_amount": null,
            "collateral_constituted": false,
            "collateral_data": {
                "reservation_type": "new_credit",
                "registration_code": "123456789"
            },
            "collateral_key": "c6006572-d66a-45f6-862d-4ecb5b9b5d2d",
            "collateral_type": "military_payroll",
            "created_at": "2023-03-17T20:56:09.200482",
            "external_key": "1c736cd8-a4c7-43d4-8abd-c00ed0cd6450",
            "percentage": 1,
            "updated_at": "2023-03-17T20:56:09.200474"
        }],
        "contract": {
            "number": "0000000003/NDD",
            "signature_information": [{
                "signature_url": null,
                "signer_document_number": "12345678911",
                "signer_email": "email@email.com",
                "signer_external_key": null,
                "signer_name": "Nome do Devedor",
                "signer_role": "issuer"
            }],
            "urls": [
                "https://storage.googleapis.com/live-doc-api/documents/ae66d0cd-1054-4ff5-b1d6-e03aaaa2ff1b/QISCD-NOME_DO_DEVEDOR-CCB-0000000002-20230317183044.pdf"
            ]
        },
        "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": "2023-03-22",
                "external_contract_fee_amount": 0,
                "external_contract_fees": [],
                "first_due_date": "2023-05-07",
                "installments": [{
                        "additional_costs": [],
                        "business_due_date": "2022-05-08",
                        "calendar_days": 34,
                        "due_date": "2023-05-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
                    }, 
                    ... 
                    x 96
                ],
                "issue_amount": 3187.44,
                "net_external_contract_fee_amount": 0,
                "total_iof": 100.44,
                "total_pre_fixed_amount": 3225.1656904289435
            },
            ...
            x 15
        ],
        "iof_charge_method": "financed",
        "requester_identifier_key": "f7fa079e-e02f-469f-a9ba-7a550f8f665f"
    },
    "event_datetime": "2023-03-17 13:54:58",
    "key": "23c89acf-b11b-4988-b738-a0f5ba238c33",
    "status": "waiting_signature",
    "webhook_type": "debt"
}

注销登记​

军队薪资贷款业务创建后，QI 将启动业务的注销登记流程。

注销登记尝试流程从业务创建时开始，并将重试至业务最后一个放款选项日期。

军队可扣除额度注销登记完成后，QI 将通过以下 webhook 通知合作伙伴：

WEBHOOK_TYPE
credit_operation.collateral
STATUS
Success
Webhook Body
{
    "key": "23c89acf-b11b-4988-b738-a0f5ba238c33",
    "data": {
        "collateral_type": "military_payroll",
        "collateral_constituted": true
    },
    "event_time": "2022-10-31 15:23:46",
    "webhook_type": "credit_operation.collateral"
}

如果提供的 token 无效，我们将发送以下 webhook。如果提供的 token 已被使用且需要新 token，也将发送此 webhook。

WEBHOOK_TYPE
credit_operation.collateral
STATUS
Pending Valid Token
Webhook Body
{
    "key": "23c89acf-b11b-4988-b738-a0f5ba238c33",
    "data": {
		"collateral_type": "military_payroll",
		"collateral_data": {
			"reservation_status": "pending_valid_token",
			"cancel_reason": "invalid_token",
		},
		"collateral_constituted": false,
    },
    "event_time": "2022-10-31 15:23:46",
    "webhook_type": "credit_operation.collateral"
}

导致自动取消的响应​

根据 Zetra 的响应，操作将被自动取消。 发生此情况时，我们将以如下格式发送 webhook，取消原因在"cancel_reason"字段中说明

WEBHOOK_TYPE
credit_operation.collateral
STATUS
Canceled
Webhook Body
{
	"data": {
		"cancel_reason": "Contrato de origem não encontrato.",
		"cancel_reason_enumerator": "military_payroll_portability_not_found"
	},
	"event_datetime": "2023-10-10 15:45:21",
	"key": "\<UUID \>",
	"status": "canceled",
	"webhook_type": "debt"

}

枚举值表​

枚举值描述Zetra 代码
military_payroll_military_not_found未找到军人。293
military_payroll_portability_not_found未找到原合同。294
military_payroll_consignable_margin_exceeded可用额度已超出。359

可携性到期​

10 天后，Zetra 将取消等待确认的可携性请求。

因此，要重新启动可携性流程，需要一个新的有效 token。如果存在新的有效 token，提案将返回到可携性意向步骤（预留状态：pending_reservation）。但是，如果不存在有效 token（通常是因为发送的 token 已在之前的可携性意向中使用），提案将更新为 pending_valid_token 状态，等待发送新 token。发送新的有效 token 后，提案将正常继续可携性意向和确认流程。

为通知相关情况，将发送以下 webhook：

WEBHOOK_TYPE
credit_operation.collateral
STATUS
Pending Reservation/Pending Valid Token
Webhook Body
{
    "key": "23c89acf-b11b-4988-b738-a0f5ba238c33",
    "data": {
		"collateral_type": "military_payroll",
		"collateral_data": {
			"reservation_status": "pending_reservation" ou "pending_valid_token",
			"cancel_reason": "expired_portability",
		},
    },
    "event_time": "2022-10-31 15:23:46",
    "webhook_type": "credit_operation.collateral"
}

取消​

要对操作进行永久取消，包括取消可扣除额度的注销登记，应使用以下端点：

注意

需要指出，取消注销登记流程是异步的，即信贷业务的取消不一定意味着取消注销登记已完成。要查询取消注销登记的状态，请参阅获取最后一次请求的响应"。

注意

永久取消也可能自动发生，当操作处于"canceled"状态超过 7 天时会发生这种情况。

请求​

ENDPOINT
/debt/[DEBT-KEY]/cancel_permanently
MÉTODO
POST

操作取消成功：​

操作取消完成后，合作伙伴将收到以下 webhook：

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

发送新的可携性 Token​

可携性 token 是一次性使用的，因此，当之前的 token 被使用或 token 无效时，需要发送新 token。

发送方式是一个简单的调用：

请求​

ENDPOINT
/debt/[DEBT-KEY]/collateral
MÉTODO
PATCH
Request Body
    {
        "portability_data": {
            "token": "12345678"
        }
    }

成功情况​

Response 204​

Response Body
    {}

错误情况​

信息

此请求中只应发送 token，否则流程将返回错误

响应​

Response Body
    {
        "title": "Bad Request",
        "description": "Additional properties are not allowed (<campo extra> was unexpected)",
        "translation": "Schema Inválido",
        "code": "QIT000001"
    }

更改业务的注销登记类型​

专门将操作的注销登记类型从可携性更改为新信贷。 更改后，预留将自动遵循新信贷类型预留的注销登记流程和规则。

请求​

ENDPOINT
/debt/[DEBT-KEY]/collateral
MÉTODO
PATCH
Request Body
    {
        "reservation_type": "new_credit"
    }

成功情况​

Response 204​

Response Body
    {}

错误情况​

响应​

Response Body
    {
        "title": "Bad Request",
        "description": "Additional properties are not allowed (<campo extra> was unexpected)",
        "translation": "Schema Inválido",
        "code": "QIT000001"
    }

获取最后一次请求的响应​

last response 是一种简单直接的方式，用于映射 QI 与 Zetra 之间通信的响应，可以了解该请求的发起时间及获得的返回值（通过枚举值）。

每个枚举值都有详细描述。我们可以在下面更详细地查看 last response 数据的呈现方式。

成功情况​

请求​

ENDPOINT
/debt/[DEBT-KEY]/collateral
MÉTODO
GET

响应​

Response Body
  {
    "collateral_constituted": true,
    "collateral_type": "military_payroll",
    "updated_at": "2023-05-24 19:13:02",
    "collateral_data": {
      "status": "reserved",
      "last_response": {
        "success": [
          {
            "enumerator": "succesfully_reserved"
          }
        ]
      },
      "last_response_event_datetime": "2023-05-22T19:13:02Z"
    }
  }
Response Body Portability
{
    "collateral_constituted": true,
    "collateral_type": "military_payroll",
    "collateral_data": {
        "status": "reserved",
        "last_response": {
            "success": [
                {
                    "enumerator": "successfully_reserved"
                }
            ]
        },
        "last_response_event_datetime": "2023-08-09T19:25:09Z",
        "portability_data": {
            "origin_econsig_id": "2016587",
            "token": "123456"
        }       
    }
}

枚举值表​

枚举值描述详情预留状态
successfully_acceptedReservation request accepted注销登记请求已被接受，正在等待确认pending_confirmation
successfully_reservedReservation made successfully预留已成功注销登记reserved
successfully_deletedReservation successfully deleted预留已成功取消注销登记deleted

错误情况​

请求​

ENDPOINT
/debt/[DEBT-KEY]/collateral
MÉTODO
GET

响应​

Response Body
  {
    "collateral_constituted": false,
    "collateral_type": "military_payroll",
    "updated_at": "2023-05-24 19:13:02",
    "collateral_data": {
      "status": "pending_reservation",
      "last_response": {
        "errors": [
          {
            "enumerator": "invalid_portability_token"
          }
        ]
      },
      "last_response_event_datetime": "2023-05-22T19:13:02Z"
    }
  }

枚举值表​

枚举值描述QI 操作对应 Zetra 代码
waiting_confirmationWaiting Confirmation on Portabilityretry
communication_errorCommunication Error with Zetraretry241
consignable_margin_exccededExceeded consignable marginretry359

未偿余额通知​

未偿余额通知在申请日后的第 5 个工作日发生，所有通知均通过 webhook 以以下信息发送：

WEBHOOK_TYPE
military_payroll.due_balance.status_change
STATUS
processed
Response Body
{
	"webhook_type": "military_payroll.due_balance.status_change",
	"status": "processed",
	"event_datetime": "2024-03-12T19:23:12Z",
	"data": [
		{
			"contract_number": "0000086715/TA",
			"payment_amount": 284.28,
			"balance_limit_date": "2024-03-12"
		},
		{
			"contract_number": "0000086715/BE",
			"payment_amount": 134.00,
			"balance_limit_date": "2024-03-12"
		}
	]
}