跳到主要内容

资产 Webhook

在转让流程中，系统会发送 webhook，向集成合作伙伴通知单项资产的状态变更。webhook 有两种类型：用于状态变更的 trade_receivables.asset_status_change，以及用于确认资产创建的 trade_receivables.asset_creation。

Webhook 配置

如需接收 webhook，需要在 QI Tech 配置回调 URL。该配置决定您接收哪些状态：只发送已订阅的事件。创建 webhook（asset_creation）会发送给订阅了 pending_eligibility 状态的一方。请联系 integracao.dtvm@qitech.com.br 进行配置。投递、重试和签名：参见 Webhook 接收。

资产状态流程​

资产插入批次后立即进入 pending_eligibility，经过合格性审查后，沿以下路径之一继续。下图展示主路径；完整的状态列表参见资产状态枚举值。

资产状态流程，从 pending_eligibility 到 completed，以及转向 denied、registry_denied 和 discarded 的分支

图例：蓝色 = 中间状态 · 绿色 = 资产已转让并纳入投资组合 · 红色 = 拒绝或废弃的最终状态。

Webhook 结构​

所有资产 webhook 都采用相同的基础结构：

字段类型描述
webhook_typestringwebhook 类型：trade_receivables.asset_status_change 或 trade_receivables.asset_creation。
webhook_datetimestring发送的日期和时间，格式为 YYYY-MM-DDTHH:MM:SSZ。
dataobject事件数据。见下表。

data 属性​

字段类型描述
assignment_external_idstring资产所属批次的 external_id。
asset_external_idstring资产的 external_id。
asset_new_statusstring资产的新状态。
assignment_configuration_keystring批次所属转让配置的标识——与端点 URL 中使用的 key 相同。
fund_class_keystring与批次关联的基金类别标识。
operation_typestring转让配置的业务类型（例如：unsecured_credit、duplicata_mercantil）。
asset_payloadobject仅在创建 webhook（asset_creation）中返回。包含创建时发送的资产数据，并在 credit_operation（CCB）或 contract（合同）中附带计算出的 purchase_irr。
denial_reasonstring在 denied 和 registry_denied 中返回：拒绝的来源（denied_by 的取值）。
denial_metadataobject在 denied 和 registry_denied 中有详情时返回——例如未通过的合格性规则，或移除资产时提供的原因。
什么是 assignment_configuration_key

转让配置是转让方与基金之间已登记的协议：它规定应收账款转让给哪个基金、接受哪种资产类型，以及业务在何种规则下进行。它与您在转让端点 URL 中使用的 key 相同，可在转让方准入中获取。

由于同一转让方可能同时有多项有效配置，该字段表明资产是在哪一项协议下转让的。这样，您无需调用 API 查询资产来源，即可将 webhook 分发到正确的流程。

Webhook 标准结构
{
    "data": {
        "assignment_external_id": "ac597f90-a13e-4f78-86f0-11c66f5fa6d6",
        "asset_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b",
        "asset_new_status": "STATUS",
        "assignment_configuration_key": "3571e292-3a83-4011-904d-20ee963022ef",
        "fund_class_key": "b7d3e2a1-4c5f-4e8b-9d1a-2f3c4e5a6b7c",
        "operation_type": "unsecured_credit"
    },
    "webhook_type": "trade_receivables.asset_status_change",
    "webhook_datetime": "2024-04-23T15:08:30Z"
}

各状态的事件​

资产已创建​

STATUS
pending_eligibility

在资产成功插入批次时发送。该 webhook 包含 asset_payload 字段，其中含有创建时发送的全部信贷业务数据。webhook 类型为 trade_receivables.asset_creation。

