跳到主要内容

私人养老金手册 - 批注与放款

导航
API 开发中

该 API 仍处于开发阶段，因此本手册可能会有所变动。

注意！

QI Tech 的 Webhooks 不应以严格限制的方式映射。 我们 API 返回的 Webhook payload 中可能会添加额外字段。

Webhook 重发

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

1 - 批注​

Webhooks​

批注成功时，合作伙伴将收到以下 Webhook：

WEBHOOK TYPE
credit_operation.collateral
STATUS
Opened
Webhook Body
{
  "webhook": {
    "key": "<Debt Key>",
    "data": {
      "collateral_data": "collateral_data": {
            "total_gross_amount_lock": 1500,
            "investment_funds": [
                {
                    "susep_process_number": "111111111111",
                    "certificate": "12345678",   
                    "name": "QI Fund Alpha",
                    "document_number": "32402502000135",
                    "class": "",
                    "subclass": "",
                    "lock_gross_amount": 500,
                },
                {
                    "susep_process_number": "222222222222",
                    "certificate": "87654321",
                    "name": "QI Fund Beta",
                    "document_number": "32402502000135",
                    "class": "",
                    "subclass": "",
                    "lock_gross_amount": 500,
                },
                {
                    "susep_process_number": "333333333333",
                    "certificate": "56781234",  
                    "name": "QI Fund Gama",
                    "document_number": "32402502000135",
                    "class": "",
                    "subclass": "",
                    "lock_gross_amount": 500,
                }
            ]
        },
      "collateral_type": "private_pension",
      "collateral_constituted": true
    },
    "event_time": "2025-07-10 02:15:01",
    "webhook_type": "credit_operation.collateral"
  }
}

批注失败​

如果预约失败，将以以下格式发送 Webhook 通知：

WEBHOOK TYPE
private_pension_failed_reservation
STATUS
Failed
Webhook Body
Webhook Body
{
    "key": "<Debt Key>",
    "status": "failed",
    "webhook_type": "private_pension_failed_reservation",
    "event_datetime": "2025-10-26 16:41:28",
    "data": {
        "enumerator": "Fail enumerator.",
        "description": "Descrição da falha.",
    }
}

2 - 解除批注​

合同的解除批注通过永久取消路由执行。该路由将合同设为最终状态，不可重试，并触发已批注保证金的解除批注。

要执行永久取消，请使用以下接口：

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

3 - 放款失败​

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 - 重新提交付款​

更改放款日期而不影响操作的财务价值。

POST
/debt/DEBT-KEY/change_disbursement_date

请求​

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

响应​

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