银行读取与电子凭证（开发中）

本页记录 9 项银行接口的当前契约。功能默认关闭，验证范围限于本地合成场景，真实银行环境尚未验证。生产所需的原生材料、运行时输入提供器和服务就绪流程尚未完整接通；接口注册不代表当前分发包已经可以登录银行或提供可用服务。

这些接口覆盖账户、资产和流水读取，以及电子凭证的生成与下载。它们不提供远程登录、开户、KYC 或资金转移。

本地启动配置

银行启动须一起指定 --bank-native-package、--bank-environment、--bank-language。以下配置记录已知的本地运行条件；它们不能替代安装包中的必要材料。缺少必要信息时启动会报告缺项，不进入认证。

所有下列选项也接受平铺 TOML/XML 键，名称将 - 换为 _，例如 bank_native_app_data_root。显式 CLI 值优先；这些观察选项不读取环境变量，也没有推测默认值。本地观察文件/目录必须使用绝对路径；它们与 OpenD 自有工作目录分别管理。

CLI 选项	配置契约
--bank-native-app-data-root、--bank-native-sdk-workspace	原生应用数据目录与 SDK 工作目录，分别指定
--bank-distribution-area、--bank-release-app-version	必须一起指定；后者为显式 true / false
--bank-native-platform-primary、--bank-native-platform-guaranteed	Platform 的主/保障地址观察
--bank-native-bank-primary、--bank-native-bank-guaranteed	Bank 的主/保障地址观察；四项路由须完整，已确认无保障地址时使用 none
--bank-http-timeout-ms、--bank-http-proxy-type	必须一起指定；代理类型为 no-override、socks4、socks5、http-tunnel
--bank-http-proxy-host、--bank-http-proxy-port	非 no-override 代理必填；no-override 不接受代理附属字段
--bank-http-proxy-user-file、--bank-http-proxy-password-file	非 no-override 代理必填；读取文件的完整 UTF-8 内容，不裁剪空格或换行，空文件表示空值
--bank-native-common-config-file、--bank-native-developer-ini	已观察到的原生配置文件路径；提供路径不等于文件内容已满足所需合同

no-override 保留传输库原本的代理环境行为，并不强制直连。缺少整个观察组会保留为未提供；部分观察组、未知枚举、非法数值或相对观察路径会作为配置错误拒绝。银行密码只通过本地交互输入，关闭密码回显；退出或取消后不会开始下一次认证。

入口与权限

接口	REST POST	MCP	CLI
账户信息	/api/get-bank-account-info	futu_get_bank_account_info	get-bank-account-info
活期资产	/api/get-bank-demand-assets	futu_get_bank_demand_assets	get-bank-demand-assets
按状态查询账户	/api/get-bank-accounts-by-status	futu_get_bank_accounts_by_status	get-bank-accounts-by-status
流水筛选项	/api/get-bank-transaction-filters	futu_get_bank_transaction_filters	get-bank-transaction-filters
流水列表	/api/get-bank-transactions	futu_get_bank_transactions	get-bank-transactions
流水详情	/api/get-bank-transaction-detail	futu_get_bank_transaction_detail	get-bank-transaction-detail
综合资产	/api/get-bank-assets	futu_get_bank_assets	get-bank-assets
生成电子凭证	/api/generate-bank-statement	futu_generate_bank_statement	generate-bank-statement
下载电子凭证	/api/download-bank-statement	futu_download_bank_statement	download-bank-statement

九项接口均要求经过认证的 acc:read API key；兼容模式也不允许无凭据访问。账户限制（包括显式配置及解析后的限制）、卡号、市场、标的和买卖方向限制均须未配置。显式空集合也属于配置了限制，不能用于银行完整账户域数据。密钥过期、机器绑定及当前权限仍会检查。

读取和下载依赖 desktop_phase2_reads、bank_external_services 两项运行条件；生成还依赖独立的 bank_statement_generation。可分别通过 --enable-desktop-phase2-reads、--enable-bank-external-services 和 --enable-bank-statement-generation 显式开启。后两项也支持 enable_bank_external_services / enable_bank_statement_generation 配置键，以及 FUTU_ENABLE_BANK_EXTERNAL_SERVICES / FUTU_ENABLE_BANK_STATEMENT_GENERATION 环境变量（仅 true / false）；均默认关闭，生成开关不隐含开启读取。单独开启条件不能替代当前有效的银行会话与完整生产初始化。

REST 使用平铺 JSON 请求体及 Authorization: Bearer，字段名称采用 snake_case。MCP 使用对应的独立类型参数，不使用 c2s_json；认证上下文或显式 api_key 必须对应实际转发调用者。CLI 使用 --rest-url、--api-key 或相应环境变量。密钥不进入业务 JSON。

Gateway/gRPC 使用对应的 Protobuf Request.c2s。本地公开协议 ID 按表顺序为 0x7F200031 至 0x7F200039，不是银行服务端命令号。

所有请求均必填 extension_version: 1。未知字段、错误类型或不支持的版本会被拒绝；请求不接受用户身份、来源信息或连接凭据覆盖值。

七项读取的参数

下表只列版本字段之外的参数。必填布尔值必须显式提供，false 有效。

