私人薪资抵押贷款手册 - 信贷操作跟踪

1. 正式化

赢得内部拍卖后，合作伙伴应等待收到正式化 webhook，表明借款人已完成 QI Sign 的签署流程。

{
    "key": "<credit_operation_key>",
    "status": "signed",
    "signers": [
        {
            "id": "3271efd3-89ba-43aa-b032-af9a459e6096",
            "images": {
                "face_image_url": "https://qisign-face-images-bucket-sandbox.s3.amazonaws.com/fad7f924-d210-4ec4-9565-a57662a0a65a.jpeg",
                "document_back_url": "https://qisign-personal-documents-bucket-sandbox.s3.amazonaws.com/8c7b68ba-07ad-4188-82ae-679833b2843b.jpeg",
                "document_front_url": "https://qisign-personal-documents-bucket-sandbox.s3.amazonaws.com/f63cd291-5668-4926-be5d-9290aeda3f6e.jpeg",
                "document_back_template": "cnh_back",
                "document_front_template": "cnh_front"
            },
            "biometry": {
                "face_validation": {
                    "score": 80,
                    "provider": "qitech",
                    "available": true
                },
                "fraud_base_flag": false
            },
            "document": {
                "template": "cnh_front",
                "face_match_score": 100
            },
            "liveness": {
                "result": "live"
            },
            "signed_at": "2025-04-09T19:59:39Z",
            "ip_address": "182.224.219.198",
            "signer_data": {
                "name": "Nome Trabalhador",
                "email": "exemplo@qitech.com.br",
                "phone": {
                    "number": "829549234",
                    "area_code": "11",
                    "international_dial_code": "55"
                },
                "address": {
                    "uf": "SP",
                    "city": "Sao Paulo",
                    "number": "123",
                    "street": "Rua tal do sal",
                    "complement": "Ap 23",
                    "postal_code": "00000-000",
                    "neighborhood": "Pinheiros"
                },
                "pix_key": "pix03@pix03.com",
                "birthdate": "1996-03-13",
                "document_number": "504.856.400-66",
                "document_submission_method": "email",
                "authentication_submission_method": "sms"
            }
        }
    ],
    "webhook_type": "laas.credit_operation.status_change",
    "event_datetime": "2025-04-09 20:00:19",
    "signed_contract_url": "https://storage.googleapis.com/sandbox-doc-api/documents/9b55450e-fca5-44f2-9118-5851ed4bd92e/RESTAURANTEBEBBER-TRABALHADOR_SICQ-CCB-0000195364-2230409195718_signed.pdf"
}

签署失败时，合作伙伴将收到以下模型的 webhook。

{
  "key": "e8e28023-fa00-4d12-a410-ede4157957ea",
  "data": {
    "cancel_reason": "Validação facial não alcançou a pontuação mínima permitida",
    "cancel_reason_enumerator": "face_validation_score"
  },
  "status": "canceled",
  "webhook_type": "laas.credit_operation.status_change",
  "event_datetime": "2025-11-28 17:35:07"
}

2. 提案确认

发送第二个 webhook，通知操作正在等待核批授权调用。

WEBHOOK TYPE

laas.private_payroll.reservation_status_change

Webhook Body

{
    "webhook_type": "laas.private_payroll.reservation_status_change",
    "data": {
        "reservation_status": "pending_requester_authorization"
    },
    "key": "<credit_operation_key>",
    "event_datetime": "2025-04-09T20:00:20Z",
    "status": "pending_requester_authorization"
}

此时合作伙伴可以决定继续放款操作或取消提案：

授权核批

要继续核批，需进行以下调用：

Request

PATCH

/private_payroll/reservation/external_key/EXTERNAL-KEY/authorize

Response

STATUS

202 (OK)

Response Body

{
    "reservation_key": "<credit_operation_key>",
    "document_number": "12345678901",
    "registration_number": "99999999999-A", 
    "employer_document_number": "12345678901234",
    "external_key": "abc123def456",
    "contract_number": "2024001234",
    "inclusion_date": "2024-03-18",
    "disbursement_date": "2024-03-20",
    "contract_data": {
        "amount": 5000.00,
        "installments": 12,
        "interest_rate": 0.018
    },
    "reservation_data": {
        "installment_value": 500.00,
        "margin_value": 450.00
    },
    "reservation_status": "authorized"
}

