跳到主要内容

书写 Webhooks

概述​

书写 webhooks 允许您实时接收有关商业票据发行流程中状态变更和重要事件的通知。当事件发生时，QI Tech 会自动向您系统中配置的 URL 发送 HTTP POST 载荷。

Webhooks 配置​

要接收 webhooks，您需要在系统中配置端点 URL。请参阅 webhooks 配置文档 了解如何注册和管理您的 webhook URL 的更多详情。

认证和安全​

QI Tech 发送的所有 webhooks 在 Signature header 中包含 HMAC-SHA256 签名。您的系统必须验证此签名，以确保接收数据的真实性和完整性。有关验证流程的更多信息，请参阅 webhooks 认证文档。

可用事件​

发行人管理​

发行人登记已批准​

当发行人的登记被合规团队批准时发送。

Event Type: issuer_management.issuer_status_change

Payload:

{
  "event_type": "issuer_management.issuer_status_change",
  "event_datetime": "2025-07-30T15:32:00Z",
  "event_data": {
    "issuer_key": "18c4d162-1b1b-4c3a-b7a7-5f1200723c43",
    "status": "approved"
  }
}

发行人登记未批准​

当发行人的登记被合规团队拒绝时发送。

Event Type: issuer_management.issuer_status_change

Payload:

{
  "event_type": "issuer_management.issuer_status_change",
  "event_datetime": "2025-07-30T15:32:00Z",
  "event_data": {
    "issuer_key": "18c4d162-1b1b-4c3a-b7a7-5f1200723c43",
    "status": "reproved"
  }
}

投资人管理​

投资人登记已批准​

当投资人的登记被合规团队批准时发送。

Event Type: investor_management.investor_status_change

Payload:

{
  "event_type": "investor_management.investor_status_change",
  "event_datetime": "2025-07-30T15:32:00Z",
  "event_data": {
    "investor_key": "18c4d162-1b1b-4c3a-b7a7-5f1200723c43",
    "status": "approved"
  }
}

投资人登记未批准​

当投资人的登记被合规团队拒绝时发送。

Event Type: investor_management.investor_status_change

Payload:

{
  "event_type": "investor_management.investor_status_change",
  "event_datetime": "2025-07-30T15:32:00Z",
  "event_data": {
    "investor_key": "18c4d162-1b1b-4c3a-b7a7-5f1200723c43",
    "status": "reproved"
  }
}

操作管理​

操作已批准​

当操作被合规团队批准并准备好发送签名时发送。

Event Type: commercial_paper.operation_status_change

Payload:

{
  "event_type": "commercial_paper.operation_status_change",
  "event_datetime": "2025-07-30T15:45:00Z",
  "event_data": {
    "operation_key": "89c7f73a-c184-400c-bb2a-dd4424075a4f",
    "status": "pending_signature_submission"
  }
}

操作未批准​

当操作在审核中被拒绝时发送（自动预审或合规团队的人工审核）。该操作不会进入签署流程。

Event Type: commercial_paper.operation_status_change

Payload:

{
  "event_type": "commercial_paper.operation_status_change",
  "event_datetime": "2025-07-30T15:45:00Z",
  "event_data": {
    "operation_key": "89c7f73a-c184-400c-bb2a-dd4424075a4f",
    "status": "compliance_reproved",
    "reproval_reason": {
      "maximum_overdue_by_debtor": "Issuer 12.345.678/0001-90 holds another asset that is more than 0 days overdue."
    }
  }
}

reproval_reason 字段以「键—说明」对象的形式提供拒绝原因。在自动预审中，每个键为导致该操作被拒绝的合格性规则。当拒绝未记录任何原因时，该字段可能为 null。

操作已发送签名​

当操作被发送给相关方签名时发送。

Event Type: commercial_paper.operation_status_change

Payload:

{
  "event_type": "commercial_paper.operation_status_change",
  "event_datetime": "2025-07-30T15:45:00Z",
  "event_data": {
    "operation_key": "89c7f73a-c184-400c-bb2a-dd4424075a4f",
    "status": "waiting_signature"
  }
}

操作已签名并发行​

当操作被所有各方签署时发送。此事件确认商业票据已成功发行。

Event Type: commercial_paper.operation_status_change

Payload:

{
  "event_type": "commercial_paper.operation_status_change",
  "event_datetime": "2025-07-30T15:45:00Z",
  "event_data": {
    "operation_key": "89c7f73a-c184-400c-bb2a-dd4424075a4f",
    "status": "issued",
    "signed_files_url": "https://storage.googleapis.com/commercial-paper-bucket/89c7f73a-c184-400c-bb2a-dd4424075a4f/signed_files?X-Goog-Algorithm=..."
  }
}

signed_files_url 字段提供一个下载链接，其中包含该操作所有已签署合同的压缩包，适用于所有签署方式。该链接自 Webhook 发送起 7 天内有效。

操作已取消​

当操作被取消时发送。

Event Type: commercial_paper.operation_status_change

Payload:

