跳到主要内容

手册 - 私人薪资抵押贷款：雇佣关系

开发中的 API

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

1. 文档目的​

本手册介绍私人薪资抵押贷款中信贷借款人雇佣关系监控的运作方式，以及如何通过 webhook 通知更新。

2. 背景与动机​

私人薪资抵押贷款合同依赖于有效的雇佣关系来维持预留的有效性。 因此，Dataprev 每日被查询以识别这些关系的变化（如：劳动合同终止或新雇佣关系创建）。

当有变化时，系统会向合作伙伴发送自动 webhook，告知预留的新状态或检测到的新雇佣关系。

🔄 流程概述​

  1. 系统每日查询 Dataprev 中的雇佣关系。
  2. 若有效雇佣关系终止，合同将被更新并通知合作伙伴。
  3. 若工人建立新的雇佣关系，系统会自动识别并尝试重新关联预留。
  4. 在每个阶段都会发送 webhook，以便合作伙伴保持其系统更新。

3. Webhook - 雇佣关系终止​

📅 发送时机​

当工人失去雇佣关系且薪资抵押合同与该关系关联时。

🔍 发生的情况​

预留状态更新为 "terminated"，表示预留因雇佣关系终止而结束。 合作伙伴应相应更新其系统。

💡 Payload 示例​

{
    "status": "terminated",
    "event_datetime": "2025-03-20T14:47:43Z",
    "key": "<Debt Key>",
    "webhook_type": "laas.private_payroll.reservation_status_change",
    "data": {
            "reservation_key": "<Reservation Key>",
            "document_number": "12345678901",
            "reservation_status": "terminated",
            "requester_key": "123e4567-e89b-12d3-a456-426614174000",
            "registration_number": "99999999999-A",
            "employer_name": "VIPER SERVICOS DO NORDESTE LTDA",
            "admission_date": "2025-04-02",
            "employer_document_number": "12345678901234",
            "external_key": "123e4567-e89b-12d3-a456-426614174000",
            "contract_number": "2024001234",
            "inclusion_date": "2025-04-02",
            "disbursement_date": "2025-04-05",
            "reservation_type": "new_credit",
    }
}

4. Webhook - 新雇佣关系​

📅 发送时机​

当系统识别到持有有效合同的工人在之前终止后建立了新的雇佣关系。

🔍 发生的情况​

系统向合作伙伴发送新雇佣关系的完整数据通知。

💡 Payload 示例​

{
    "status": "active",
    "event_datetime": "2025-03-20T14:47:43Z",
    "key": "<Debt Key>",
    "webhook_type": "laas.private_payroll.new_employment_relationship",
    "data": {
        "document_number": "71742311016",
        "registration_number": "123456789ABCDEFR",
        "employer_document_number": "02302554000179",
        "status": "active",
        "employment_relationship_data": {
            "name": "LETYCIA AGUILAR DA SILVA",
            "eligible": true,
            "loan_count": 0,
            "employer_name": "VIPER SERVICOS DO NORDESTE LTDA",
            "admission_date": "2025-04-02",
            "total_due_amount": 1642.16,
            "base_margin_amount": 911.67,
            "political_exposition": "not_exposed",
            "worker_category_code": 101,
            "employer_document_type": "CNPJ",
            "available_margin_amount": 319.08
        }
    }
}

5. Webhook - 预留重新关联到新雇佣关系​

📅 发送时机​

系统检测到新的雇佣关系后，自动将已终止的预留重新关联时。

🔍 发生的情况​

仅当新保证金充足时才会重新关联。

分期付款不会重新计算，债务也不会重新配置。

生成新的预留键（reservation_key），保持相同的 credit_operation_key 或 external_key。

合作伙伴将收到两个 webhook，一个通知新预留状态为 "reserved"，另一个通知旧预留状态变为 "transferred"。这样可以追踪重新关联、已终止和已转移的合同。

💡 Payload 示例 - 重新关联的合同​

{
    "status": "reserved",
    "event_datetime": "2025-03-20T14:47:43Z",
    "key": "<Debt Key>",
    "webhook_type": "laas.private_payroll.renewed_reservation",
    "data": {
            "reservation_key": "<Reservation Key>",
            "document_number": "12345678901",
            "reservation_status": "reserved",
            "requester_key": "123e4567-e89b-12d3-a456-426614174000",
            "registration_number": "99999999999-A",
            "employer_name": "VIPER SERVICOS DO NORDESTE LTDA",
            "admission_date": "2025-04-02",
            "employer_document_number": "12345678901234",
            "external_key": "123e4567-e89b-12d3-a456-426614174000",
            "contract_number": "2024001234",
            "inclusion_date": "2025-04-02",
            "disbursement_date": "2025-04-05",
            "reservation_type": "transferred",
    }
}

💡 Payload 示例 - 已转移的合同​

{
    "status": "transferred",
    "event_datetime": "2025-03-20T14:47:43Z",
    "key": "<Debt Key>",
    "webhook_type": "laas.private_payroll.reservation_status_change",
    "data": {
            "reservation_key": "<Reservation Key>",
            "document_number": "12345678901",
            "requester_key": "123e4567-e89b-12d3-a456-426614174000",
            "registration_number": "99999999999-A",
            "employer_name": "VIPER SERVICOS DO NORDESTE LTDA",
            "admission_date": "2025-04-02",
            "employer_document_number": "12345678901234",
            "external_key": "123e4567-e89b-12d3-a456-426614174000",
            "contract_number": "2024001234",
            "inclusion_date": "2025-04-02",
            "disbursement_date": "2025-04-05",
            "reservation_type": "new_credit",
            "reservation_status": "transferred",
    }
}

注意：​

external_key 或 credit_operation_key 及大多数数据保持不变。

6. 最佳实践​

每日监控您的 webhook，以确保与 LaaS 系统同步。

以幂等方式处理状态更新（即避免对同一事件进行两次处理）。

保存 webhook 接收日志以供审计之用。