Flex 报表服务

Flex Web Service 是 IBKR 的报表下载接口，用来按预先配置好的 Flex Query 拉取账户报表。它不是行情接口，也不是下单接口。

使用 Flex Web Service 前，需要先在 Client Portal 中创建 Flex Query，并生成 Flex Token。官方 Flex 文档说明，程序化请求需要 Token、Query ID，并通过 SendRequest 和 GetStatement 两步获取报表。

适合场景

场景	是否适合
每天下载成交、现金流水、持仓或活动报表	适合
税务、对账、绩效统计、后台入库	适合
实时行情、实时持仓、下单	不适合
低延迟策略或盘中交易判断	不适合

核心概念

名称	中文理解
Flex Query	在 Client Portal 里配置的报表模板，决定返回哪些字段和账户范围。
Query ID	某个 Flex Query 模板的编号。程序请求报表时要传它。
Flex Token	Flex Web Service 的访问令牌。它不是 IBKR 登录密码，也不是 OAuth token。
Reference Code	调用 `SendRequest` 成功后返回的引用码，用它再调用 `GetStatement` 取报表。
Version	Flex Web Service 版本。官方示例中常见 `v=3`。

两步请求流程

步骤	请求	作用
1	`/SendRequest`	提交报表生成请求，传入 `t` token、`q` query id、`v` version。
2	`/GetStatement`	使用 token 和 reference code 获取生成好的报表内容。

请求结构示意：

https://ndcdyn.interactivebrokers.com/AccountManagement/FlexWebService/SendRequest?t=TOKEN&q=QUERY_ID&v=3
https://ndcdyn.interactivebrokers.com/AccountManagement/FlexWebService/GetStatement?t=TOKEN&q=REFERENCE_CODE&v=3

上面的 TOKEN、QUERY_ID、REFERENCE_CODE 都必须替换成自己的真实值。示例用于说明参数位置和调用顺序；拿到 Flex Token 与 Query ID 后，再按自己的报表模板发起请求。

Query 参数

参数	用在	必填	中文解释
`t`	`/SendRequest`、`/GetStatement`	是	Flex Web Service Token。
`q`	`/SendRequest`	是	Flex Query ID，也就是报表模板编号。
`q`	`/GetStatement`	是	上一步返回的 `ReferenceCode`，表示某一次报表生成任务。
`v`	`/SendRequest`、`/GetStatement`	是	Flex Web Service 版本，官方建议使用 `3`。

SendRequest 成功后并不一定马上能取到完整报表。报表越大，生成时间越长。程序应等待一段时间后再调用 GetStatement，或对 GetStatement 做有限次数重试。

常见返回字段

字段	中文解释
`Status`	请求状态。成功通常为 `Success`，失败通常为 `Fail`。
`ReferenceCode`	报表生成引用码。只有 `SendRequest` 成功后才用于下一步。
`url`	获取报表的服务地址。
`ErrorCode`	失败时的错误码。
`ErrorMessage`	失败时的错误文本，例如 token 失效、query id 无效等。

成功生成请求的返回结构通常类似：

<FlexStatementResponse>
  <Status>Success</Status>
  <ReferenceCode>1234567890</ReferenceCode>
  <url>...</url>
</FlexStatementResponse>

失败时通常类似：

<FlexStatementResponse>
  <Status>Fail</Status>
  <ErrorCode>1012</ErrorCode>
  <ErrorMessage>Token has expired.</ErrorMessage>
</FlexStatementResponse>

常见错误码

错误码	中文解释
`1001`	报表暂时无法生成，稍后重试。
`1003`	报表不可用。
`1004`	报表尚未完整生成，稍后重试。
`1005`	结算数据尚未准备好。
`1006`	FIFO 盈亏数据尚未准备好。
`1007`	MTM 盈亏数据尚未准备好。
`1012`	Token 已过期。

报表字段怎么理解

Flex Query 返回的报表字段取决于你在 Client Portal 里配置的模板。常见报表包括：

报表	常见字段
Activity Statement	日期、现金、成交、持仓、手续费、股息、资金变化。
Trade Confirmation	交易日、结算日、symbol、买卖方向、数量、价格、佣金。
Cash Report	币种、现金余额、现金变动、说明。
Positions	合约、数量、成本、市场价值、未实现盈亏。

易错点

Flex Token 有有效期，也可以绑定 IP；部署到服务器后要确认出口 IP。
Flex Query 是按创建它的用户名和账户范围管理的，子账户、FA 主账户和个人账户看到的 query 可能不同。
使用相对日期的 Flex Query 时，报表日期范围由模板规则决定；需要精确回测或对账时，优先使用明确的日期范围。
Flex 返回 XML，不是 JSON。入库前应使用 XML 解析器读取字段。
不要把 Flex Token 写进前端代码、公开图片或公开日志。

和 TWS API 的关系

TWS API 适合盘中实时开发：连接、行情、订单、持仓和成交回调。Flex Web Service 适合盘后或后台报表：拉取完整活动、成交确认和现金流水。真实系统通常两者都会用：TWS API 负责交易链路，Flex 负责报表归档和对账。