# QI Tech — Investment-as-a-Service › 投资组合构成 Documentação da QI Tech em texto corrido, para colar em um LLM. Fonte: https://docs.qitech.com.br 5 página(s). Índice: - 投资组合 - 审批 (/zh-Hans/documentation/iaas/composicao_carteira/aprovar_carteira) - 投资组合 - 下载投资组合 (/zh-Hans/documentation/iaas/composicao_carteira/baixar_carteira) - 简介 (/zh-Hans/documentation/iaas/composicao_carteira/inicio) - 投资组合 - 获取投资组合 (/zh-Hans/documentation/iaas/composicao_carteira/recuperar_carteira) - 投资组合 Webhook (/zh-Hans/documentation/iaas/composicao_carteira/webhooks) --- # 投资组合 - 审批 URL: /zh-Hans/documentation/iaas/composicao_carteira/aprovar_carteira 审批通过或拒绝验证投资组合。仅适用于状态为 `pending_confirmation` 的投资组合——投资组合准备好供您审核时即处于该状态，此时管理人会收到[状态变更 webhook](/documentation/iaas/composicao_carteira/webhooks)。 :::info 适用范围 | 角色 | 主机 | 所需权限 | | ------ | ------------- | -------- | | 管理人 | `manager-api` | 写入 | 各主机的 Base URL：[环境（主机）](/documentation/iaas/introducao/inicio#ambientes-hosts)。 ::: ## Request ENDPOINT /composition/fund_class/FUND_CLASS_KEY/composition/COMPOSITION_KEY MÉTODO PUT ```json title='Request Body — 审批通过' { "new_status": "confirmed" } ``` ```json title='Request Body — 拒绝' { "new_status": "reproved_by_agent", "reproved_reason": "Cota divergente do controle interno da gestora." } ``` | 字段 | 类型 | 必填 | 描述 | | ----------------- | ------ | ------------------------------------------ | ------------------------------------------ | | `new_status` | string | 是 | 投资组合的新状态。见下方枚举值。 | | `reproved_reason` | string | 是，当 `new_status` 为 `reproved_by_agent` 时 | 拒绝原因，1 到 255 个字符。 | ## "new_status" 枚举值 {#enumeradores-do-new_status} | 枚举值 | 描述 | | ------------------- | ------------------------------------------------------------ | | `confirmed` | 审批通过投资组合。 | | `reproved_by_agent` | 拒绝投资组合，并记录 `reproved_reason` 中填写的原因。 | | `reproved` | 拒绝投资组合，不要求填写原因。建议优先使用 `reproved_by_agent`。 | 拒绝原因会记录在投资组合的历史中：[投资组合查询](/documentation/iaas/composicao_carteira/recuperar_carteira#informacoes-da-carteira)的 `status_events` 字段会列出每次状态变更及其 `metadata`。 ## Response 成功时，API 返回 **204 No Content**，不带响应体。可查询投资组合以查看新状态。 ## 错误 {#erros} | 状态码 | 代码 | 触发条件 | | ------ | ----------- | -------------------------------------------------------------------------------- | | 404 | `CMP000013` | 投资组合不处于 `pending_confirmation`（已审批通过、已拒绝或仍在处理中）。 | | 404 | `CMP000010` | `new_status` 不是 `confirmed`、`reproved_by_agent` 或 `reproved`。 | | 404 | `CMP000025` | `new_status` 为 `reproved_by_agent`，但未发送 `reproved_reason`。 | | 404 | `CMP000012` | 所指定的基金类别下不存在该 `composition_key` 对应的投资组合。 | | 404 | `CMP000001` | 不存在该 `fund_class_key` 对应的基金类别。 | | 409 | `CMP000022` | 同一基金类别、同一日期、同一类型下已有另一份投资组合处于所请求的状态。 | | 400 | `QIT000001` | 请求体不符合接口契约：缺少 `new_status` 或其值不在可接受范围内，或包含未定义的字段。 | | 400 | `QIT000004` | 该 `fund_class_key` 属于其他管理人的基金类别。 | 认证、权限和主机相关错误：参见 [API 错误](/documentation/iaas/introducao/erros)。 --- # 投资组合 - 下载投资组合 URL: /zh-Hans/documentation/iaas/composicao_carteira/baixar_carteira ## 简介 {#introducao} 该接口以同步方式生成基金类别的报告，并以 base64 返回。 :::info 适用范围 | 角色 | 主机 | 所需权限 | | ------ | ---------------- | ----------------- | | 管理人 | `manager-api` | 读取 | | 顾问 | `consultant-api` | View Compositions | 各主机的 Base URL：[环境（主机）](/documentation/iaas/introducao/inicio#ambientes-hosts)。 ::: ### Request ENDPOINT /composition/fund_class/FUND_CLASS_KEY/report MÉTODO POST STATUS 201 ```json title='Request Body' { "report_type": "wallet_composition_by_composition", "composition_type": "final_quota", "reference_date": "2025-01-20" } ``` | 字段 | 类型 | 必填 | 描述 | | ------------------ | ------ | ---------------------------------------------------- | ------------------------------------------------------------------------------------- | | `report_type` | string | 是 | 要生成的报告。见下表。 | | `reference_date` | string | 是 | 参考日期，格式为 `YYYY-MM-DD`。 | | `composition_type` | string | 投资组合类报告需提供此字段或 `composition_key` 之一 | `pre_quota`、`final_quota` 或 `opening_quota`。使用 `reference_date` 当日该类型的投资组合。 | | `composition_key` | string | 投资组合类报告需提供此字段或 `composition_type` 之一 | 特定投资组合的 key。 | ### 可用报告 {#relatorios-disponiveis} | `report_type` | 内容 | 是否需要指定投资组合 | | --------------------------------------- | ------------------------------------------ | --------------------------- | | `wallet_composition_by_composition` | 投资组合电子表格（`.xlsx`） | 是 | | `wallet_composition_by_composition_pdf` | 投资组合 PDF | 是 | | `xml_401_by_composition` | 投资组合 XML 4.01——不接受 `pre_quota` | 是 | | `xml_5_by_composition` | 投资组合 XML 5.0——不接受 `pre_quota` | 是 | | `cash_account_demonstrative` | 现金账户明细 | 否（仅需 `reference_date`） | | `pmts_reconciliation` | PMT 对账 | 否（仅需 `reference_date`） | 接口契约接受的其他值（`wallet_composition_a_pagar`、`assets_wallet_composition_legacy`、`wallet_asset_installments_settlement_legacy`、`settlements_status_by_reference_date`、`discarded_settlements_on_payment_batch`）不由该端点生成，会返回 `CMP000027`。 ### Response ```json title='Response Body' { "document_b64": "UEsDBBQABgAIAAAAIQ..." } ``` `document_b64` 为以 base64 编码的报告文件。 :::caution 注意 对于投资组合类报告，投资组合必须处于 **`confirmed`**、**`pending_confirmation`** 或 **`reproved_by_agent`** 状态。处于其他状态时，返回 **400**（`CMP000015`）。 ::: ## 错误 {#erros} | 状态码 | 代码 | 触发条件 | | ------ | ----------- | ------------------------------------------------------------------------------------- | | 400 | `CMP000015` | 投资组合不处于 `confirmed`、`pending_confirmation` 或 `reproved_by_agent`。 | | 400 | `CMP000044` | 投资组合类报告既没有 `composition_key`，也没有 `composition_type`。 | | 400 | `CMP000027` | 该 `report_type` 不由此端点生成。 | | 404 | `CMP000026` | 对 `pre_quota` 投资组合请求了 `xml_401_by_composition` 或 `xml_5_by_composition`。 | | 404 | `CMP000012` | 不存在所指定 `composition_key` 的投资组合，或 `reference_date` 当日不存在该 `composition_type` 的投资组合。 | | 400 | `CMP000014` | 报告生成器拒绝了请求；`description` 中给出原因。 | | 400 | `QIT000001` | 请求体不符合接口契约：缺少必填字段、日期格式错误或包含未定义的字段。 | | 400 | `QIT000004` | 该 `fund_class_key` 属于其他管理人的基金类别。 | 认证、权限和主机相关错误：参见 [API 错误](/documentation/iaas/introducao/erros)。 --- # 简介 URL: /zh-Hans/documentation/iaas/composicao_carteira/inicio 本节介绍如何通过 API 获取投资组合。QI DTVM 所管理的全部投资基金的投资组合每天都会通过该 API 提供，其中包含构成当日份额的各项信息。 在基金日终处理（即提供其投资组合）的过程中，我们会先生成第一份投资组合，称为**验证投资组合**（`composition_type` = `pre_quota`）；该投资组合审批通过后，再提供**最终投资组合**（`composition_type` = `final_quota`）。 两份投资组合的主要区别在于：验证投资组合在负债端处理（包括摊销、申购和赎回）之前生成，而最终投资组合已反映这些变动。资产、费用、对账和现金信息在两份投资组合中始终完全相同。实际上，变化在于待确认份额的赎回所对应的"应付"项，或待确认份额的金融申购所对应的"应收"项，会完成份额确认并影响各发行系列的份额数量，但不会改变已公布的份额净值。 :::caution 所有审核或校验都务必在**验证投资组合**审批通过之前完成，因为一旦审批通过，系统就会进入负债端处理，进而提供最终投资组合。到这一阶段，由于负债端已处理完毕，相关的赎回和摊销甚至可能已经完成清算。 ::: 当投资组合准备好供您审核时，其状态变为 `pending_confirmation`，管理人会收到[状态变更 webhook](/documentation/iaas/composicao_carteira/webhooks)。审批通过或拒绝通过[投资组合审批](/documentation/iaas/composicao_carteira/aprovar_carteira)完成。 如需使用这些服务，请联系 [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br) 团队，以便在 Sandbox 和生产环境中开通相应权限。 --- # 投资组合 - 获取投资组合 URL: /zh-Hans/documentation/iaas/composicao_carteira/recuperar_carteira --- ## 投资组合列表 {#lista-de-carteiras} 分页列出某一基金类别的投资组合，按日期从新到旧排列。 :::info 适用范围 | 角色 | 主机 | 所需权限 | | ------ | ---------------- | ----------------- | | 管理人 | `manager-api` | 读取 | | 顾问 | `consultant-api` | View Compositions | 各主机的 Base URL：[环境（主机）](/documentation/iaas/introducao/inicio#ambientes-hosts)。 ::: ### Request ENDPOINT /composition/fund_class/FUND_CLASS_KEY/compositions MÉTODO GET ### Query Params | 参数 | 描述 | |------------------|-----------------------------------------------------------------------------------------------------| | `not_status` | 排除处于所指定状态的投资组合。 | | `status` | 仅返回处于所指定状态的投资组合。 | | `reference_date` | 查询投资组合的参考日期，格式必须为 `YYYY-MM-DD`。 | | `type` | 投资组合类型：`pre_quota`、`final_quota` 或 `opening_quota`。 | | `start_date` | 查询区间的起始日期。如提供了 `end_date` 则必填。格式：`YYYY-MM-DD`。 | | `end_date` | 查询区间的结束日期。如提供了 `start_date` 则必填。格式：`YYYY-MM-DD`。 | | `page` | 要获取的页码，从 `0` 开始。默认：`0`。 | | `limit` | 每页条目数。默认：`20`；最大：`100`。 | `status` 和 `not_status` 可接受多个值（`?status=pending_confirmation&status=confirmed`）。投资组合可能的状态有 `created`、`pending_processing`、`pending_validation`、`pending_variation_reason`、`pending_quota_performance`、`pending_confirmation`、`confirmed`、`reproved`、`reproved_by_agent` 和 `reprocessed`。等待您审批的投资组合处于 `pending_confirmation`。 :::caution 注意 按日期筛选有两种方式： - **指定日期**：发送 query param `reference_date`。 - **时间段**：同时发送 query param `start_date` 和 `end_date`。 ::: ```json title='Response Body' { "data": [ { "composition_key": "f2208257-1489-4937-8862-031bca34016f", "status": "confirmed", "composition_type": "pre_quota", "composition_date": "2024-11-13", "fund_class": { "name": "A SAMPLE CLASS", "fund_class_key": "5dac941c-c779-4049-a4ee-7cee583b6860", "document_number": "11.222.333/0001-81" } }, { "composition_key": "f2208257-1489-4937-8862-031bca34016f", "status": "confirmed", "composition_type": "final_quota", "composition_date": "2024-11-13", "fund_class": { "name": "A SAMPLE CLASS", "fund_class_key": "5dac941c-c779-4049-a4ee-7cee583b6860", "document_number": "11.222.333/0001-81" } } ], "limit": 20, "page": 0, "is_last_page": true } ``` ### 分页对象 {#objeto-paginado} | 字段 | 类型 | 描述 | |---------------|--------|----------------------------------------------------------------| | `data` | array | **[Composition](#composition)** 对象列表 | | `limit` | int | 每页获取的对象数量上限 | | `page` | int | 所获取的页码 | | `is_last_page`| boolean| 指示所获取的页是否为最后一页 | ### Composition | 字段 | 类型 | 描述 | |--------------------------|--------|-------------------------------------------------| | `composition_key` | string | 投资组合的唯一标识 key | | `status` | string | 该投资组合的状态 | | `composition_type` | string | 该投资组合的类型，pre_quota/final_quota | | `composition_date` | string | 投资组合的参考日期 | | `fund_class` | object | **[Fund Class](#fund_class)** 对象 | ### Fund Class {#fund_class} | 字段 | 类型 | 描述 | 字符数 | |-------------------------------|----------|---------------------------------------------------|------------| | `name` | string | 基金类别名称 | 最多 255 | | `fund_class_key` | string | 基金类别的唯一标识 key | 36 | | `document_number` | string | 基金类别的 CNPJ | - | --- ## 投资组合详情 {#informacoes-da-carteira} 返回完整的投资组合：发行系列、资产、应收、应付、账户以及状态历史。 :::info 适用范围 | 角色 | 主机 | 所需权限 | | ------ | ---------------- | ----------------- | | 管理人 | `manager-api` | 读取 | | 顾问 | `consultant-api` | View Compositions | 各主机的 Base URL：[环境（主机）](/documentation/iaas/introducao/inicio#ambientes-hosts)。 ::: ### Request ENDPOINT /composition/fund_class/FUND_CLASS_KEY/composition/COMPOSITION_KEY MÉTODO GET ```json title='Response Body' { "composition_key": "f2208257-1489-4937-8862-031bca34016f", "status": "confirmed", "composition_type": "pre_quota", "composition_date": "2024-12-02", "fund_class": { "name": "A SAMPLE CLASS", "fund_class_key": "5dac941c-c779-4049-a4ee-7cee583b6860", "document_number": "11.222.333/0001-81" }, "issuance_series": [ { "issuance_serie_key": "840e01e9-0df8-4719-83c4-f10b839d8384", "name": "SUBORDINADA - 1", "gross_net_worth": 1891397.29, "net_net_worth": 1891397.29, "gross_quota_value": 1.76821576, "net_quota_value": 1.76821576, "number_of_quotas": 1069664.309518427, "applied_value": 0.0, "applied_quotas": 0.0, "redeemed_value": 0.0, "redeemed_quotas": 0.0, "amortized_value": 0.0, "tax_anticipated_value": 0.0, "tax_anticipated_quotas": 0.0, "profitabilities": [ { "reference_date": "2024-11-29", "quota_value": 1.76065188, "di_benchmark_quota_value": 1.7613906, "quota_percentage": 100.43, "di_benchmark_percentage": 100.43, "type": "monthly" }, { "reference_date": "2024-11-25", "quota_value": 1.7568068, "di_benchmark_quota_value": 1.76049545, "quota_percentage": 99.79, "di_benchmark_percentage": 100.0, "type": "monthly" }, { "reference_date": "2024-11-01", "quota_value": 1.74121452, "di_benchmark_quota_value": 1.75502225, "quota_percentage": 99.21, "di_benchmark_percentage": 100.0, "type": "monthly" }, { "reference_date": "2024-10-03", "quota_value": 1.72167143, "di_benchmark_quota_value": 1.75002091, "quota_percentage": 98.38, "di_benchmark_percentage": 100.0, "type": "monthly" }, { "reference_date": "2024-09-03", "quota_value": 1.70128747, "di_benchmark_quota_value": 1.74445962, "quota_percentage": 97.52, "di_benchmark_percentage": 100.0, "type": "monthly" }, { "reference_date": "2024-06-05", "quota_value": 1.63380383, "di_benchmark_quota_value": 1.7178922, "quota_percentage": 95.1, "di_benchmark_percentage": 100.0, "type": "monthly" }, { "reference_date": "2023-12-08", "quota_value": 1.52421994, "di_benchmark_quota_value": 1.68553599, "quota_percentage": 90.43, "di_benchmark_percentage": 100.0, "type": "daily" } ] } ], "assets": [ { "asset_key": "34f42521-f27f-424a-958f-8b53f15cc80d", "asset_type": "fixed_income_fund_quota", "purchase_date": "2024-11-27", "total_purchase_value": 1009320, "bad_debt_percentage": 0, "bad_debt_value": 0, "overdue_accounting_value": 0, "current_accounting_value": 1234335, "current_fair_accounting_value": 1234335 } ], "consolidated_assets": [ { "asset_type": "ccb", "asset_category": "credit", "total_units": 175623, "bad_debt_value": 0, "overdue_accounting_value": 75642, "current_accounting_value": 187762590, "current_fair_accounting_value": 187762590, "post_maturity_interest_value": 0, "delay_interest_value": 0, "delay_fine_value": 0 } ], "receivables": [ { "origin_key": "a60f9226-edac-488e-9a58-6205a334e6ba", "origin_type": "expense", "description": "Taxa CVM - 2024", "total_value": 711515, "recognized_value": 654125, "start_date": "2024-01-09", "end_date": "2024-12-31", "payment_date": "2024-05-10" } ], "payables": [ { "origin_key": "19b83b17-d36c-4edd-97fe-99af6a0a4a63", "origin_type": "expense", "description": "Taxa de Gestão - 2024/12", "total_value": 14586, "recognized_value": 14586, "start_date": "2024-12-02", "end_date": "2024-12-31", "payment_date": "2025-01-08" } ], "cash_accounts": [ { "account_key": "a41e4fa8-6950-485e-9a5b-70f21cc6774a", "balance": 100000, "unconcilied_cash_in": 0, "unconcilied_cash_out": 0, "account_branch": "0001", "account_digit": "1", "account_number": "372832", "accounting_identification": 1, "financial_institution": { "code": "329", "ispb": "32402502", "name": "QI Sociedade de Crédito Direto" } } ] } ``` ### 完整 Composition {#composition-completo} | 字段 | 类型 | 描述 | |--------------------------|--------|-------------------------------------------------------------| | `composition_key` | string | 投资组合的唯一标识 key | | `status` | string | 该投资组合的状态 | | `composition_type` | string | 该投资组合的类型，pre_quota/final_quota | | `composition_date` | string | 投资组合的参考日期 | | `fund_class` | object | **[Fund Class](#fund_class)** 对象 | | `issuance_series` | array | **[Issuance Series](#issuance_serie)** 对象列表 | | `assets` | array | **[Assets](#assets)** 对象列表 | | `consolidated_assets` | array | **[Consolidated Assets](#consolidated-assets)** 对象列表 | | `receivables` | array | **[Receivables](#receivables)** 对象列表 | | `payables` | array | **[Payables](#payables)** 对象列表 | | `cash_accounts` | array | **[Cash Accounts](#cash-accounts)** 对象列表 | | `status_events` | array | 投资组合的状态历史。见 **[Status Events](#status-events)** | ### Issuance Serie {#issuance_serie} | 字段 | 类型 | 描述 | |---------------------------|--------|-------------------------------------------------------------| | `issuance_serie_key` | string | 发行系列的唯一标识 key | | `name` | string | 该系列的名称 | | `gross_net_worth` | float | 该系列的总净资产（PL Bruto） | | `net_net_worth` | float | 该系列的净资产净额（PL Líquido） | | `gross_quota_value` | float | 份额总值 | | `net_quota_value` | float | 份额净值 | | `number_of_quotas` | float | 份额总数 | | `applied_value` | float | 期间内申购总金额（可选） | | `applied_quotas` | float | 期间内申购份额数量（可选） | | `redeemed_value` | float | 期间内赎回总金额（可选） | | `redeemed_quotas` | float | 期间内赎回份额数量（可选） | | `amortized_value` | float | 期间内摊销总金额（可选） | | `tax_anticipated_value` | float | 预缴税款金额（可选） | | `tax_anticipated_quotas` | float | 预缴税款对应的份额数量（可选） | | `isin_code` | string | 该系列的 ISIN 代码（可选） | | `profitabilities` | array | **[Profitability](#profitability)** 对象列表 | ### Profitability | 字段 | 类型 | 描述 | |------------------------------|--------|----------------------------------------------------------------------| | `reference_date` | string | 分析业绩所依据的参考日期 | | `quota_value` | float | 该系列在参考日期的份额净值 | | `di_benchmark_quota_value` | float | 假设参考份额按 100% DI 增长，其当前的份额净值 | | `quota_percentage` | float | 期间内份额的累计收益率（%） | | `di_benchmark_percentage` | float | 期间内 DI 基准的累计收益率（%） | | `type` | string | 收益率的期间类型 | ### Assets | 字段 | 类型 | 描述 | |---------------------------------|---------|-------------------------------------------------------| | `asset_key` | string | 资产的唯一标识 key | | `asset_type` | string | 资产类型 | | `purchase_date` | string | 资产的购入日期 | | `total_purchase_value` | string | 资产的购入总额 | | `bad_debt_percentage` | string | 计提的坏账准备（PDD）比例 % | | `bad_debt_value` | integer | 计提的坏账准备（PDD）总额——以分为单位的整数 | | `overdue_accounting_value` | integer | 资产的逾期金额——以分为单位的整数 | | `current_accounting_value` | integer | 资产总值——以分为单位的整数 | | `current_fair_accounting_value` | integer | 资产总值——以分为单位的整数 | ### Consolidated Assets | 字段 | 类型 | 描述 | |---------------------------------|---------|----------------------------------------------------------------------| | `asset_type` | string | 资产类型 | | `asset_category` | string | 资产类别 | | `total_units` | integer | 该类型下汇总的资产总数 | | `bad_debt_value` | integer | 计提的坏账准备（PDD）总额——以分为单位的整数 | | `overdue_accounting_value` | integer | 资产的逾期金额——以分为单位的整数 | | `current_accounting_value` | integer | 资产总值——以分为单位的整数 | | `current_fair_accounting_value` | integer | 资产公允总值——以分为单位的整数 | | `post_maturity_interest_value` | integer | 到期后利息——以分为单位的整数 | | `delay_interest_value` | integer | 逾期利息——以分为单位的整数 | | `delay_fine_value` | integer | 逾期罚金——以分为单位的整数 | ### Receivables | 字段 | 类型 | 描述 | |-----------------------------|--------|----------------------------------------------------------------------| | `origin_key` | string | 产生该应收项的资源的唯一标识 key | | `origin_type` | string | 产生该应收项的资源类型 | | `description` | string | 条目描述 | | `total_value` | float | 应收总额 | | `recognized_value` | float | 已确认（计提）的金额 | | `start_date` | string | 开始确认的日期 | | `end_date` | string | 结束确认的日期 | | `payment_date` | string | 清算日期 | ### Payables | 字段 | 类型 | 描述 | |-----------------------------|--------|----------------------------------------------------------------------| | `origin_key` | string | 产生该应付项的资源的唯一标识 key | | `origin_type` | string | 产生该应付项的资源类型 | | `description` | string | 条目描述 | | `total_value` | float | 应付总额 | | `recognized_value` | float | 已确认（计提）的金额 | | `start_date` | string | 开始确认的日期 | | `end_date` | string | 结束确认的日期 | | `payment_date` | string | 清算日期 | ### Cash Accounts | 字段 | 类型 | 描述 | |-----------------------------|---------|-------------------------------------------------------------------| | `account_key` | string | 账户的唯一标识 key | | `balance` | integer | 账户余额——以分为单位的整数 | | `unconcilied_cash_in` | integer | 该账户待对账的入账金额——以分为单位的整数 | | `unconcilied_cash_out` | integer | 该账户待对账的出账金额——以分为单位的整数 | | `account_branch` | string | 账户所属分行 | | `account_digit` | string | 账户校验位 | | `account_number` | string | 账号 | | `accounting_identification` | integer | 该账户的会计标识 | | `financial_institution` | object | **[Financial Institution](#financial_institution)** 对象 | | `account_data` | object | 包含账户数据的对象（字段与上述相同） | ### Financial Institution {#financial_institution} | 字段 | 类型 | 描述 | |-----------------------------|--------|-----------------------| | `code` | string | 金融机构的 COMPE 代码 | | `ispb` | string | 金融机构的 ISPB | | `name` | string | 金融机构名称 | ### Status Events | 字段 | 类型 | 描述 | |------------------|--------|--------------------------------------------------------------------------------------| | `status` | string | 投资组合所处的状态 | | `event_datetime` | string | 状态变更的日期和时间 | | `metadata` | object | 变更相关数据（如有）。管理人拒绝时，包含其填写的 `reproved_reason` | ## 错误 {#erros} | 状态码 | 代码 | 触发条件 | | ------ | ----------- | ---------------------------------------------------------------- | | 400 | `CMP000016` | 列表查询只提供了 `start_date` 和 `end_date` 中的一个。 | | 400 | `CMP000017` | 列表查询中 `end_date` 早于 `start_date`。 | | 400 | `QIT000004` | 该 `fund_class_key` 属于其他管理人的基金类别。 | | 400 | `QIT000010` | 查询参数无效：`limit` 大于 100、`page` 为负数或 `reference_date` 不符合 `YYYY-MM-DD` 格式。 | | 404 | `CMP000001` | 不存在该 `fund_class_key` 对应的基金类别。 | | 404 | `CMP000012` | 查询的 `composition_key` 在所指定的基金类别中不存在。 | 认证、权限和主机相关错误：参见 [API 错误](/documentation/iaas/introducao/erros)。 --- # 投资组合 Webhook URL: /zh-Hans/documentation/iaas/composicao_carteira/webhooks 投资组合在变更为某些状态时会发送 `composition.status_change` webhook。该 webhook **仅发送给**基金类别的**管理人**。 签名、请求头和重发策略与所有 webhook 相同：参见 [Webhook 认证](/documentation/iaas/introducao/autenticacao_webhooks)。 ## 发送时机 {#quando-e-enviado} | `status` | 时机 | 处理方式 | | ---------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------ | | `pending_confirmation` | 投资组合已准备就绪，等待管理人审批。 | 审核投资组合，并[审批通过或拒绝](/documentation/iaas/composicao_carteira/aprovar_carteira)。 | | `confirmed` | 投资组合已确认：验证投资组合在管理人审批通过时确认（如该基金类别启用了自动审批，则自动确认）；最终投资组合在处理结束时确认。 | 查询或[下载](/documentation/iaas/composicao_carteira/baixar_carteira)投资组合。 | | `reprocessed` | 一份已确认的投资组合被 QI DTVM 重新处理。 | 原已确认的投资组合不再有效。请列出同一日期的投资组合以获取当前有效版本。 | 拒绝（`reproved`、`reproved_by_agent`）以及处理过程中的中间状态不会发送 webhook。 ## Payload ```json title='Webhook Body' { "webhook_type": "composition.status_change", "webhook_datetime": "2025-01-22T20:30:23.459123+00:00", "data": { "composition_key": "f2208257-1489-4937-8862-031bca34016f", "composition_date": "2025-01-21", "composition_type": "pre_quota", "status": "pending_confirmation", "fund_class_key": "5dac941c-c779-4049-a4ee-7cee583b6860" } } ``` | 字段 | 类型 | 描述 | | ----------------------- | ------ | -------------------------------------------------------- | | `webhook_type` | string | 始终为 `composition.status_change`。 | | `webhook_datetime` | string | 发送的日期和时间，UTC（ISO 8601）。 | | `data.composition_key` | string | 投资组合的 key。可用它查询完整的投资组合。 | | `data.composition_date` | string | 投资组合的参考日期（`YYYY-MM-DD`）。 | | `data.composition_type` | string | `pre_quota`、`final_quota` 或 `opening_quota`。 | | `data.status` | string | 投资组合的新状态。 | | `data.fund_class_key` | string | 基金类别的 key。 | ## 配置 {#configuracao} webhook 的 URL 以及会触发通知的投资组合类型（例如仅 `pre_quota`）由 QI DTVM 配置——您的集成中没有用于此项配置的端点。请联系集成团队：[integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br)。