API开发

本文档描述对外 API 的调用方式。

1. 基础信息

• 基础地址：https://etf.dqgxl.com
• 认证方式：请求头 X-API-Key: sk-...
• 幂等键（可选）：Idempotency-Key: <unique-id>
• 返回格式：JSON

示例：

curl -X GET "https://etf.dqgxl.com/api/jobs/<job_id>" \
  -H "X-API-Key: sk-xxxxxxxx"

2. 鉴权与权限

• API Key 由管理员审批发放，并绑定到您的账户
• 如需新增、重置、吊销 API Key，请联系管理员处理
• 请妥善保管 API Key，避免泄露给无关人员

3. 策略ID与名称

strategy_id	策略名称
a_industry_etf_rot	A股行业动量轮动
extend_global_etf	全球资产轮动扩容版
global_etf_standard	全球资产轮动标准版
multi_factor_rotation_default	多因子轮动标准版
low_vol_rotation_default	低波动组合标准版
corr_filter_rotation_default	低相关组合标准版

4. 接口清单

4.1 提交策略运行

• 方法：POST
• 路径：/api/strategy/run
• 作用：创建任务并返回 job_id（与前端任务机制一致）
• 权限：仅允许调用已开通权限的策略；无权限会直接拒绝

请求头：

• Content-Type: application/json
• X-API-Key: sk-...
• Idempotency-Key: ...（可选）

请求体：

{
  "strategy_id": "low_vol_rotation_default",  # 策略ID（见上方映射表）
  "start_date": "20260101",                   # 开始日期，支持 YYYYMMDD / YYYY-MM-DD，且不能早于该策略最早可回测日期
  "end_date": "20260314",                     # 结束日期，且必须在最近2个月窗口内
  "params": {}                                # 策略参数对象，仅允许该策略支持的参数
}

成功响应示例：

{
  "ok": true,                          # 请求是否成功
  "idempotent": false,                 # 是否命中幂等复用
  "job_id": "a3d8...b9",               # 任务ID（后续轮询使用）
  "status": "running",                 # 当前状态：running/completed/failed
  "cached": false,                     # 是否命中已完成缓存
  "deduped_inflight": false,           # 是否命中运行中去重
  "cache_source_job_id": "",           # 缓存来源任务ID（cached=true时有值）
  "inflight_source_job_id": "",        # 运行中复用任务ID（deduped_inflight=true时有值）
  "cache_ttl_seconds": 15              # 缓存有效期（秒）
}

4.2 轮询任务状态

• 方法：GET
• 路径：/api/jobs/{job_id}
• 作用：查询任务状态与仓位快照

成功响应示例（仅返回仓位快照，不返回 Web 端展示明细）：

{
  "ok": true,                          # 请求是否成功
  "job_id": "a3d8...b9",               # 任务ID
  "status": "completed",               # 任务状态：running/completed/failed
  "progress": 100,                     # 进度（0-100）
  "error": "",                         # 失败信息（失败时有值）
  "position_snapshot": {
    "snapshot_date": "2026-03-14",     # 仓位快照日期
    "position_count": 2,               # 持仓条数
    "total_weight": 0.95,              # 总仓位
    "cash_weight": 0.05,               # 现金仓位
    "positions": [
      {
        "date": "2026-03-14",          # 持仓日期
        "code": "510300.SH",           # 标的代码
        "name": "沪深300ETF",           # 标的名称
        "price": 3.81,                 # 当前价格
        "weight": 0.60,                # 组合权重
        "pnl_rate": 0.12,              # 持有期收益率
        "day_pnl_rate": 0.003,         # 当日收益率
        "days_held": 8                 # 持有天数
      }
    ]
  }
}

5. 限流与时间窗（当前规则）

• 仅允许 14:00 后提交运行请求（服务端时区判断）
• 每用户每小时最多 5 次
• end_date 仅支持最近 2 个月窗口，且不能晚于当天
• start_date 不能早于该策略最早可回测日期（与前端一致）
• 参数必须符合该策略允许的参数列表，不支持的参数会被拒绝

6. 常见错误码

• 401 invalid_api_key：Key 无效
• 403 run_time_restricted：不在允许时间窗
• 403 strategy_permission_denied：当前账户未开通该策略权限
• 409 idempotency_conflict：同一个 Idempotency-Key 对应了不同请求参数
• 409 idempotency_pending：同一个 Idempotency-Key 仍在处理中
• 429 hourly_quota_exceeded：当前小时调用次数超限
• 404 job_not_found：任务不存在或无权限查看
• 400 end_date_too_old：结束日期超出最近2个月窗口
• 400 start_date_too_early：开始日期早于该策略最早可回测日期
• 400 unsupported_params：包含策略不支持的参数

7. 幂等使用建议

• 同一业务请求重试：复用同一个 Idempotency-Key
• 参数有变化：必须使用新的 Idempotency-Key
• 不需要幂等：可以不传该请求头

8. 风险提示与合规要求

• 本软件输出的策略结果仅供授权用户内部参考，不构成任何投资建议。
• 严禁将本软件输出结果向他人传播、提供、共享，或进行任何形式的包装转售。
• 若因擅自传播、共享或转售导致的风险、损失或纠纷，本公司不承担任何责任。
• 一经发现将本软件结果信号进行包装转售，本公司将依法追究相关法律责任。
• 策略可能在运行期间持续优化，策略新版本上线后可能出现仓位与历史结果变化；因策略版本更新导致的结果变化及相关风险，本软件不承担任何责任。