可携性 Out

注意！

QI Tech 的 webhooks 不应被严格映射。返回的 webhooks payload 中可能会新增额外字段。

重新发送 Webhooks

您可以按照文档中的详细说明查询和重新发送 webhooks：重新发送 Webhooks。

1. 收到可携性 out 通知

一旦 QI SCD 通过 CTC（信用转移中心）收到可携性申请，合作伙伴将通过以下 webhook 收到通知：

WEBHOOK_TYPE

credit_transfer.received_portability

STATUS

Received

Webhook Body

{
    "webhook_type": "credit_transfer.received_portability",
    "received_portability_status": "received", 
    "key": "673d2872-c6c9-4075-b9ab-4525bcbe4aa1",
    "event_datetime": "2022-07-24T18:29:45",  
    "data": {
        "annual_interest_rate": "20.27",
        "annual_effective_interest_rate": "20.27",
        "number_of_installments": "6",
        "installment_face_value": "201.71",
        "phone_number": "(05)541997558",
        "address": {
            "street": "Rua Longe de Casa",
            "city": "Rio de Janeiro",
            "state": "RJ",
            "number": "112",
            "postal_code": "38300569"
        },
        "due_balance": "1000",
        "due_balance_date": "2022-07-29",
        "issuer_name": "A Random Name",
        "issuer_document_number": "37197645832",
        "reference_date": "2022-08-01",
        "contract_number": "0000049045/UO",
        "origin_credit_operation_key": "7daef1ad-5497-4ec3-92f4-26f8d63bcd80",
        "retention_limit_date": "2022-08-03", 
        "due_balance_limit_date": "2022-08-08", 
        "portability_number": "202207150000001642808",
        "corban_document_number": "08289470514408",
        "source_ispb_number": "0"
    }
}

查阅 received_portability webhook 详细说明表中的字段描述

2. 响应可携性攻击

2.1. 合同留存

重新发送 Webhooks

要留存客户，合作伙伴必须执行**留存证据的上传，并在收到攻击事件（_credit_transfer.received_portability**_）后第 4 个工作日的 18:00 之前将其附加到操作中。

ENDPOINT

/credit_transfer/received_portability/[received_portability_key]

MÉTODO

PATCH

在 Playground 中测试

{
  "received_portability_status": "retained",
  "retention_reason": "issuer_retention",
  "document_type": "received_portability_retention_proof",
  "documents": [
    {
      "file_type": "jpeg",
      "document_key": "3d6fbbbf-55e9-4275-8050-b83b33fdefa6",
      "retention_type": "whatsapp"
    }
  ]
}

注意

不接受压缩文件。

请查阅表格中的请求字段说明

2.2 批准可携性 out

如果客户未被留存，合作伙伴必须在收到可携性攻击通知（credit_transfer.received_portability）后第 4 个工作日的 10:00 之前告知不留存情况。

注意

如果可携性申请在 4 个工作日内未得到响应，QI Tech 将把操作的到期余额返还给提案人（可携性申请人）。

ENDPOINT

/credit_transfer/received_portability/[received_portability_key]

MÉTODO

PATCH

在 Playground 中测试

Request Body
{
	"received_portability_status": "accepted_by_creditor"
}

3. 查询可携性 out 申请

3.1. 查询可携性申请

如需验证可能的状态

ENDPOINT

/credit_transfer/received_portability/[received_portability_key]

MÉTODO

GET

在 Playground 中测试

Response Body

{
	"received_portability_key": "e3bedf31-1e87-4ba4-a36c-d52f7f5c9036",
	"received_portability_status": "accepted",
	"annual_interest_rate": "20.27",
	"annual_effective_interest_rate": "20.27",
	"number_of_installments": "6",
	"installment_face_value": "201.71",
	"phone_number": "(05)541997558",
	"address": {
		"street": "Rua Longe de Casa",
		"city": "Rio de Janeiro",
		"state": "RJ",
		"number": "112",
		"postal_code": "38300569"
	},
	"due_balance": 1000,
	"due_balance_date": "2022-07-29",
	"issuer_name": "A Random Name",
	"issuer_document_number": "37197645832",
	"reference_date": "2022-08-01",
	"contract_number": "0000049045/UO",
	"origin_credit_operation_key": "key",
	"retention_limit_date": "2022-08-03",
	"due_balance_limit_date": "2022-08-08",
	"portability_number": "202207150000001642808",
	"retention_reason": null,
	"canceled_reason": null,
  "corban_document_number": "08289470514408",
  "attached_documents": [
    ],
  "financial_institution_code_number": "001",
  "financial_institution_name": "Banco do Brasil",
  "ispb": "00000000",
  "requester_key": "8511012c-3a3c-4f4d-9f23-dbe437211a8e",
  "requester_name": "Corban LTDA",
  "response_date": null,
  "settlement_date": null,
  "settlement_due_balance": null
}

