跳到主要内容

薪资卡手册 - Webhooks

导航
API 开发中

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

1. 全局状态变更 Webhook​

为跟踪申请进度（签名完成、入网失败、放款完成或卡片发行），API 发送一个统一的 Webhook 通知预约状态变更。

WEBHOOK TYPE
laas.payroll_card_reservation.status_change

Webhook 通用结构​

字段类型描述
keystring卡片预约密钥
statusstring预约的新状态
webhook_typestringlaas.payroll_card_reservation.status_change
event_datetimestring事件日期和时间
dataobject包含状态变更相关数据的对象

场景​

A. 签名完成（Pending Onboarding）​

当文件通过 Qi Sign 或外部方式签名完成时触发。预约状态变更为 pending_onboarding，流程进入入网阶段。

返回预约的附件文件列表以及签名人的面部分析数据。

Payload 示例
{
    "key": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "pending_onboarding",
    "webhook_type": "laas.payroll_card_reservation.status_change",
    "event_datetime": "2025-01-15T14:30:00Z",
    "data": {
        "attached_documents": [
            {
                "document_key":"332017f4-a0d6-463a-8557-e925a9485251",
                "document_type":"payroll_card_term",
                "document_certifier":"qi_sign",
                "document_status":"signed",
                "document_batch_key":"f28bf87a-11cd-4d89-89c0-19229a1b31a7",
                "document_url": "https://storage.googleapis.com/example_document.pdf",
                "signature_url": "https://storage.googleapis.com/example_document_signed.pdf",
            },
            {
                "document_key":"0f0651de-bf3f-45f8-891f-f81b9c24df10",
                "document_type":"payroll_card_consent_term",
                "document_certifier":"qi_sign",
                "document_status":"signed",
                "document_batch_key":"f28bf87a-11cd-4d89-89c0-19229a1b31a7",
                "document_url": "https://storage.googleapis.com/example_document.pdf",
                "signature_url": "https://storage.googleapis.com/example_document_signed.pdf",
            },
            {
                "document_key":"910e8de5-16af-4bc5-8ee1-4a0652ca0cbf",
                "document_type":"withdrawal_operation_term",
                "document_certifier":"qi_sign",
                "document_status":"signed",
                "document_batch_key":"f28bf87a-11cd-4d89-89c0-19229a1b31a7",
                "document_url": "https://storage.googleapis.com/example_document.pdf",
                "signature_url": "https://storage.googleapis.com/example_document_signed.pdf",
            },
            {
                "document_key":"b1c3e915-6707-49f5-85a9-398ef997fdad",
                "document_type":"selfie",
                "document_certifier":"qi_sign",
                "document_status":"generated",
                "document_url":"https://storage.googleapis.com/selfie.jpeg"
            },
            {
                "document_key":"5769a335-a2ac-4913-a742-38b9d1e4abd2",
                "document_type":"document_identification",
                "document_certifier":"qi_sign",
                "document_status":"generated",
                "document_url":"https://storage.googleapis.com/cnh.jpeg"
            },
            {
                "document_key":"75577d34-4ebd-4488-aca8-b064e603c973",
                "document_type":"document_identification_back",
                "document_certifier":"qi_sign",
                "document_status":"generated",
                "document_url":"https://storage.googleapis.com/cnh_back.jpeg"
            }
        ],
        "signature_data": {
            "document_similarity_score": 1,
            "similarity_score": 0.75,
            "biometry_analysis_reference": "internal",
        }
    }
}
响应体详情
字段类型描述
attached_documentsarray为预约创建的文件列表
signature_dataobject签名时收集的生物特征数据
signature_data Payload​
字段类型描述
document_similarity_scorenumber签署人与所发送文件之间的生物特征相似度分数（0-1）
similarity_scorenumber签署人与人脸数据库中找到的参考之间的生物特征相似度分数（0-1）
biometry_analysis_referencestring用于计算生物特征相似度分数的人脸数据来源

B. 发送附加文件（Pending Additional Documents Submission）​

当保证金在 Dataprev 成功预约或由于附加文件（视频）被拒绝而从验证阶段返回时触发。

此 Webhook 表示操作正在等待通过 /additional_documents 接口发送（或重新发送）确认视频。如果是因拒绝而重新发送，payload 将返回 rejection_reason 字段。