{
  "event_type": "commercial_paper.operation_status_change",
  "event_datetime": "2025-07-30T15:45:00Z",
  "event_data": {
    "operation_key": "89c7f73a-c184-400c-bb2a-dd4424075a4f",
    "status": "canceled"
  }
}

认购管理​

认购已发送签名​

当认购被创建并发送给投资人签名时发送。

Event Type: subscription.subscription_status_change

Payload:

{
  "event_type": "subscription.subscription_status_change",
  "event_datetime": "2025-07-30T16:05:00Z",
  "event_data": {
    "integralization_key": "491e4f5c-a173-4ab8-8ec6-24e7aa228099",
    "subscription_key": "eb791639-2931-41df-b087-731d40f07a7c",
    "status": "waiting_signature"
  }
}

认购已签名​

当认购被所有各方签署并等待付款时发送。

Event Type: subscription.subscription_status_change

Payload:

{
  "event_type": "subscription.subscription_status_change",
  "event_datetime": "2025-07-30T16:05:00Z",
  "event_data": {
    "integralization_key": "491e4f5c-a173-4ab8-8ec6-24e7aa228099",
    "subscription_key": "eb791639-2931-41df-b087-731d40f07a7c",
    "status": "waiting_payment"
  }
}

认购已完成​

当认购在付款确认后完全完成时发送。

Event Type: subscription.subscription_status_change

Payload:

{
  "event_type": "subscription.subscription_status_change",
  "event_datetime": "2025-07-30T16:05:00Z",
  "event_data": {
    "integralization_key": "491e4f5c-a173-4ab8-8ec6-24e7aa228099",
    "subscription_key": "eb791639-2931-41df-b087-731d40f07a7c",
    "status": "finished"
  }
}

认购已取消​

当认购因整合在合格性审核中被拒绝而取消时发送。对应的整合认购单和签署信封会一并取消。

Event Type: subscription.subscription_status_change

Payload:

{
  "event_type": "subscription.subscription_status_change",
  "event_datetime": "2025-07-30T16:05:00Z",
  "event_data": {
    "operation_key": "89c7f73a-c184-400c-bb2a-dd4424075a4f",
    "integralization_key": "491e4f5c-a173-4ab8-8ec6-24e7aa228099",
    "subscription_key": "eb791639-2931-41df-b087-731d40f07a7c",
    "status": "canceled",
    "cancellation_reason": "ineligible",
    "ineligible_reasons": {
      "maximum_overdue_by_debtor": "Issuer 12.345.678/0001-90 holds another asset that is more than 0 days overdue."
    }
  }
}

cancellation_reason 字段以稳定的取值标识取消原因。当取值为 ineligible 时，ineligible_reasons 字段以「键—说明」对象的形式列出导致该整合被拒绝的合格性规则及对应说明。

认购付款管理​

付款凭证已添加​

当付款凭证被添加并等待确认时发送。

Event Type: subscription_payment.subscription_payment_status_change

Payload:

{
  "event_type": "subscription_payment.subscription_payment_status_change",
  "event_datetime": "2025-07-30T16:05:00Z",
  "event_data": {
    "integralization_key": "491e4f5c-a173-4ab8-8ec6-24e7aa228099",
    "subscription_key": "eb791639-2931-41df-b087-731d40f07a7c",
    "subscription_payment_key": "1413020c-6965-40fb-a162-632459d35fd1",
    "status": "waiting_confirmation"
  }
}

付款凭证已批准​

当付款凭证被批准和确认时发送。

Event Type: subscription_payment.subscription_payment_status_change

Payload:

{
  "event_type": "subscription_payment.subscription_payment_status_change",
  "event_datetime": "2025-07-30T16:05:00Z",
  "event_data": {
    "integralization_key": "491e4f5c-a173-4ab8-8ec6-24e7aa228099",
    "subscription_key": "eb791639-2931-41df-b087-731d40f07a7c",
    "subscription_payment_key": "1413020c-6965-40fb-a162-632459d35fd1",
    "status": "confirmed"
  }
}

事件流程​

商业票据发行流程​

  1. 发行人登记 → issuer_status_change（approved/reproved）
  2. 投资人登记 → investor_status_change（approved/reproved）
  3. 创建操作 → operation_status_change（pending_signature_submission）
  4. 发送签名 → operation_status_change（waiting_signature）
  5. 操作发行 → operation_status_change（issued）

认购流程​

  1. 创建认购 → subscription_status_change（waiting_signature）
  2. 签名完成 → subscription_status_change（waiting_payment）
  3. 添加凭证 → subscription_payment_status_change（waiting_confirmation）
  4. 付款确认 → subscription_payment_status_change（confirmed）
  5. 认购完成 → subscription_status_change（finished）

最佳实践​

  1. 快速响应：尽快返回 HTTP 2xx 状态以确认收到 webhook。
  2. 异步处理：对于耗时操作，立即确认接收并异步处理事件。
  3. 幂等性：实现幂等逻辑，因为网络故障时 webhooks 可能会重新发送。
  4. 签名验证：处理 webhook 前务必验证 HMAC 签名。
  5. 日志和监控：保留所有收到的 webhooks 的详细日志，用于审计和调试。

参考​