跳到主要内容

批次资产查询

用于查询转让批次中已插入资产的端点。有两种查询方式：批次中所有资产的分页列表，以及特定资产的单项查询。

适用场景

可使用这些端点在插入后跟踪资产状态，确认哪些资产在合格性审查中审批通过或被拒绝，并在有拒绝时查看原因。

列表支持筛选条件——包括按状态筛选——因此可以直接只查询被拒绝的资产，而无需对整个批次分页。参见仅查询被拒绝的资产。

资产列表​

返回批次中资产的分页列表，支持筛选。响应只包含您的角色有权查看的资产。

适用范围
角色主机所需权限
管理人manager-api读取
顾问consultant-apiView Assignments

各主机的 Base URL：环境（主机）。

Request​

ENDPOINT
/trade_receivables/fund_class/{fund_class_key}/assignment/{assignment_external_id}/assets
MÉTODO
GET

Query params​

所有筛选条件均为可选，且可以相互组合。未提供任何筛选条件时，路由返回批次中的所有资产。

参数类型默认描述
pageinteger0页码（从 0 开始）。
limitinteger10每页记录数。最大：100。
statusstring—按资产状态筛选。只接受一个值，且必须为状态枚举值之一。使用 denied 只获取被拒绝的资产。
external_idstring—按创建时提供的资产 external_id 筛选。
contract_numberstring—按业务的合同编号筛选。
invoice_access_keystring—按发票访问码筛选（duplicata 和 CT-e）。
invoice_numberstring—按发票号码筛选。
invoice_seriestring—按发票系列号筛选。
borrower_document_numberstring—按债务人（根据资产类型为付款人或借款人）的 CPF/CNPJ 筛选。
purchase_value_minnumber—资产的最低购买价值（含）。
purchase_value_maxnumber—资产的最高购买价值（含）。
maturity_date_startstring (AAAA-MM-DD)—到期日区间的起始日期。
maturity_date_endstring (AAAA-MM-DD)—到期日区间的结束日期。
示例——简单列表
GET /trade_receivables/fund_class/{fund_class_key}/assignment/{assignment_external_id}/assets?page=0&limit=10
示例——组合筛选
GET /trade_receivables/fund_class/{fund_class_key}/assignment/{assignment_external_id}/assets?status=denied&limit=100&maturity_date_start=2024-01-01&maturity_date_end=2024-12-31
无效状态

如果 status 中发送的值不对应任何有效的枚举值，请求返回 TRC000163（400）。构造筛选条件前，请参阅枚举值表。

Response​

STATUS
200
Response Body
{
    "data": [
        {
            "asset_key": "f4348106-01c4-4c59-a261-7c09db811c47",
            "external_id": "e292656f-f7fb-44dc-96f3-667c36c88442",
            "total_purchase_value": 1231.21,
            "asset_type": "duplicata_mercantil",
            "status": "denied",
            "duration": 9177,
            "denied_by": "document",
            "denial_reason": "Invalid documents"
        }
    ],
    "limit": 10,
    "page": 0,
    "is_last_page": true
}

响应属性​

字段类型描述
dataarray资产对象列表。见下表。
pageinteger当前页码。
limitinteger每页记录数。
is_last_pageboolean指示是否为结果的最后一页。

每项资产的属性（data 中的对象）​

字段类型描述
asset_keystring资产的唯一标识（UUID）。
external_idstring合作伙伴在创建时提供的外部 key。
total_purchase_valuenumber资产的购买总额。
asset_typestring资产类型（例如：ccb、duplicata_mercantil、discounted_contract）。
ipoc_codestring资产的 IPOC 代码（如有）。
purchase_irrnumber资产的购买利率（已计算时）。
contract_numberstring合同编号（如有）。
premiumsarray资产的溢价（premium_type、total_value）。没有时不返回。
deductionsarray资产的折价（deduction_type、total_value）。没有时不返回。
statusstring资产当前状态。参见下方的状态表。
durationinteger资产的期限（天数）。尚未计算时可能不返回。
denied_bystring拒绝的来源。仅当资产被拒绝时返回。参见来源表。
denial_reasonstring拒绝原因的描述。仅当有拒绝详情时返回。
denial_translationstring原因的翻译（如有）。
denial_descriptionstring原因的补充描述（如有）。
嵌套对象

根据资产类型，响应包含 credit_operation（CCB）、discounted_credit_right（duplicata、CT-e、贴现合同）或 contract（分期合同）对象，其中包含创建时发送的数据以及 originator 对象。

仅查询被拒绝的资产​

