跳到主要内容

私人薪资抵押贷款手册 - 核批与放款

导航
注意！

QI Tech 的 webhook 不应进行严格映射。 返回的 webhook payload 中可能包含额外字段。

重新发送 Webhook

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

1. 提案确认​

在主动流程中，可以配置环境，使操作在借款人完成债务正式化后立即进入核批和放款阶段，否则将发送 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": "<Debt Key>",
    "event_datetime": "2025-04-09T20:00:20Z",
    "status": "pending_requester_authorization"
}

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

授权核批​

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

Request​

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

Response​

STATUS
200 (OK)
Response Body
{
    "reservation_key": "<Debt 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"
}

取消操作​

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

如果操作来自主动流程，可以通过永久取消端点完成，方式与第5项 - 取消核批相同。

如果操作来自拍卖，则应通过拍卖文档中的提案取消端点进行取消。

重要

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

2 - 核批​

核批成功​

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

WEBHOOK TYPE
credit_operation.collateral
collateral_constituted
True
Webhook Body
{
  "webhook": {
    "key": "<UUID>",
    "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"
}

3 - 放款​

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

放款成功​

WEBHOOK TYPE
debt
STATUS
disbursed
Webhook Body
 {
    "key": "8351238-1272-46b2-292b-7161a05c5161",
    "data": {
      "installments": [
        {
          "due_date": "2026-04-28",
          "total_amount": 180.75,
          "installment_key": "6286548-015a-4f26-8fb5-0d23f34554e",
          "pre_fixed_amount": 180.75,
          "installment_number": 1,
          "principal_amortization_amount": 0.0
        },
        {
          "due_date": "2026-05-28",
          "total_amount": 180.75,
          "installment_key": "b3e719e6-24fc-4ddf-a8b8-ee9012342ba6",
          "pre_fixed_amount": 180.75,
          "installment_number": 2,
          "principal_amortization_amount": 0.0
        },
        {
          "due_date": "2026-06-28",
          "total_amount": 180.75,
          "installment_key": "3652fb45-4304-4f8e-84ff-1234307042cc",
          "pre_fixed_amount": 180.75,
          "installment_number": 3,
          "principal_amortization_amount": 0.0
        },
        {
          "due_date": "2026-07-28",
          "total_amount": 180.75,
          "installment_key": "7e2d4334-b963-4a77-1234-4e4fcb1986f8",
          "pre_fixed_amount": 180.75,
          "installment_number": 4,
          "principal_amortization_amount": 0.0
        },
        {
          "due_date": "2026-08-28",
          "total_amount": 180.75,
          "installment_key": "a1ab6f5b-321b-41a0-a608-0eb54a261014",
          "pre_fixed_amount": 180.75,
          "installment_number": 5,
          "principal_amortization_amount": 0.0
        },
        {
          "due_date": "2026-09-28",
          "total_amount": 180.75,
          "installment_key": "7d423192-10d4-45c6-8353-7c3be28ee368",
          "pre_fixed_amount": 180.75,
          "installment_number": 6,
          "principal_amortization_amount": 0.0
        }
      ],
      "ted_receipt_list": [
        {
          "fee": 0,
          "url": "[URL]",
          "amount": 2444.15,
          "origin": {
            "name": "QI SOCIEDADE DE CRÉDITO DIRETO S.A.",
            "type": "payment_account",
            "branch": "0001",
            "document": "32402502000135",
            "bank_code": "329",
            "account_key": "65463575-3456-4345-9787-146868523667",
            "branch_digit": null,
            "account_digit": "1",
            "account_branch": "0001",
            "account_number": "0000025",
            "financial_institution_name": "QI SCD S.A."
          },
          "timestamp": "2026-01-29T20:03:44",
          "description": "12431420 0134 71234489-3 99999999999 - Lucas Blau Mattos",
          "destination": {
            "name": "Lucas Blau Mattos",
            "type": "checking_account",
            "branch": "0001",
            "purpose": "Crédito PIX em Conta",
            "document": "99999999999",
            "bank_ispb": "18236120",
            "branch_digit": null,
            "account_digit": "3",
            "account_number": "71234489",
            "financial_institution_name": "NU PAGAMENTOS - IP"
          },
          "end_to_end_id": "E32402502202601291954msTASDFEGS",
          "transaction_key": "e89dc7af-165d-4534-b345-11345625d2c6",
          "origin_transaction_key": "3415085f-1254-2153-a254-b1254215279e"
        }
      ],
      "requester_identifier_key": "1235cd2f-6345-4025-a334-a1435269fe11"
    },
    "status": "disbursed",
    "webhook_type": "debt",
    "event_datetime": "2026-01-29 20:03:45"
  }

放款失败​

TED​

TED 放款失败时

WEBHOOK TYPE
debt
STATUS
canceled
Webhook Body
 {
     "key": "<Debt Key>",
     "status": "canceled",
     "webhook_type": "debt",
     "event_datetime": "2025-03-18 16:41:28",
     "data": {
         "ted_refusal": {
             "transaction_key": "16faabfc-3876-437d-a4f6-aae17a1d68c9",
             "description": "341 0000 000000-7 12345678900 - NOME DO EMPREGADO",
             "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 DO EMPREGADO",
                 "purpose": "Crédito em Conta",
                 "type": "checking_account",
                 "branch_digit": null,
                 "document": "12345678900",
                 "bank_code": "341",
                 "account_digit": "7"
             }
         },
         "cancel_reason": "ted_refusal"
     }
 }

PIX​

PIX 放款失败时

WEBHOOK TYPE
debt
STATUS
canceled
Webhook Body
{
    "key": "<Debt Key>",
    "status": "canceled",
    "webhook_type": "debt",
    "event_datetime": "2025-03-18 16:41:28",
    "data": {
        "cancel_reason": "pix_refusal",
        "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."
        }
    }
}
放款失败

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

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

4 - 重新提交还款​

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

可能的放款账户 payload 示例请参见放款 payload 示例页面。

Request​

POST
/debt/DEBT-KEY/change_disbursement_date

Request​

Request Body
{
    "disbursement_date": "2025-03-19",
    "disbursement_bank_accounts": [
        {
            "branch_number": "1232",
            "account_digit": "4",
            "account_number": "412412412",
            "account_type": "checking_account",
            "document_number": "<CPF DO TRABALHADOR>",
            "bank_code": 184,
            "ispb_number": "17298092",
            "name": "<NOME DO TRABALHADOR>",
            "percentage_receivable": 100
        }
    ]
}

Response​

STATUS
200 OK
Response Body
{
    "disbursement_date": "2025-03-19",
    "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
        }
    ]
}

5 - 取消核批​

合同的取消核批通过永久取消路由完成。该路由为合同设置最终状态，不可重试，并触发已核批保证金的取消核批。

要执行永久取消，请使用以下端点：

Request​

POST
/debt/DEBT-KEY/cancel_permanently

Webhooks​

WEBHOOK TYPE
debt
STATUS
canceled_permanently
Webhook Body
{
    "key": "<Debt Key>",
    "status": "canceled_permanently",
    "webhook_type": "debt",
    "event_datetime": "2025-03-18 16:41:28",
    "data": {}
}

6 - 核批查询​

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

核批凭证

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

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

附件​

核批失败原因​

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

协议类型​

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