Payload 示例
{
    "key": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "pending_additional_documents_submission",
    "webhook_type": "laas.payroll_card_reservation.status_change",
    "event_datetime": "2025-01-15T16:00:00Z",
    "data": {
        "rejection_reason": "Vídeo sem áudio ou ilegível" // 仅在文件被拒绝后从 pending_additional_documents_validation 状态返回时出现
    }
}

C. 附加文件验证（Pending Additional Documents Validation）​

确认视频成功发送后触发。状态变更为 pending_additional_documents_validation，表示视频/附加文件已进入验证和分析队列。

Payload 示例
{
    "key": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "pending_additional_documents_validation",
    "webhook_type": "laas.payroll_card_reservation.status_change",
    "event_datetime": "2025-01-15T16:15:00Z",
    "data": {}
}

D. 附加文件已批准（Pending Withdrawal Disbursement）​

验证阶段分析并批准确认视频后触发。状态变更为 pending_withdrawal_disbursement（等待取款放款）。

Payload 示例
{
    "key": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "pending_withdrawal_disbursement",
    "webhook_type": "laas.payroll_card_reservation.status_change",
    "event_datetime": "2025-01-15T17:00:00Z",
    "data": {
        "credit_operation_key": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    }
}

E. 放款完成（Pending Card Issuance）​

取款完成时触发。状态变更为 pending_card_issuance（等待卡片发行），流程进入卡片发行阶段。

不返回任何附加信息。

Payload 示例
{
    "key": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "pending_card_issuance",
    "webhook_type": "laas.payroll_card_reservation.status_change",
    "event_datetime": "2025-01-15T17:00:00Z",
    "data": {
        "wallet_key": "9a7b7982-8bf7-4a2c-942c-588166811623"
    }
}

F. 卡片已发行（Card Issued）​

钱包和卡片创建完成时触发。

Payload 示例
{
    "key": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "card_issued",
    "webhook_type": "laas.payroll_card_reservation.status_change",
    "event_datetime": "2025-01-15T18:30:00Z",
    "data": {
        "card_key": "7c6b421e-7ae0-4419-b021-87bcc0be8748"
    }
}

G. 取消（Canceled）​

操作因某种原因被取消时触发（身份或信用验证被拒、Dataprev 保证金预约错误等）。

返回取消原因和详情。

Payload 示例
{
    "key": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "canceled",
    "webhook_type": "laas.payroll_card_reservation.status_change",
    "event_datetime": "2025-01-15T16:45:00Z",
    "data": {
        "cancel_reason": "not_eligible", 
        "cancel_details": "Age 15 is not within the eligible range (18-79 years)"
    }
}

2. 文件 Webhook（生成与验证）​

此 Webhook 通知操作中每个附件文件的单独状态变更。包括合同生成、签名收集阶段，以及附加文件（如确认视频）的验证阶段响应。

WEBHOOK TYPE
laas.payroll_card_reservation.attached_document.status_change

Webhook 通用结构​

字段类型描述
keystring文件密钥
statusstring文件的新状态（generated、pending_signature、approved、rejected）
webhook_typestringlaas.payroll_card_reservation.attached_document.status_change
event_datetimestring事件日期和时间
dataobject包含状态变更相关数据的对象

data 对象详情​

字段类型描述
payroll_card_reservation_keystring卡片预约密钥
document_keystring文件唯一密钥
document_typestring文件类型
document_urlstring查看文件的链接
signature_urlstring签名流程链接。仅当 status 为 pending_signature 时出现。
rejection_reasonstring拒绝原因。仅当 status 为 rejected 时出现。

场景​

A. 文件已生成（generated）​

操作合同成功生成并可查看时触发。

Payload 示例
{
    "key": "332017f4-a0d6-463a-8557-e925a9485251",
    "status": "generated",
    "webhook_type": "laas.payroll_card_reservation.attached_document.status_change",
    "event_datetime": "2025-01-15T14:30:00Z",
    "data": {
        "payroll_card_reservation_key": "910e8de5-16af-4bc5-8ee1-4a0652ca0cbf",
        "document_key": "332017f4-a0d6-463a-8557-e925a9485251",
        "document_type": "payroll_card_term",
        "document_url": "https://storage.googleapis.com/example_document.pdf",
        "signature_url": null
    }
}