Webhook Body
{
    "data": {
        "assignment_external_id": "ac597f90-a13e-4f78-86f0-11c66f5fa6d6",
        "asset_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b",
        "asset_new_status": "pending_eligibility",
        "assignment_configuration_key": "3571e292-3a83-4011-904d-20ee963022ef",
        "fund_class_key": "b7d3e2a1-4c5f-4e8b-9d1a-2f3c4e5a6b7c",
        "operation_type": "unsecured_credit",
        "asset_payload": {
            "premiums": [
                {
                    "total_value": 1.2,
                    "premium_type": "spread"
                }
            ],
            "asset_type": "ccb",
            "credit_operation": {
                "delay": {
                    "fine": {
                        "amount": 0.0,
                        "fine_type": "percentage"
                    },
                    "interest": {
                        "method": "compound",
                        "pre_fixed": {
                            "monthly_rate": 0.0,
                            "calendar_base": "workdays"
                        }
                    }
                },
                "borrower": {
                    "name": "João Pereira",
                    "email": "exemplo3@gmail.com",
                    "phone": {
                        "number": "948386674",
                        "area_code": "11"
                    },
                    "address": {
                        "uf": "SP",
                        "city": "São Paulo",
                        "number": "84",
                        "street": "RUA GILBERTO SABINO",
                        "country": "BRA",
                        "postal_code": "05425-020",
                        "neighborhood": "Pinheiros"
                    },
                    "person_type": "natural_person",
                    "natural_person": {
                        "birthdate": "1970-02-18",
                        "mother_name": "Natalia Nascimento"
                    },
                    "document_number": "969.698.790-03"
                },
                "contract": {
                    "cet": 0.0314,
                    "number": "0032226586/NNT",
                    "iof_value": 3.04,
                    "issue_date": "2024-04-24",
                    "issue_value": 93.05,
                    "signature_date": "2024-04-24",
                    "disbursement_date": "2024-04-24",
                    "disbursement_value": 62.1
                },
                "pre_fixed": {
                    "monthly_rate": 0.0179,
                    "calendar_base": "calendar_365"
                },
                "external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b",
                "installments": [
                    {
                        "face_value": 30.81,
                        "maturity_date": "2025-02-01",
                        "installment_number": 1
                    },
                    {
                        "face_value": 26.19,
                        "maturity_date": "2026-02-01",
                        "installment_number": 2
                    },
                    {
                        "face_value": 29.68,
                        "maturity_date": "2027-02-01",
                        "installment_number": 3
                    },
                    {
                        "face_value": 23.74,
                        "maturity_date": "2028-02-01",
                        "installment_number": 4
                    },
                    {
                        "face_value": 28.49,
                        "maturity_date": "2029-02-01",
                        "installment_number": 5
                    },
                    {
                        "face_value": 19.94,
                        "maturity_date": "2030-02-01",
                        "installment_number": 6
                    },
                    {
                        "face_value": 13.96,
                        "maturity_date": "2031-02-01",
                        "installment_number": 7
                    },
                    {
                        "face_value": 13.03,
                        "maturity_date": "2032-02-01",
                        "installment_number": 8
                    }
                ],
                "principal_value": 93.05,
                "amortization_type": "price",
                "interest_rate_type": "pre_fixed",
                "originator_document_number": "22.333.444/0001-81"
            },
            "total_purchase_value": 94.86
        }
    },
    "webhook_type": "trade_receivables.asset_creation",
    "webhook_datetime": "2024-04-23T15:08:30Z"
}

通过合格性审查——等待文件​

STATUS
pending_documentation

在资产通过合格性审查审批、且转让配置要求文件时发送（商业 duplicata 和 CT-e 始终会经过此状态）。如尚未提交，请通过插入文件提交所需文件。

Webhook Body
{
    "data": {
        "assignment_external_id": "ac597f90-a13e-4f78-86f0-11c66f5fa6d6",
        "asset_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b",
        "asset_new_status": "pending_documentation",
        "assignment_configuration_key": "3571e292-3a83-4011-904d-20ee963022ef",
        "fund_class_key": "b7d3e2a1-4c5f-4e8b-9d1a-2f3c4e5a6b7c",
        "operation_type": "unsecured_credit"
    },
    "webhook_type": "trade_receivables.asset_status_change",
    "webhook_datetime": "2024-04-23T15:08:30Z"
}

预审批通过​

STATUS
pre_approved

在文件校验成功后（或无需额外文件时），资产预审批通过时发送。资产可以进入正式化/登记环节。

Webhook Body
{
    "data": {
        "assignment_external_id": "ac597f90-a13e-4f78-86f0-11c66f5fa6d6",
        "asset_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b",
        "asset_new_status": "pre_approved",
        "assignment_configuration_key": "3571e292-3a83-4011-904d-20ee963022ef",
        "fund_class_key": "b7d3e2a1-4c5f-4e8b-9d1a-2f3c4e5a6b7c",
        "operation_type": "unsecured_credit"
    },
    "webhook_type": "trade_receivables.asset_status_change",
    "webhook_datetime": "2024-04-23T15:08:30Z"
}

