版本 v1.4
最后更新:2026-11-13
快速开始|十分钟完成首次 API 调用 - FTLib
本指南帮助你用最短路径完成首次调用:确认密钥、发出一个 REST 请求、理解响应结构,再建立一条推送连接。示例使用命令行工具 curl,你可以用任意 HTTP 客户端复现。
准备工作
接入前需要准备三件事:有效的 API Key、可访问外网的开发环境,以及明确的证券代码。证券代码采用 代码.交易所 格式,例如 600519.SH、000001.SZ。
| 项目 | 说明 |
|---|---|
| API Key | 通过接入咨询获取,按数据域与配额授权 |
| 网络 | 可访问 api.ftlib.com 与 push.ftlib.com |
| 时区 | 所有时间戳为毫秒级 epoch,展示时使用 Asia/Shanghai |
| 代码 | 优先使用带交易所后缀的完整代码 |
密钥不要写入代码仓库
请通过环境变量或密钥管理服务注入 API Key,不要提交到 Git 仓库,也不要在前端代码中暴露。
第一个请求
将密钥放入环境变量,然后请求一只证券的快照。响应会返回最新价、成交量与五档盘口。
bash
export FTLIB_API_KEY="your_api_key"
curl -H "Authorization: Bearer $FTLIB_API_KEY" \
"https://api.ftlib.com/v1/quote/snapshot?symbols=600519.SH"
如果密钥有效且代码格式正确,HTTP 状态码为 200,响应体中的 code 为 0。若返回 401 或 403,请检查密钥与授权范围;若返回 400,请检查证券代码格式。
解析响应
所有 REST 接口使用统一响应封装。data 为业务数据,request_id 用于排查问题。
json
{
"code": 0,
"message": "ok",
"request_id": "req_7f3c9a21",
"data": [
{
"symbol": "600519.SH",
"name": "贵州茅台",
"ts": 1794794400000,
"last": 1688.00,
"volume": 2154300,
"amount": 3635123400.00,
"bids": [{ "price": 1687.90, "volume": 300 }],
"asks": [{ "price": 1688.00, "volume": 200 }]
}
]
}
建议在客户端统一处理三件事:检查 code 是否为 0、记录 request_id、对缺失字段做显式判断。不要假设所有品种都返回相同字段。
接入推送
实时行情通过 WebSocket 推送。连接建立后先发送鉴权消息,再发送订阅消息。seq 表示期望的续传位置,首次连接可设为 0。
json
{
"op": "subscribe",
"channel": "quote.l1",
"symbols": ["600519.SH", "000001.SZ"],
"seq": 0
}
客户端应处理心跳、序列号缺口与断线重连。生产环境建议为每条消息记录 seq,并在重连时携带最后处理的序列号。