快速开始
欢迎使用 TS 数据筛选平台 开放 API。本文档面向需要通过 API 接入平台的开发者，覆盖签名认证、任务创建、状态查询与结果下载的完整流程。
接入流程概览
- 申请账号并生成 ApiKey
- 按签名规则生成
X-Api-Key - 调用接口创建任务：
- 推荐方式：使用「一键上传并创建任务」整合接口（1 步完成）
- 标准方式：依次调用「上传文件」 → 「创建任务」（2 步完成）
- 轮询「查询任务状态」接口，等待任务完成
- 调用「生成下载链接」接口获取结果文件
- 遵守限流规则上线
先在线试一试
正式写代码前，可以用在线调试台走一遍完整流程：填入账号与 ApiKey，选任务类型、国家，上传文件，查状态、拿下载链接，每一步都会给出等价的 curl 命令。
在线调试台
地址：https://console.ts-filter.com/
调试台是一个网页工具，覆盖本文档的全部接口，无需写代码即可验证账号、参数与文件：
| 功能 | 说明 |
|---|---|
| 凭据与地址 | 填入账号、ApiKey，调试台按签名规则自动生成 X-Api-Key |
| 查询余额 / 产品状态 | 下单前确认余额与任务类型是否可下单 |
| 上传并创建任务 | 任务类型、国家可下拉选择或手工输入；支持单任务与批量接口，以及 skipDedup、skipCountryFilter 开关 |
| 查询任务状态 | 创建后自动带入任务 ID，可每 5 秒轮询直到完成 |
| 生成下载链接 | txt / excel，支持活跃天数、年龄、性别筛选 |
| 请求日志 | 每次调用的请求头、表单、响应与等价 curl 命令，可一键复制到自己的代码中对照 |
使用须知
- 调试台调用的是正式接口，创建任务会真实扣费，请用小文件验证。
- ApiKey 只保存在你自己的浏览器本地，调试台服务端仅用它计算签名，不做存储。
- 调试台的源码可作为接入示例（Node + 静态页面，无数据库），如需自行部署请联系客服获取。
账号准备
| 参数名称 | 类型 | 必填 | 描述 |
|---|---|---|---|
| act | String | 是 | 平台分配的用户账号（如：partner01） |
| ApiKey | String | 是 | 登录后台在 API 管理 页生成 |
请求约定
- 统一域名：
https://api.ts-filter.com/ - 统一根路径：
/api/openapi - 请求头：
X-Api-Account: <act>
X-Api-Key: <timestamp.signature>
X-Api-Key 的生成方式见签名算法。
接口一览
| 接口 | 方法 | 路径 | 说明 |
|---|---|---|---|
| 上传文件 | POST | /api/openapi/upload | 上传号码文件，返回预估费用 |
| 创建筛选任务 | POST | /api/openapi/addTask | 基于已上传文件创建任务 |
| 一键上传并创建任务 | POST | /api/openapi/uploadAndCreateTask | 上传 + 创建一步完成（推荐） |
| 查询任务状态 | GET | /api/openapi/task/{taskId} | 轮询任务进度与状态 |
| 生成下载链接 | POST | /api/openapi/download | 任务完成后获取结果文件 |
| 查询产品状态（单个） | GET | /api/openapi/taskType/status/{taskType} | 查询任务类型是否可下单 |
| 批量查询产品状态 | POST | /api/openapi/taskType/statusBatch | 批量查询任务类型上架状态 |
| 查询用户余额 | GET | /api/openapi/user/balance | 查询账户余额 |