3.2. 列出可携性申请

ENDPOINT

/credit_transfer/received_portability

MÉTODO

GET

PARÂMETROS

settlement_date, max_portability_date, due_balance_limit_date, received_portability_status, portability_number, contract_number, credit_operation_key

在 Playground 中测试

Response Body

{
	"data": [{
		"received_portability_key": "e3bedf31-1e87-4ba4-a36c-d52f7f5c9036",
		"received_portability_status": "accepted",
		"annual_interest_rate": 1,
		"annual_effective_interest_rate": 1,
		"number_of_installments": 6,
		"installment_face_value": 201.71,
		"phone_number": "(05)541997558",
		"address": {
			"street": "Rua Longe de Casa",
			"city": "Rio de Janeiro",
			"state": "RJ",
			"number": "112",
			"postal_code": "38300569"
		},
		"due_balance": 1000,
		"due_balance_date": "2022-07-29",
		"issuer_name": "A Random Name",
		"issuer_document_number": "37197645832",
		"reference_date": "2022-08-01",
		"contract_number": "0000049045/UO",
		"origin_credit_operation_key": "key",
		"retention_limit_date": "2022-08-03",
		"due_balance_limit_date": "2022-08-08",
		"portability_number": "202207150000001642808",
		"retention_reason": null,
		"canceled_reason": null
	}],
	"pagination": {
		"next_page": null,
		"current_page": 1,
		"total_rows": 0,
		"rows_per_page": 1,
		"total_pages": 0
	}
}

4. Webhooks

以下是流程中可能收到的 webhooks，可查阅状态机了解可能的状态变化（canceled_by_proponent 状态可从任意非终态达到）

4.1. 等待到期余额付款

WEBHOOK_TYPE

credit_transfer.received_portability

STATUS

waiting_settlement

Webhook Body
{
  "webhook_type": "credit_transfer.received_portability",

  "received_portability_key": "673d2872-c6c9-4075-b9ab-4525bcbe4aa1",
  "received_portability_status": "waiting_settlement",
  "event_datetime": "2022-07-24T18:29:45",
  "data": {
    "settlement_due_balance": 120.00,
    "settlement_date": "2022-08-02"
  }
}

4.2. 提案被提案人取消

WEBHOOK_TYPE

credit_transfer.received_portability

STATUS

canceled_by_proponent

Webhook Body
{
  "webhook_type": "credit_transfer.received_portability",
  "received_portability_key": "673d2872-c6c9-4075-b9ab-4525bcbe4aa1",
  "received_portability_status": "canceled_by_proponent",
  "event_datetime": "2022-07-24T18:29:45",
  "data": {}
}

4.3. 可携性已清算

WEBHOOK_TYPE

credit_transfer.received_portability

STATUS

settled

Webhook Body
{
  "webhook_type": "credit_transfer.received_portability",
  "received_portability_key": "673d2872-c6c9-4075-b9ab-4525bcbe4aa1",
  "received_portability_status": "settled",
  "event_datetime": "2022-07-24T18:29:45Z",
  "data": {}
}

4.4. 可携性未清算

如果提案人未在可携性 out 响应（可携性攻击）中返回的到期余额规定期限内付款，提案将因逾期未付而被取消。

WEBHOOK_TYPE

credit_transfer.received_portability

STATUS

canceled_by_creditor

Webhook Body
{
  "webhook_type": "credit_transfer.received_portability",
  "received_portability_key": "673d2872-c6c9-4075-b9ab-4525bcbe4aa1",
  "received_portability_status": "canceled_by_creditor",
  "event_datetime": "2022-07-24T18:29:45",
  "data": {
   "canceled_reason": {
    "enumerator": "not_paid",
    "description": "Decurso de prazo por STR não paga dentro do prazo"
   }
  }
}

5. 沙盒验证 Mock 接口

沙盒环境

使用这些端点在沙盒中模拟可携性 out 流程，无需依赖真实的 CTC/STR 事件。

重要提示！

请勿在沙盒环境中使用真实的个人数据（CPF、CNPJ 等）。

5.1. 模拟收到的可携性

调用此端点后，您将收到 credit_transfer.received_portability webhook（如第 1 节中所述），其数据根据提供的信贷操作计算得出。

ENDPOINT

/mock/credit_transfer/received_portability

MÉTODO

POST

属性

credit_operation_keystring (UUID)必填要转移的信贷操作的密钥。reference_datestring必填可携性的参考日期（格式 YYYY-MM-DD）。ispb_numberstring必填源机构的 ISPB 号码（最多 8 个字符）。origin_contract_typestring可选源合同类型。允许值：payroll、public_agency。默认值：payroll。proposal_typestring可选提案类型。允许值：inss。默认值：inss。