取消操作

若不继续核批，需要取消操作。

如果操作来自拍卖，可以通过永久取消端点完成，方式与第6项 - 取消核批相同。

如果操作来自主动流程，则应通过本手册中的端点进行取消。

重要

external_key 字段是信贷操作的 UUID，与 debt_key 和 credit_operation_key 相同。

3 - 核批

核批成功

核批成功时，合作伙伴将收到以下 webhook：

WEBHOOK TYPE

credit_operation.collateral

collateral_constituted

True

Webhook Body

{
  "webhook": {
    "key": "<credit_operation_key>",
    "data": {
      "collateral_data": {},
      "collateral_type": "private_payroll",
      "collateral_constituted": true
    },
    "event_time": "2025-07-10 02:15:01",
    "webhook_type": "credit_operation.collateral"
  }
}

核批失败

核批失败时，将发送包含 DATAPREV 批评信息的 webhook。核批失败的可能原因可在核批失败原因表中查阅。根据核批错误，QI 将保持提案处于"重试"状态，进行新的核批尝试，直到操作被手动取消或放款选项耗尽为止。

WEBHOOK TYPE

credit_operation.collateral

collateral_constituted

False

Webhook Body

Webhook Body
{
    "key": "72926c65-35a5-4060-b5ec-af8661d8546a",
    "data": {
      "collateral_data": {
        "status": "pending_reservation",
        "last_response": {
          "errors": [
            {
              "enumerator": "monthly_interest_rate_exceeds_active_proposal"
            }
          ]
        },
        "last_response_event_datetime": "2025-10-10T19:45:39Z"
      },
      "collateral_type": "private_payroll",
      "collateral_constituted": false
    },
    "event_time": "2025-10-10 00:07:21",
    "webhook_type": "credit_operation.collateral"
}

4 - 放款

核批成功后，操作将自动进入放款阶段。

放款成功

WEBHOOK TYPE

laas.credit_operation.status_change

STATUS

opened

Webhook Body

放款失败

WEBHOOK TYPE

laas.credit_operation.status_change

STATUS

canceled

Webhook Body

{
    "key": "<UUID>",
    "data": {
      "cancel_reason": "A conta de destino encontra-se bloqueada.",
      "cancel_reason_enumerator": "blocked_account"
    },
    "status": "canceled",
    "webhook_type": "laas.credit_operation.status_change",
    "event_datetime": "2025-10-12 09:54:46"
}

放款失败

若放款失败，必须对提案采取行动，因为保证金不会自动取消核批。

合作伙伴需要决定联系借款人以请求更新银行数据，从而重新提交债务还款，或者合作伙伴进行债务永久取消调用以取消薪资抵押保证金。

5 - 重新提交还款

要重试债务放款，需进行以下调用，同时更新放款日期和银行数据（如果是同一银行账户重试，则只需发送放款日期参数即可）。

可能的放款账户 payload 示例请参见放款 payload 示例页面。对于此 API，payload 中的 disbursement_bank_accounts 已更名为 disbursement_account。

要重新提交债务，需使用 auction_proposal_key 发起请求。

ENDPOINT

- /private_payroll_auction/auction_proposal/{auction_proposal_key}/change_disbursement_date

MÉTODO

- PATCH

{
    "disbursement_date": "2025-12-12",
    "disbursement_account": {
        "document_number": "31233261000185",
        "name": "Jorge Augusto Salgado Salhani",
        "pix_key": "2f205c99-3161-4120-badd-854039d12de6",
        "pix_transfer_type": "key"
    }
}

6 - 取消核批

要永久取消操作并取消保证金核批，需进行以下调用：

Request

ENDPOINT

- /private_payroll_auction/auction_proposal/{auction_proposal_key}/cancel

MÉTODO

- PATCH

Response

STATUS

- 202 (Accepted)

Response Body: 提案已取消

{
  "auction_proposal_key": "814e7ed3-4080-4cae-a853-8e12812817ea",
  "status": "cancelled"
}

修改成功时将返回状态 200。

STATUS

- 200

若发送的 payload 格式有误，将返回无效 schema 错误

STATUS

- 400

7 - 核批查询

要查询核批数据及核批或取消核批的协议凭证，可使用以下端点：

核批凭证

可使用此方法查询核批、取消核批和暂停凭证。protocol_type 的可能枚举值请见协议类型表