B. 待签名（pending_signature）​

合同已生成并等待受益人签名时触发。返回 signature_url。

Payload 示例
{
    "key": "332017f4-a0d6-463a-8557-e925a9485251",
    "status": "pending_signature",
    "webhook_type": "laas.payroll_card_reservation.attached_document.status_change",
    "event_datetime": "2025-01-15T14:30:00Z",
    "data": {
        "payroll_card_reservation_key": "910e8de5-16af-4bc5-8ee1-4a0652ca0cbf",
        "document_key": "332017f4-a0d6-463a-8557-e925a9485251",
        "document_type": "payroll_card_term",
        "document_url": "https://storage.googleapis.com/example_document.pdf",
        "signature_url": "https://test.sign.qitech.com.br/s/SVomf6J"
    }
}

C. 附加文件已批准（approved）​

作为附加文件（如确认视频）验证的肯定响应触发，表示文件已由我们的团队或检查系统验证并接受。

Payload 示例
{
    "key": "2fc216c6-5d1c-4713-b70b-6e1f75f8bb17",
    "status": "approved",
    "webhook_type": "laas.payroll_card_reservation.attached_document.status_change",
    "event_datetime": "2025-01-15T16:45:00Z",
    "data": {
        "payroll_card_reservation_key": "910e8de5-16af-4bc5-8ee1-4a0652ca0cbf",
        "document_key": "2fc216c6-5d1c-4713-b70b-6e1f75f8bb17",
        "document_type": "payroll_card_confirmation_video",
        "document_url": "https://storage.googleapis.com/video.mp4",
        "signature_url": null
    }
}

D. 附加文件已拒绝（rejected）​

作为附加文件验证的否定响应触发。文件被拒绝，payload 将包含 rejection_reason 属性说明原因。

Payload 示例
{
    "key": "2fc216c6-5d1c-4713-b70b-6e1f75f8bb17",
    "status": "rejected",
    "webhook_type": "laas.payroll_card_reservation.attached_document.status_change",
    "event_datetime": "2025-01-15T16:50:00Z",
    "data": {
        "payroll_card_reservation_key": "910e8de5-16af-4bc5-8ee1-4a0652ca0cbf",
        "document_key": "2fc216c6-5d1c-4713-b70b-6e1f75f8bb17",
        "document_type": "payroll_card_confirmation_video",
        "document_url": "https://storage.googleapis.com/video_bad.mp4",
        "signature_url": null,
        "rejection_reason": "Áudio inaudível e rosto do cliente não visível"
    }
}

3. Dataprev 返回 Webhook（担保物）​

此 Webhook 通知 Dataprev 保证金预约进度。

主要用于**"Teimosinha"（持续重试）**场景，即临时故障（如保证金被占用或分期金额暂时超额）不会立即取消预约。在这些情况下，预约保持在批注队列中，直到配置的最后放款日期。

WEBHOOK TYPE
social_security.collateral

Webhook 通用结构​

字段类型描述
keystring卡片预约密钥（payroll_card_reservation_key）
webhook_typestring始终为 social_security.collateral
event_timestring事件日期和时间
dataobjectDataprev 返回的详细数据
data.collateral_constitutedboolean表示担保物是否成功构成（true 或 false）
data.collateral_data.statusstring预约状态（例如：pending_reservation）
data.collateral_data.last_responseobject包含 Dataprev 返回的错误列表（例如：installment_limit_excceded）
Payload 示例 - 临时故障
{
  "event_time": "2026-01-06 18:48:51",
  "key": "b670553f-28f4-4cf2-a3b5-e33c5ae86bb5",
  "webhook_type": "social_security.collateral",
  "data": {
    "collateral_data": {
      "last_response": {
        "errors": [
          {
            "enumerator": "installment_limit_excceded"
          }
        ]
      },
      "status": "pending_reservation",
      "last_response_event_datetime": "2026-01-06T18:48:51Z",
      "reservation_method": "social_security_payroll_card"
    },
    "collateral_type": "social_security_payroll_card",
    "collateral_constituted": false
  }
}