接口	参数
get-bank-account-info	无额外参数
get-bank-demand-assets	必填 is_need_exchange_amount（布尔值）
get-bank-accounts-by-status	可选 statuses（字符串数组）；空数组表示全部，保留顺序和重复值
get-bank-transaction-filters	无额外参数
get-bank-transactions	必填 page_size（1–100）、page_flag（字符串，可为空）；可选 min_amount、max_amount、start_time_ms、end_time_ms、filter_type_list、keyword
get-bank-transaction-detail	必填非空 transaction_id；可选 business_type、sub_business_type、business_id
get-bank-assets	必填 currency 和 valuation_options

金额上下界使用字符串，保留小数精度；不转换为浮点数。时间上下界为有符号毫秒整数，不接受日期字符串。分页游标作为不透明字符串处理，首请求可传空串，后续使用返回值。

filter_type_list 的每项包含必填 type_key 和可选 key_list 字符串数组。使用当前筛选项响应中的类型与值；已有筛选项和已观察流水的资格会在当前会话下检查。详情参数必须对应当前可用的记录或关联记录。网页详情入口不会被自动转换为本接口；任意链接不能作为读取授权。

valuation_options 包含必填的 currency、use_before_price、use_after_price、use_overnight_price、use_option_combo。四个布尔值均须显式传入；外层币种与估值币种是两个独立字段。报价权限和夜盘可用性来自当前会话，不能由请求自行声明。

示例仅展示请求形状，需完整就绪后才能成功：

{
  "extension_version": 1,
  "page_size": 20,
  "page_flag": "",
  "min_amount": "0.0100",
  "filter_type_list": []
}

响应保留字段缺失、空字符串、列表顺序、重复项及金额文本。公开的二进制字段在 JSON 中使用标准 Base64，Protobuf 中使用 bytes；缺失与空字节不同。非零错误可能仍带有 s2c，客户端应保留完整响应，不能把缺失金额补为零或把部分数据当成完整成功。

生成凭证

generate-bank-statement 另需非空 transaction_id 与调用者明确提供的非空 intent_key。交易 ID 必须来自当前可用的流水记录。CLI/MCP 不自动生成意图键。

{"transaction_id":"sample-transaction","intent_key":"sample-statement-intent","extension_version":1}

同一已认证主体、调用者、环境及意图对应一份稳定回执。重复请求读取原有历史；修改同一意图对应的交易会冲突。执行状态不明时不会自动再次生成。

s2c.receipt 包含 receipt_id、intent_key、state，以及可选的 file_id、result_code。file_id 是只读关联信息，不是下载请求参数。

state	含义	外层结果
prepared	已记录，尚未确认提交	非零
submitted_unknown	无法确定是否执行	非零，保留回执
awaiting_association	尚无可用的非空文件关联	非零，保留缺失或空关联
generated	已取得非空文件关联	ret_type: 0
rejected	已知生成请求被拒绝	非零，保留回执

已知诊断保留为 64 位 result_code；只有能表示为 32 位的值才同时出现在外层 err_code。没有诊断时保持缺失，不补零。有诊断的 submitted_unknown 仍是未知状态。

按回执下载

download-bank-statement 只接受非空 receipt_id 和版本字段。当前主体与调用者必须有权访问原回执；接口从已有生成结果取文件关联，不接受 URL、文件 ID 或服务器路径，不触发重新生成。

{"receipt_id":"sample-receipt","extension_version":1}

下载使用当前有效的 HTTP 认证状态。业务 TCP 连接断开本身不会要求重新生成；主体变化、认证失败、权限、来源、存储或相关运行条件变化仍会使请求或最终输出失败。下载不依赖生成开关。

s2c.result 包含 receipt_id、state，以及可选的 http_status、native_transfer_code、transport_error、filename、content。

state	结果
downloaded	HTTP 200 且收到完整非空内容；ret_type: 0，content 为 Base64
empty_body	HTTP 200 但正文为空；非零，无文件内容
http_failure	非 200 状态；非零，保留实际状态
transfer_failure	传输未完成；非零，保留传输码及已观察到的 HTTP 状态，不返回部分字节
transport_error	其他已分类的传输错误；非零，不虚构状态或传输码

下载诊断使用上述独立字段，不把 HTTP/传输码伪装成银行业务 err_code。

filename.state 为 available、unsafe 或 unsupported。其余可选字段是 source_name、safe_basename、origin、unsafe_reason、unsupported_reason；origin 可为 extended_header、plain_header 或 transaction_fallback。文件名不适合本地保存或无法可靠解析时，完整内容仍可返回，但不会虚构安全文件名。

CLI 输出

以下是参数形状示例，不是生产登录或启用指南：

futucli generate-bank-statement --rest-url "$FUTU_REST_URL" \
  --api-key "$FUTU_API_KEY" --extension-version 1 \
  --transaction-id sample-transaction --intent-key sample-statement-intent

futucli download-bank-statement --rest-url "$FUTU_REST_URL" \
  --api-key "$FUTU_API_KEY" --extension-version 1 \
  --receipt-id sample-receipt --output-file ./statement.bin

默认输出完整 JSON，包括失败回执和 Base64 内容。只有显式提供 --output-file 且取得完整下载成功结果时才保存文件；既有目标不会被覆盖。空正文、部分传输或失败响应不创建目标文件。保存路径由调用者指定，不使用服务器文件名选择目录或覆盖文件。