Request

GET

/private_payroll/reservation/external_key/[DEBT-KEY]

Response

STATUS

200 OK

Response Body

{
    "data": [
        {
            "reservation_key": "310754e1-cef2-4b19-ba04-7b1c0b575276",
            "document_number": "04142652117",
            "registration_number": "SECAIXADEA00000000000000006258",
            "employer_name": null,
            "admission_date": null,
            "employer_document_number": "04311093000126",
            "external_key": "1d900fed-5ed2-4149-8702-f8dab595b590",
            "contract_number": "179799466",
            "inclusion_date": "2025-09-30",
            "disbursement_date": "2025-02-06",
            "contract_data": {
                "iof": 227.64,
                "periods": [
                    {
                        "amount": 338.22,
                        "due_date": "2025-04-20"
                    },
                    {
                        "amount": 338.22,
                        "due_date": "2025-05-20"
                    },
                    {
                        "amount": 338.22,
                        "due_date": "2025-06-20"
                    },
                    {
                        "amount": 338.22,
                        "due_date": "2025-07-20"
                    },
                    {
                        "amount": 338.22,
                        "due_date": "2025-08-20"
                    }
                ],
                "total_amount": 6680.9,
                "annual_cet_rate": 0.7176,
                "contract_number": "179799466",
                "disbursed_amount": 6090.9,
                "monthly_cet_rate": 0.0461,
                "disbursement_date": "2025-02-06",
                "annual_interest_rate": 0.6163544955,
                "disbursement_end_date": "2025-02-06",
                "monthly_interest_rate": 0.0408
            },
            "reservation_type": "rollover",
            "reservation_status": "reserved",
            "protocols": {
                "reservation": {
                    "receipt_url": "[URL]",
                    "receipt_data": {
                        "contract_number": "XXX0123456789",
                        "protocol_number": "21134056260",
                        "reservation_competence": "2026-03",
                        "installment_value": 468.6,
                        "protocol_type": "reservation",
                        "number_of_installments": 12,
                        "operation_datetime": "30/01/2026 20:21:22"
                    },
                    "protocol_key": "d32342f-369a-4e12-8634-4dfb494d3038"
                },
                "documents_inclusion": {
                    "receipt_data": {
                        "contract_number": "XXX0123456789",
                        "operation_datetime": "30/01/2026 20:21:29",
                        "number_of_installments": 12,
                        "protocol_number": "21134054053",
                        "installment_value": 468.6,
                        "protocol_type": "documents_inclusion"
                    },
                    "receipt_url": "[URL]",
                    "protocol_key": "ae018749-7982-4547-92aa-12455e8bafe7"
                }
            },
        }
    ],
    "pagination": {
        "current_page": 1,
        "next_page": 2,
        "rows_per_page": 1
    }
}

附件

重新提交放款详情

字段	类型	描述
`disbursement_date`	string	新的放款日期，格式 YYYY-MM-DD，非必填
`disbursement_account`	dict	放款账户数据，非必填

核批失败原因

枚举值	描述	QI 操作
monthly_interest_rate_exceeds_active_proposal	QI 在借款人 CTPS 应用中有一个利率低于本次核批尝试的有效提案	重试
margin_exceeded	薪资抵押保证金超额	重试
allowed_number_of_contracts_exceeded	超过最大合同数量	取消操作
employment_relationship_blocked	雇佣关系被借款人锁定（可通过 CTPS 应用解锁）	取消操作

协议类型

枚举值	描述
reservation	核批
documents_inclusion	文件提交（向 DATAPREV 发送正式化文件的流程）
suspension	暂停
deletion	删除

1. 正式化​

2. 提案确认​

授权核批​

Request​

Response​

取消操作​

3 - 核批​

核批成功​

核批失败​

4 - 放款​

放款成功​

放款失败​

5 - 重新提交还款​

6 - 取消核批​

Request​

Response​

7 - 核批查询​

Request​

Response​

附件​

重新提交放款详情​

核批失败原因​

协议类型​

1. 正式化

2. 提案确认

授权核批

Request

Response

取消操作

3 - 核批

核批成功

核批失败

4 - 放款

放款成功

放款失败

5 - 重新提交还款

6 - 取消核批

Request

Response

7 - 核批查询

Request

Response

附件

重新提交放款详情

核批失败原因

协议类型