公共债券交易单
为基金登记联邦公共债券(LFT、LTN、NTN-B、NTN-F)的买断式买入或卖出交易单,或回购式买入交易单。交易单在管理人审批后登记到 SELIC。
适用范围
| 角色 | 主机 | 所需权限 |
|---|---|---|
| 管理人 | manager-api | 写入 |
各主机的 Base URL:环境(主机)。
审批在门户中完成
截止时间: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}/operationMÉTODO
POSTPath params
| 参数 | 类型 | 描述 |
|---|---|---|
fund_class_key | string | 基金的唯一标识。 |
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"
}
请求体属性
| 字段 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
external_id | string | 可选 | 您为该交易单设定的标识,在同一基金内唯一。未提供时自动生成(UUID)。最多 36 个字符。参见重发与重复。 |
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 对象
| 字段 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
iselic_number | string | 必填 | 交易对手的 iSELIC 编号(8 位数字)。 |
selic_account_number | string | 必填 | 交易对手的 SELIC 账户(9 位数字)。 |
document_number | string | 必填 | 交易对手的 CNPJ,带标点(格式 XX.XXX.XXX/XXXX-XX),校验位必须有效。 |
Response
STATUS
201Response 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": {}
}
响应属性
| 字段 | 类型 | 描述 |
|---|---|---|
operation_key | string | QI Tech 生成的交易唯一标识(UUID)。 |
external_id | string | 提供的或自动生成的外部标识。 |
fund_class | object | 与交易关联的基金数据。 |
status | string | 交易的初始状态:始终为 pending_manager_approval。参见交易状态。 |
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 | 时间豁免理由。在截止时间之后提交交易单时返回。 |
重发与重复
如发生错误,请重发请求。重复(TTR000044)表示该交易单已存在:请在列表中按 operation_date 筛选,并在 data 的条目中查找您的 external_id。参见重发与重复。
错误
| 状态码 | 代码 | 触发条件 |
|---|---|---|
| 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 错误。