# 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 3 página(s). Índice: - 公共债券交易单 (/zh-Hans/documentation/iaas/boletador/boletador_titulos_publicos) - 公共债券查询 (/zh-Hans/documentation/iaas/boletador/consulta_titulo_publico) - 公共债券列表 (/zh-Hans/documentation/iaas/boletador/listagem_titulos_publicos) --- # 公共债券交易单 URL: /zh-Hans/documentation/iaas/boletador/boletador_titulos_publicos 为基金登记联邦公共债券（LFT、LTN、NTN-B、NTN-F）的买断式买入或卖出交易单，或回购式买入交易单。交易单在管理人审批后登记到 SELIC。 :::info 适用范围 | 角色 | 主机 | 所需权限 | | ------ | ------------- | -------- | | 管理人 | `manager-api` | 写入 | 各主机的 Base URL：[环境（主机）](/documentation/iaas/introducao/inicio#ambientes-hosts)。 ::: :::caution 审批在门户中完成 所有交易单创建后均处于 `pending_manager_approval`，集成 API **不提供**审批操作。如需审批，请进入管理人门户的 **Ativos › Negociações › Títulos Públicos**，打开该交易并点击 **Aprovar operação**。在同一页面中还可以取消交易，或在截止时间之后申请时间豁免。可通过[交易查询](/documentation/iaas/boletador/consulta_titulo_publico)或[列表](/documentation/iaas/boletador/listagem_titulos_publicos)跟踪进度。 ::: :::info 截止时间：16:55（巴西利亚时间） 自 16:55（America/Sao_Paulo，含）起，当天不会再有任何交易进入 SELIC： - 只有填写了 `time_exception_reason` 的 POST 才会被接受（未填写时返回 `TTR000054`）； - 截止时间之后，门户中的审批也会被拒绝。此时管理人可以申请时间豁免，交易单将处于 `pending_time_exception_approval`，直至 QI Tech 团队审查理由并放行（或取消）。 16:55 之前，`time_exception_reason` 会被忽略。 ::: ## Request ENDPOINT /trade_treasury/fund_class/{fund_class_key}/operation MÉTODO POST ### Path params | 参数 | 类型 | 描述 | | :---- | :---- | :---- | | `fund_class_key` | string | 基金的唯一标识。 | ```json title="Request Body" { "external_id": "a3f1c2e4-7b8d-4e6f-9a0b-1c2d3e4f5a6b", "operation_date": "2025-12-04", "payment_date": "2025-12-04", "operation_part": "assignee", "operation_type": "outright_operation", "counterparty": { "iselic_number": "33444555", "selic_account_number": "123456789", "document_number": "33.444.555/0001-81" }, "treasury_type": "ntn_b", "unit_price": 1234.567891, "units": 10, "maturity_date": "2035-05-15" } ``` ### 请求体属性 {#atributos-do-body} | 字段 | 类型 | 是否必填 | 描述 | | :---- | :---- | :---- | :---- | | `external_id` | string | 可选 | 您为该交易单设定的标识，在同一基金内唯一。未提供时自动生成（UUID）。最多 36 个字符。参见[重发与重复](#reenvio-e-duplicidade)。 | | `operation_date` | string (date) | 必填 | 交易日期，格式为 `YYYY-MM-DD`。必须为工作日，且等于基金的 `accounting_date`。 | | `payment_date` | string (date) | 必填 | 结算日期，格式为 `YYYY-MM-DD`。必须 `>= operation_date`。对于非远期交易（`outright_operation`、`buyback_operation`），必须等于 `operation_date`。 | | `operation_part` | string | 必填 | 基金在交易中的角色：`assignee`（买方）或 `assignor`（卖方）。为 `assignor` 时，`units` 不得超过基金投资组合中该债券的持有单位数。 | | `operation_type` | string | 必填 | 交易类型：`outright_operation`（买断式）或 `buyback_operation`（回购式）。`buyback_operation` 要求 `operation_part == "assignee"`，且基金已开通回购式交易。`term_outright_operation` 暂不可用（`TTR000042`）。 | | `counterparty` | object | 必填 | 交易对手数据。见下方对象。 | | `treasury_type` | string | 必填 | 债券类型：`lft`、`ltn`、`ntn_b` 或 `ntn_f`。 | | `unit_price` | number | 必填 | 债券单价。可接受任意小数精度；服务器会根据类型向下截断：`buyback_operation` → 8 位小数；其他 → 6 位小数。 | | `units` | integer | 必填 | 债券数量（正整数）。 | | `maturity_date` | string (date) | 必填 | 债券到期日（`YYYY-MM-DD`）。必须严格晚于 `operation_date`。 | | `yearly_negotiated_rate` | number | 条件必填 | 协商年利率，小数形式（`0.144` = 年化 14,4%）。`buyback_operation` **必填**。 | | `return_date` | string (date) | 条件必填 | 返售日期（`YYYY-MM-DD`）。`buyback_operation` **必填**。必须 `> operation_date`。 | | `time_exception_reason` | string | 条件必填 | 在规定时间之外提交交易单的理由。**自 16:55（巴西利亚时间）起必填**；此前会被忽略。最多 500 个字符。 | #### `counterparty` 对象 {#objeto-counterparty} | 字段 | 类型 | 是否必填 | 描述 | | :---- | :---- | :---- | :---- | | `iselic_number` | string | 必填 | 交易对手的 iSELIC 编号（8 位数字）。 | | `selic_account_number` | string | 必填 | 交易对手的 SELIC 账户（9 位数字）。 | | `document_number` | string | 必填 | 交易对手的 CNPJ，带标点（格式 `XX.XXX.XXX/XXXX-XX`），校验位必须有效。 | ## Response STATUS 201 ```json title="Response Body" { "operation_key": "85cfd700-54a4-40f4-bc61-2ece992864ea", "external_id": "a3f1c2e4-7b8d-4e6f-9a0b-1c2d3e4f5a6b", "fund_class": { "fund_class_key": "5122bf31-660a-4f61-a447-38e5e17162dd", "manager_key": "bea7581a-f901-4995-a486-46e18ae61aab", "name": "FUNDO EXEMPLO DTVM", "document_number": "11.222.333/0001-81", "accounting_date": "2025-12-04" }, "status": "pending_manager_approval", "operation_part": "assignee", "operation_type": { "enumerator": "outright_operation", "code": 1052 }, "treasury": { "enumerator": "ntn_b", "code": 760199 }, "operation_date": "2025-12-04", "payment_date": "2025-12-04", "maturity_date": "2035-05-15", "total_operation_value": 12345.67, "units": 10, "unit_price": 1234.567891, "counterparty": { "iselic_number": "33444555", "document_number": "33.444.555/0001-81", "selic_account_number": "123456789" }, "isin_code": "BRSTNCNTB633", "issue_date": "2025-11-04", "operation_data": {} } ``` ### 响应属性 {#atributos-da-resposta} | 字段 | 类型 | 描述 | | :---- | :---- | :---- | | `operation_key` | string | QI Tech 生成的交易唯一标识（UUID）。 | | `external_id` | string | 提供的或自动生成的外部标识。 | | `fund_class` | object | 与交易关联的基金数据。 | | `status` | string | 交易的初始状态：始终为 `pending_manager_approval`。参见[交易状态](/documentation/iaas/boletador/listagem_titulos_publicos#status-da-operacao)。 | | `operation_part` | string | `assignee`（买方）或 `assignor`（卖方）。 | | `operation_type` | object | `{ enumerator, code }`——交易类型及对应的 SELIC 代码。 | | `treasury` | object | `{ enumerator, code }`——债券类型及对应的 SELIC 代码。 | | `operation_date` | string | 交易日期（`YYYY-MM-DD`）。 | | `payment_date` | string | 结算日期（`YYYY-MM-DD`）。 | | `maturity_date` | string | 债券到期日（`YYYY-MM-DD`）。 | | `total_operation_value` | decimal | 交易总额（units × unit_price）。 | | `units` | integer | 债券数量。 | | `unit_price` | number | 债券单价。 | | `counterparty` | object | 交易对手数据（`iselic_number`、`document_number`、`selic_account_number`）。 | | `isin_code` | string | 债券的 ISIN 代码。 | | `issue_date` | string | 债券发行日期（`YYYY-MM-DD`）。 | | `operation_data` | object | 交易的其他内部元数据。 | | `yearly_negotiated_rate`、`return_date`、`return_unit_price`、`total_return_value` | number / string | 返售数据。在 `buyback_operation` 中返回。 | | `time_exception_reason` | string | 时间豁免理由。在截止时间之后提交交易单时返回。 | ## 重发与重复 {#reenvio-e-duplicidade} 如发生错误，请重发请求。重复（`TTR000044`）表示该交易单已存在：请在[列表](/documentation/iaas/boletador/listagem_titulos_publicos)中按 `operation_date` 筛选，并在 `data` 的条目中查找您的 `external_id`。参见[重发与重复](/documentation/iaas/introducao/erros#reenvio-e-duplicidade)。 ## 错误 {#erros} | 状态码 | 代码 | 触发条件 | |---|---|---| | 409 | `TTR000044` | 该基金中已存在使用此 `external_id` 的交易单。 | | 400 | `TTR000054` | 自 16:55（巴西利亚时间）起提交但未填写 `time_exception_reason`。 | | 400 | `TTR000058` | `operation_date`、`payment_date`、`maturity_date` 或 `return_date` 中的日期不存在（例如 `2025-02-30`）。 | | 400 | `TTR000016` | `operation_date` 与基金的会计日期不同。 | | 400 | `TTR000011` | `operation_date` 不是工作日。 | | 400 | `TTR000021` | 非远期交易中 `payment_date` 与 `operation_date` 不同。 | | 400 | `TTR000017` | `payment_date` 早于 `operation_date`。 | | 400 | `TTR000010` | `maturity_date` 等于或早于 `operation_date`。 | | 400 | `TTR000057` | 卖出（`operation_part: assignor`）时 `units` 超过基金投资组合中该债券的持有单位数。 | | 400 | `TTR000037` | ANBIMA 中不存在该 `treasury_type` 和 `maturity_date` 对应的债券。 | | 400 | `TTR000018` / `TTR000019` / `TTR000020` | 回购式交易缺少 `yearly_negotiated_rate`、缺少 `return_date`，或 `return_date` 等于或早于 `operation_date`。 | | 400 | `TTR000042` | `operation_type` 未实现、回购式交易使用了 `operation_part: assignor`，或基金未开通回购式交易。 | | 400 | `TTR000035` | 交易对手的 CNPJ 无效。 | | 400 | `TTR000027` / `TTR000028` / `TTR000029` / `TTR000038` / `TTR000048` | 基金的公共债券注册信息不完整（目标账户、托管人、SELIC 账户或投资组合）。请联系集成团队。 | | 404 | `TTR000004` | 该 `fund_class_key` 不存在。 | | 403 | `TTR000040` | 该基金不属于您的管理人。 | 认证、权限和主机相关错误：参见 [API 错误](/documentation/iaas/introducao/erros)。 --- # 公共债券查询 URL: /zh-Hans/documentation/iaas/boletador/consulta_titulo_publico 按 `operation_key` 返回一张公共债券交易单及其状态历史。可用于跟踪交易的审批、在 SELIC 中的登记以及结算。 :::info 适用范围 | 角色 | 主机 | 所需权限 | | ------ | ------------- | -------- | | 管理人 | `manager-api` | 读取 | 各主机的 Base URL：[环境（主机）](/documentation/iaas/introducao/inicio#ambientes-hosts)。 ::: ## Request ENDPOINT /trade_treasury/fund_class/{fund_class_key}/operation/{operation_key} MÉTODO GET ### Path params | 参数 | 类型 | 描述 | | :---- | :---- | :---- | | `fund_class_key` | string | 基金的唯一标识。 | | `operation_key` | string | [创建交易单](/documentation/iaas/boletador/boletador_titulos_publicos)时返回的交易标识。 | ## Response STATUS 200 ```json title="Response Body" { "operation_key": "85cfd700-54a4-40f4-bc61-2ece992864ea", "external_id": "a3f1c2e4-7b8d-4e6f-9a0b-1c2d3e4f5a6b", "fund_class": { "fund_class_key": "5122bf31-660a-4f61-a447-38e5e17162dd", "manager_key": "bea7581a-f901-4995-a486-46e18ae61aab", "name": "FUNDO EXEMPLO DTVM", "document_number": "11.222.333/0001-81", "accounting_date": "2025-12-04", "internal_transfer_for_main_account": false }, "status": "pending_registration", "operation_part": "assignee", "operation_type": { "enumerator": "outright_operation", "code": 1052 }, "treasury": { "enumerator": "ntn_b", "code": 760199 }, "operation_date": "2025-12-04", "payment_date": "2025-12-04", "maturity_date": "2035-05-15", "total_operation_value": 12345.67, "units": 10, "unit_price": 1234.567891, "counterparty": { "iselic_number": "33444555", "document_number": "33.444.555/0001-81", "selic_account_number": "123456789" }, "isin_code": "BRSTNCNTB633", "issue_date": "2025-11-04", "operation_data": {}, "status_events": [ { "status": "pending_manager_approval", "metadata": {}, "datetime": "2025-12-04 13:10:00.000000" }, { "status": "pending_registration", "metadata": {}, "datetime": "2025-12-04 13:25:00.000000" } ] } ``` ### 响应属性 {#atributos-da-resposta} 字段与[创建交易单](/documentation/iaas/boletador/boletador_titulos_publicos#atributos-da-resposta)时相同，另外还有： | 字段 | 类型 | 描述 | | :---- | :---- | :---- | | `status` | string | 当前状态。参见[交易状态](/documentation/iaas/boletador/listagem_titulos_publicos#status-da-operacao)。 | | `status_events` | array | 状态历史，包含每次变更的 `status`、`metadata` 和 `datetime`。 | | `selic_operation_id`、`selic_specification_id`、`selic_command_number` | string | 在 SELIC 中的标识。登记后返回。 | | `yearly_negotiated_rate`、`return_date`、`return_unit_price`、`total_return_value` | number / string | 返售数据。在 `buyback_operation` 中返回。 | | `time_exception_reason` | string | 时间豁免理由（如有）。 | | `time_exception_released_at` | string | QI Tech 在截止时间之后放行该交易单的日期和时间。 | ## 错误 {#erros} | 状态码 | 代码 | 触发条件 | |---|---|---| | 404 | `TTR000013` | 该基金中不存在使用此 `operation_key` 的交易。 | | 404 | `TTR000004` | 该 `fund_class_key` 不存在。 | | 403 | `TTR000040` | 该基金不属于您的管理人。 | 认证、权限和主机相关错误：参见 [API 错误](/documentation/iaas/introducao/erros)。 --- # 公共债券列表 URL: /zh-Hans/documentation/iaas/boletador/listagem_titulos_publicos 分页列出基金的公共债券交易单，按 `operation_date` 从新到旧排列。如需查询特定交易，请使用[交易查询](/documentation/iaas/boletador/consulta_titulo_publico)。 :::info 适用范围 | 角色 | 主机 | 所需权限 | | ------ | ------------- | -------- | | 管理人 | `manager-api` | 读取 | 各主机的 Base URL：[环境（主机）](/documentation/iaas/introducao/inicio#ambientes-hosts)。 ::: ## Request ENDPOINT /trade_treasury/fund_class/{fund_class_key}/operations MÉTODO GET ### Path params | 参数 | 类型 | 描述 | | :---- | :---- | :---- | | `fund_class_key` | string | 基金的唯一标识。 | ### Query params | 参数 | 类型 | 默认 | 最大 | 描述 | | :---- | :---- | :---- | :---- | :---- | | `limit` | integer | 100 | 500 | 每页条目数。 | | `page` | integer | 0 | — | 页码（从 0 开始）。 | | `status` | string | — | — | 按交易的确切状态筛选。参见[交易状态](#status-da-operacao)。 | | `not_status` | string | — | — | 排除处于特定状态的交易。 | | `status_list` | string | — | — | 以逗号分隔的状态列表（例如：`pending_manager_approval,pending_time_exception_approval`）。 | | `operation_part` | string | — | — | 按基金的角色筛选（`assignee` 或 `assignor`）。 | | `treasury_type` | string | — | — | 按债券类型筛选（`lft`、`ltn`、`ntn_b`、`ntn_f`）。 | | `operation_type` | string | — | — | 按交易类型筛选（`outright_operation`、`buyback_operation`）。 | | `operation_date` | string | — | — | 按确切的交易日期筛选（`YYYY-MM-DD`）。 | | `from_operation_date` | string | — | — | 筛选交易日期 `>=` 该值的交易（`YYYY-MM-DD`）。 | | `to_operation_date` | string | — | — | 筛选交易日期 `<=` 该值的交易（`YYYY-MM-DD`）。 | | `maturity_date` | string | — | — | 按确切的到期日筛选（`YYYY-MM-DD`）。 | | `from_maturity_date` | string | — | — | 筛选到期日 `>=` 该值的交易（`YYYY-MM-DD`）。 | | `to_maturity_date` | string | — | — | 筛选到期日 `<=` 该值的交易（`YYYY-MM-DD`）。 | ## Response STATUS 200 ```json title="Response Body" { "data": [ { "operation_key": "e96ff035-e0bc-4819-931a-6a9f7fc1c597", "external_id": "a3f1c2e4-7b8d-4e6f-9a0b-1c2d3e4f5a6b", "fund_class": { "fund_class_key": "9b6145dc-2207-428d-84c1-2f949461891a", "manager_key": "73a21e11-0ab7-461d-a93f-1e90c0a5dc0d", "name": "FUNDO DE INVESTIMENTO TESTE", "document_number": "11.222.333/0001-81", "accounting_date": "2025-04-14", "internal_transfer_for_main_account": false, "custodian": { "name": "CUSTODIANTE EXEMPLO", "document_number": "44.555.666/0001-81", "iselic_number": "44555666" }, "selic_account_number": "000216832", "target_account_key": "d3dcbf3c-1bbf-495b-b792-ac448ee20ac4" }, "status": "pending_manager_approval", "operation_part": "assignee", "operation_type": { "enumerator": "outright_operation", "code": 1052 }, "treasury": { "enumerator": "ntn_b", "code": 760199 }, "operation_date": "2025-04-14", "payment_date": "2025-04-14", "maturity_date": "2025-05-15", "total_operation_value": 250.0, "units": 5, "unit_price": 50.0, "counterparty": { "iselic_number": "33444555", "document_number": "33.444.555/0001-81", "selic_account_number": "123456789" }, "isin_code": "BRSTNCNTB633", "issue_date": "2000-07-15", "operation_data": {} } ], "limit": 100, "page": 0, "is_last_page": true } ``` ### 响应属性 {#atributos-da-resposta} | 字段 | 类型 | 描述 | | :---- | :---- | :---- | | `data` | array | 交易列表。每一项包含与单笔查询相同的字段。 | | `limit` | integer | 该页返回的条目数。 | | `page` | integer | 当前页（从 0 开始）。 | | `is_last_page` | boolean | 指示是否为结果的最后一页。 | 如已存在，每笔交易还可能返回 `selic_operation_id`、`selic_specification_id`、`selic_command_number`、回购式交易的返售数据（`yearly_negotiated_rate`、`return_date`、`return_unit_price`、`total_return_value`）、`time_exception_reason` 和 `time_exception_released_at`。 ## 交易状态 {#status-da-operacao} | 阶段 | 状态 | 含义 | |---|---|---| | 审批 | `pending_manager_approval` | 等待管理人在门户中审批。所有交易单的初始状态。 | | 审批 | `pending_time_exception_approval` | 管理人在 16:55 之后申请了时间豁免；等待 QI Tech 团队处理。 | | 审批 | `pending_administrator_approval` | 等待行政管理人（旧状态）。 | | 预匹配 | `pending_registration`、`pending_counterparty_registration`、`pending_specification`、`pending_counterparty_specification`、`pending_specification_confirmation`、`pending_counterparty_specification_confirmation` | 基金方和交易对手方在 SELIC 中的登记与明细确认。 | | 预匹配 | `specification_mismatched` | 交易对手在 SELIC 中录入的数据与交易单不一致；由 QI Tech 处理差异。 | | 预匹配 | `registration_failed` | SELIC 拒绝了交易单的登记。原因记录在 `status_events` 中该事件的 `metadata` 里。由 QI Tech 重新提交至 SELIC，或由管理人在门户中取消该交易。 | | 结算 | `pending_payment`、`pending_payment_confirmation`、`pending_internal_transfer`、`pending_internal_transfer_confirmation`、`pending_order_creation`、`pending_order_confirmation`、`pending_order_expectation_creation`、`pending_order_expectation_confirmation`、`pending_expectation_confirmation`、`pending_spb_message`、`pending_spb_message_confirmation` | 交易的资金结算。 | | 结算 | `pending_manual_order_validation` | 结算出现差异；由 QI Tech 人工核对交易。 | | 纳入投资组合 | `pending_wallet_inclusion` | 将债券纳入基金投资组合。 | | 返售 | `pending_buyback_expectation_creation`、`pending_buyback_expectation_confirmation` | 回购式交易的返售（仅 `buyback_operation`）。 | | 最终 | `operation_finished` | 交易已完成。 | | 最终 | `canceled` | 交易已取消。 | ## 错误 {#erros} | 状态码 | 代码 | 触发条件 | |---|---|---| | 400 | `TTR000041` | `status`、`not_status`、`status_list`、`treasury_type`、`operation_type` 或 `operation_part` 的值无效。 | | 400 | `QIT000010` | 查询参数无效：日期不符合 `YYYY-MM-DD` 格式、`limit` 大于 500 或 `page` 为负数。 | | 404 | `TTR000004` | 该 `fund_class_key` 不存在。 | | 403 | `TTR000040` | 该基金不属于您的管理人。 | 认证、权限和主机相关错误：参见 [API 错误](/documentation/iaas/introducao/erros)。