可携性 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",
    }
  ]
}

注意

不接受压缩文件。

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

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"
   }
  }
}

附件

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	留存时必填	完成上传后返回的文档密钥

留存原因

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

文档类型

枚举值
pdf
jpeg
jpg
png
mp3
wav

攻击状态

枚举值	描述
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. 可携性未清算​

附件​

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. 可携性未清算

附件

received_portability webhook 详细说明

authorization_term 对象详细说明

留存原因

文档类型

攻击状态

攻击状态机