Request Body
{
  "credit_operation_key": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "reference_date": "2026-04-13",
  "ispb_number": "00000000",
  "origin_contract_type": "payroll",
  "proposal_type": "inss"
}

Response — 202 Accepted
{}

5.2. 模拟 STR 清算

批准可携性（第 2.2 节）并收到 waiting_settlement webhook（第 4.1 节）后，使用此端点模拟通过 STR 的清算或付款拒绝。根据选择的 event_type，将触发相应的 webhook（settled 或 canceled_by_creditor）。

ENDPOINT

/mock/credit_transfer/str

MÉTODO

POST

属性

proposal_keystring (UUID)必填提案的密钥（在 waiting_settlement webhook 中返回）。event_typestring必填事件类型。允许值：settlement、payment_rejected。source_branchstring可选源分行代码。默认值："0001"。target_branchstring可选目标分行代码。默认值："0001"。provider_ispbstring可选提供者 ISPB 号码。默认值："99999999"。

Request Body (settlement)
{
  "proposal_key": "9ff557c3-b640-4862-b2c1-ef6f7d9a6a61",
  "event_type": "settlement",
  "source_branch": "0001",
  "target_branch": "0001",
  "provider_ispb": "99999999"
}

Response — 202 Accepted
{}

附件

received_portability webhook 详细说明

字段	描述
key	攻击密钥（received_portability_key）
webhook_type	事件类型
received_portability_status	攻击状态
event_datetime	事件日期
annual_interest_rate	攻击中提供的利率
annual_effective_interest_rate	攻击中提供的 CET
number_of_installments	攻击中提供的分期数
installment_face_value	攻击中提供的分期金额
phone_number	攻击中提供的电话号码
address	攻击中提供的地址
due_balance	攻击中提供的到期余额
due_balance_date	攻击中提供的到期余额参考日期
issuer_name	攻击中提供的借款人姓名
issuer_document_number	攻击中提供的借款人文件号码
reference_date	攻击中提供的信息
contract_number	攻击中提供的合同号
origin_credit_operation_key	信贷操作密钥（DEBT_KEY/CREDIT_OPERATION_KEY）
retention_limit_date	留存截止日期
due_balance_limit_date	告知到期余额的截止日期
portability_number	可携性号码（NU）
corban_document_number	攻击中提供的信息
source_ispb_number	攻击中提供的信息

authorization_term 对象详细说明

字段	必填性	描述
received_portability_status	必填	是否释放余额
retention_reason	留存时必填	留存原因，请查阅留存原因表中的可能枚举值
document_type	留存时必填	必须为 "received_portability_retention_proof"
documents	留存时必填	留存证据
file_type	留存时必填	文档类型，请查阅文档类型表中的可能枚举值
document_key	留存时必填	完成上传后返回的文档密钥
retention_type	留存时必填	留存证据类型，请查阅留存类型表中的可能枚举值

留存原因

枚举值	描述
issuer_retention	客户留存
portability_not_requested	客户未申请可携性

文档类型

枚举值
pdf
jpeg
jpg
png
mp3
wav

备注

留存证据（retention_type）仅接受 jpg、jpeg、png 和 pdf 格式。

留存类型

枚举值
sms
whatsapp

攻击状态

枚举值	描述
received	已接收
waiting_validation	等待验证留存证明文件
canceled_by_proponent	被提案人取消
canceled_by_creditor	被原始债权人取消
retained	已留存
waiting_settlement	可携性已批准，等待清算
settled	已清算

1. 收到可携性 out 通知​

2. 响应可携性攻击​

2.1. 合同留存​

2.2 批准可携性 out​

3. 查询可携性 out 申请​

3.1. 查询可携性申请​

3.2. 列出可携性申请​

4. Webhooks​

4.1. 等待到期余额付款​

4.2. 提案被提案人取消​

4.3. 可携性已清算​

4.4. 可携性未清算​

5. 沙盒验证 Mock 接口​

5.1. 模拟收到的可携性​

属性​

5.2. 模拟 STR 清算​

属性​

附件​

received_portability webhook 详细说明​

authorization_term 对象详细说明​

留存原因​

文档类型​

留存类型​

攻击状态​

攻击状态机​

1. 收到可携性 out 通知

2. 响应可携性攻击

2.1. 合同留存

2.2 批准可携性 out

3. 查询可携性 out 申请

3.1. 查询可携性申请

3.2. 列出可携性申请

4. Webhooks

4.1. 等待到期余额付款

4.2. 提案被提案人取消

4.3. 可携性已清算

4.4. 可携性未清算

5. 沙盒验证 Mock 接口

5.1. 模拟收到的可携性

属性

5.2. 模拟 STR 清算

属性

附件

received_portability webhook 详细说明

authorization_term 对象详细说明

留存原因

文档类型

留存类型

攻击状态

攻击状态机