等待登记​

STATUS
pending_registry

在预审批通过的资产被转交给登记机构时发送。仅发生在 registry_type 要求登记的转让配置中——internal_registry、external_registry、registry_transfer 或 unfit。资产会一直处于该状态，直至登记机构回复。

Webhook Body
{
    "data": {
        "assignment_external_id": "ac597f90-a13e-4f78-86f0-11c66f5fa6d6",
        "asset_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b",
        "asset_new_status": "pending_registry",
        "assignment_configuration_key": "3571e292-3a83-4011-904d-20ee963022ef",
        "fund_class_key": "b7d3e2a1-4c5f-4e8b-9d1a-2f3c4e5a6b7c",
        "operation_type": "unsecured_credit"
    },
    "webhook_type": "trade_receivables.asset_status_change",
    "webhook_datetime": "2024-04-23T15:08:30Z"
}

等待正式化​

STATUS
pending_formalization

资产已完成正式化（配置要求登记时已完成登记）、可在批次中继续直至纳入投资组合时所处的状态。目前此状态变更不会发送 webhook，即使已订阅该状态。请通过资产查询跟踪，或通过批次 webhook中的批次 waiting_assets_to_formalize webhook 跟踪。

资产已完成​

STATUS
completed

在资产成功纳入基金投资组合时发送。这是成功资产的最终状态——自此，该资产计入基金持仓。

Webhook Body
{
    "data": {
        "assignment_external_id": "ac597f90-a13e-4f78-86f0-11c66f5fa6d6",
        "asset_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b",
        "asset_new_status": "completed",
        "assignment_configuration_key": "3571e292-3a83-4011-904d-20ee963022ef",
        "fund_class_key": "b7d3e2a1-4c5f-4e8b-9d1a-2f3c4e5a6b7c",
        "operation_type": "unsecured_credit"
    },
    "webhook_type": "trade_receivables.asset_status_change",
    "webhook_datetime": "2024-04-23T15:08:30Z"
}

未通过合格性审查​

STATUS
denied

在资产被拒绝时发送——包括在合格性审查、文件校验或发票校验中被拒绝——或被从批次中移除时发送。webhook 包含 denial_reason，如有还包含 denial_metadata。因文件被拒绝的资产，在您提交新文件后会回到 pending_documentation。

Webhook Body
{
    "data": {
        "assignment_external_id": "ac597f90-a13e-4f78-86f0-11c66f5fa6d6",
        "asset_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b",
        "asset_new_status": "denied",
        "assignment_configuration_key": "3571e292-3a83-4011-904d-20ee963022ef",
        "fund_class_key": "b7d3e2a1-4c5f-4e8b-9d1a-2f3c4e5a6b7c",
        "operation_type": "unsecured_credit"
    },
    "webhook_type": "trade_receivables.asset_status_change",
    "webhook_datetime": "2024-04-23T15:08:30Z"
}

登记被拒绝​

STATUS
registry_denied

在登记机构拒绝资产登记时发送。该资产不会进入正式化，也不会纳入投资组合；批次审批通过时，其状态变为 denied。webhook 包含 denial_reason，如有还包含 denial_metadata；详情也会显示在资产查询中。

Webhook Body
{
    "data": {
        "assignment_external_id": "ac597f90-a13e-4f78-86f0-11c66f5fa6d6",
        "asset_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b",
        "asset_new_status": "registry_denied",
        "assignment_configuration_key": "3571e292-3a83-4011-904d-20ee963022ef",
        "fund_class_key": "b7d3e2a1-4c5f-4e8b-9d1a-2f3c4e5a6b7c",
        "operation_type": "unsecured_credit"
    },
    "webhook_type": "trade_receivables.asset_status_change",
    "webhook_datetime": "2024-04-23T15:08:30Z"
}

资产已废弃​

STATUS
discarded

资产随批次一起被废弃时所处的状态——例如在基金会计关账时。转让协议书签署后，批次中被拒绝（denied）的资产也会变为 discarded。目前此状态变更不会发送资产 webhook，即使已订阅该状态。请通过资产查询跟踪；批次的废弃由批次 webhook中的 discarded webhook 通知。如需从批次中移除资产，请使用移除资产，这会使资产变为 denied。