4. 信贷操作 Webhook（放款与 CCB 状态）​

此 Webhook 通知与预约关联的信贷操作（CCB）状态变更。在两个主要时刻触发：

  1. 成功（opened）： 资金已成功转入客户账户。
  2. 取消（canceled）： 放款时发生银行错误（如账户无效、持有人信息不符），操作被取消。
WEBHOOK TYPE
laas.credit_operation.status_change

Webhook 通用结构​

字段类型描述
keystring信贷操作密钥（credit_operation_key）
statusstring操作新状态：opened（成功）或 canceled（失败）
webhook_typestring始终为 laas.credit_operation.status_change
event_datetimestring事件日期和时间
dataobject包含成功详情或错误原因的可变对象

场景 A：放款成功（opened）​

状态为 opened 时，data 对象包含最终财务详情和交易凭证。

data 中的字段类型描述
installmentsarray含最终日期和金额的已确认分期列表
transaction_receiptsarray银行转账凭证列表
requester_identifier_keystring请求方唯一标识符
Payload 示例 - 成功
{
    "key": "550e8400-e29b-41d4-a716-446655440000",
    "status": "opened",
    "webhook_type": "laas.credit_operation.status_change",
    "event_datetime": "2025-10-14 13:26:52",
    "data": {
      "installments": [
        {
          "due_date": "2025-12-28",
          "total_amount": 315.02,
          "installment_key": "123e4567-e89b-12d3-a456-426614174000",
          "pre_fixed_amount": 212.35873015,
          "installment_number": 1,
          "principal_amortization_amount": 102.66126985
        }
      ],
      "disbursement_type": "pix",
      "transaction_receipts": [...],
      "requester_identifier_key": "req_id_key_uuid"
    }
}

场景 B：放款失败（canceled）​

状态为 canceled 时，data 对象包含银行拒绝原因（PIX 或 TED 退回）。

data 中的字段类型描述
cancel_reasonstring取消的宏观原因（例如：pix_refusal、ted_refusal）
cancel_reason_enumeratorstring原因枚举值（例如：pix_refusal）
pix_refusalobjectPIX 拒绝详情（可选）
ted_refusalobjectTED 拒绝详情（可选）
[refusal].reasonstring银行错误的描述性消息
[refusal].reason_enumeratorstring银行错误代码（例如：invalid_account）
Payload 示例 - 放款错误
{
    "key": "30e8917d-2b1f-4c79-baf5-cc18bb6e0277",
    "status": "canceled",
    "webhook_type": "laas.credit_operation.status_change",
    "event_datetime": "2026-01-06 20:57:04",
    "data": {
        "cancel_reason": "pix_refusal",
        "cancel_reason_enumerator": "pix_refusal",
        "pix_refusal": {
            "reason": "Número da conta de destino é inexistente ou inválido.",
            "reason_enumerator": "invalid_account",
            "cancel_reason_enumerator": "invalid_account"
        }
    }
}
重新提交

与预约关联的信贷操作取消并不一定意味着预约本身也被取消。在放款错误的情况下，预约保持开放状态，信贷操作仍可在卡片发送日期前重新提交。

更多详情，请参阅创建预约中的5. 取款付款重新提交。

5. 保险/福利保单创建 Webhook​

此 Webhook 通知与卡片关联的保险发行情况，并返回福利保单的 URL。 保险发行在卡片发行后异步进行，可能需要数小时才能确认。

WEBHOOK TYPE
laas.payroll_card_reservation.benefit.emission

Webhook 通用结构​

字段类型描述
keystring与预约关联的福利/保险密钥（benefit.benefit_key）
statusstringactive（保险激活）
webhook_typestring始终为 laas.payroll_card_reservation.benefit.emission
event_datetimestring事件日期和时间
dataobject包含保单详情的可变对象
data.policy_urlstring保险保单文件的 URL
Webhook 示例
{
    "key": "550e8400-e29b-41d4-a716-446655440000",
    "status": "opened",
    "webhook_type": "laas.payroll_card_reservation.benefit.emission",
    "event_datetime": "2025-10-14 13:26:52",
    "data": {
      "policy_url": "https://example.com/policy.pdf",
    }
}