这是列表最常见的用法：找出批次中哪些合同被拒绝，以便在合作伙伴的内部系统中同步 QI Tech 的决定，并决定是否需要从批次中移除某些资产。

只需提供 status=denied：

Request
GET /trade_receivables/fund_class/{fund_class_key}/assignment/{assignment_external_id}/assets?status=denied&limit=100

响应只包含被拒绝的资产，每项资产都带有 denied_by（拒绝来源）和 denial_reason（描述）：

Response Body
{
    "data": [
        {
            "asset_key": "f4348106-01c4-4c59-a261-7c09db811c47",
            "external_id": "e292656f-f7fb-44dc-96f3-667c36c88442",
            "total_purchase_value": 1231.21,
            "asset_type": "ccb",
            "status": "denied",
            "duration": 9177,
            "denied_by": "eligibility",
            "denial_reason": "Prazo do contrato acima do permitido pela política do fundo"
        }
    ],
    "limit": 100,
    "page": 0,
    "is_last_page": true
}
使用建议
  • 使用 limit=100（允许的最大值）以减少页数，并持续分页直到 is_last_page 为 true。
  • 在收到 pending_manager_approval webhook 后查询——此时所有资产的合格性审查均已完成，被拒绝资产的列表已稳定。
  • 如需相反的结果——即通过合格性审查的资产——请使用 status=pre_approved。

拒绝来源（denied_by）​

值含义
eligibility在合格性审查中被拒绝。
document在所提交文件的校验中被拒绝。
inconsistency因校验中发现的业务数据不一致而被拒绝。
invalid_invoice在发票校验中被拒绝。
registry在资产登记过程中被拒绝。
term在转让协议书环节被拒绝。
manager由基金管理人操作拒绝/移除。
consultant由顾问操作拒绝/移除。
assignor由转让方操作拒绝/移除。
accounting_close因基金会计关账而被拒绝。
denial_file因批量处理的拒绝文件而被拒绝。

查询特定资产​

返回批次中特定资产的完整数据，包括状态历史和已提交的文件。

适用范围
角色主机所需权限
管理人manager-api读取
顾问consultant-apiView Assignments
转让方assignor-api读取

各主机的 Base URL：环境（主机）。

Request​

ENDPOINT
/trade_receivables/fund_class/{fund_class_key}/assignment_configuration/{assignment_configuration_key}/assignment/{assignment_external_id}/asset/{asset_external_id}
MÉTODO
GET

Path params​

参数类型描述
asset_external_idstring创建资产时提供的 external_id。

Response​

STATUS
200
Response Body
{
    "asset_key": "074f8786-447f-4524-9f4f-a5cf8a890bb4",
    "external_id": "acfbc329-4e67-40ea-bd8d-5debdaebe144",
    "total_purchase_value": 1231.21,
    "asset_type": "duplicata_mercantil",
    "status": "denied",
    "duration": 9184,
    "denied_by": "document",
    "denial_reason": "Invalid documents"
}

响应属性​

响应的结构与资产列表返回的 data 数组中的每个对象相同，另外包含：

字段类型描述
status_eventsarray资产的状态历史：status、event_datetime（UTC），以及拒绝时的 denial_reason 和 denial_metadata。
documentsarray为该资产提交的文件。

资产状态枚举值​

以下任一值均可用于列表的 status 筛选条件。

状态描述
created资产已创建，尚未提交审查。
pending_eligibility资产已插入，等待合格性审查。
pending_documentation资产已通过合格性审查，等待提交文件。
pending_invoice_validation等待发票校验。
pre_approved资产已通过单项合格性审查（预审批）。
pending_registry等待开始资产登记。
pending_external_registry等待在外部登记机构登记。
sending_to_registry正在发送至登记机构。
waiting_registry登记已提交，等待登记机构回执。
pending_formalization资产已正式化，可在批次中继续。
registry_denied资产登记被登记机构拒绝。
sending_to_wallet正在纳入基金投资组合。
denied资产被拒绝。拒绝来源见 denied_by。
discarded资产已从批次中废弃。
pending_after_assignment_documentation资产已纳入投资组合，等待转让后文件。
pending_deferred_registry等待转让后登记（延迟登记）。
completed资产已纳入基金投资组合。

错误​

状态码代码触发条件
400TRC000163列表：status 的值不是资产状态。
400—列表：limit 超过 100 或 page 为负数（参数校验）。
404TRC000020单项查询：批次中没有使用该 asset_external_id 的资产。

认证、权限和主机相关错误：参见 API 错误。