王者荣耀战区修改文档

文档更新日期：2026-10-01
接口版本：v1
站点地址：https://zhanqudingwei.com/

本文件说明 product_type=warzone 的王者荣耀战区修改。王者荣耀与和平精英的地区目录、游戏 ID 和订单参数完全分开。

1. 认证、响应和错误

代理接口必须携带：

X-API-Key: API_xxxxxxxxxxx

创建订单、创建卡券链接和补发订单还必须带 Idempotency-Key。成功响应为 HTTP 200 且 code=0；响应头 X-Request-ID 和 JSON request_id 用于排查。

主要错误：40001 参数错误，40101 API Key 无效，40301 客户端/IP/代理停用，40401 订单不属于当前 API Key，40901 幂等冲突或订单状态冲突，40902 可用点数不足，42901 频率限制，50201 上游错误。

2. 区服与地区

`game_area`	区服
`1`	苹果微信
`2`	苹果 QQ
`3`	安卓微信
`4`	安卓 QQ

地区必须来自王者目录：

GET https://zhanqudingwei.com/api/v1/public/games/1/district/tree
GET https://zhanqudingwei.com/api/v1/public/games/1/district/search?q=深圳南山&limit=20

搜索参数 q 与 keyword 二选一，limit 为 1-100，默认 30。创建时使用完整的省、市、区、经纬度和 location_addr，且地址必须严格等于 province/city/district。

3. 创建订单

POST https://zhanqudingwei.com/api/v1/open/orders
X-API-Key: API_xxxxxxxxxxx
Idempotency-Key: warzone-20261001-0001
Content-Type: application/json

{
  "product_type": "warzone",
  "external_order_no": "merchant-20261001-0001",
  "game_area": 4,
  "province": "黑龙江省",
  "city": "大兴安岭",
  "district": "加格达奇区",
  "longitude": 124.12,
  "latitude": 50.42,
  "location_addr": "黑龙江省/大兴安岭/加格达奇区"
}

product_type 固定为 warzone；external_order_no 在当前 API 客户端内唯一；game_area 为 1-4；省、市、区各为 1-64 个非控制字符；经度范围 -180..180，纬度范围 -90..90。请求体上限 4 KiB。

不要传 realtime、gallery_image_id、poster_scheme 或和平精英字段。Open API 当前不接受通过创建请求直接转实时。

只生成用户入口而暂不创建上游订单时，调用 /api/v1/open/card-links，传 { "product_type": "warzone" }，返回入口 /x?=<code>。

4. QQ/微信扫码规则

QQ 区（`2`、`4`）

QQ 可以任意日期扫码，扫码轮询与修改轮询分开。
扫码成功只代表授权完成；非周一不开始修改战区，只保存预约/排队快照。
非周一授权订单不访问上游修改执行状态；进入周一修改窗口后，排队阶段约每 15 秒同步。
设备领取并进入 processing 后，前 5 分钟约每 5 秒同步，超过 5 分钟自动降为约 15 秒。

微信区（`1`、`3`）

普通订单的上游二维码窗口是中国时间周一 01:30-23:55；本站页面使用 01:30-23:50 的保守窗口。
非窗口时间不创建二维码，返回 appointment_at；到窗口后再次读取状态，确认 can_start_scan=true 才取码。

已转实时订单不套用普通窗口，以响应中的 scan_required、订单状态和能力字段为准。

5. 扫码与状态

先读取订单状态：

GET https://zhanqudingwei.com/api/v1/open/orders/:code/status
X-API-Key: API_xxxxxxxxxxx

允许时主动创建扫码任务：

POST https://zhanqudingwei.com/api/v1/open/orders/:code/scan
X-API-Key: API_xxxxxxxxxxx

二维码过期且 can_refresh_scan=true 时才允许：

POST https://zhanqudingwei.com/api/v1/open/orders/:code/scan?force=true

扫码任务生成、等待扫码和确认阶段约每 2 秒读取状态；不要重复 POST 正在进行的扫码任务。scan.expires_in 单位是秒。用户不点击取码时，系统不会自动创建二维码。

关键能力字段：can_start_scan、can_refresh_scan、can_rescan、can_reselect。能力字段用于判断动作，不是订单状态。

6. 订单状态、队列与结果

`status`	文案	含义
`waiting_scan`	使用未授权	等待扫码
`authorized`	已授权	已扫码，等待排队或设备领取
`processing`	修改中	本站确认设备已经领取
`success`	修改成功	终态
`failed`	修改失败	终态

上游 status=2 不能直接等同于本站 processing。只有本站确认设备领取后才进入 processing。订单状态中的 queue 包含 state、ahead、total、available、checked_at；缺省或 available=false 表示未知，不能当作 0。

建议第三方按以下节奏读取本站状态：授权排队 15 秒，processing 前 5 分钟 5 秒，之后 15 秒；成功/失败后停止。当前没有独立的全站排队 Open API。

7. 订单列表、详情和重提

GET https://zhanqudingwei.com/api/v1/open/orders?page=1&page_size=20
GET https://zhanqudingwei.com/api/v1/open/orders/:code
POST https://zhanqudingwei.com/api/v1/open/orders/:code/resubmit
X-API-Key: API_xxxxxxxxxxx

列表按当前 agent_id + api_client_id 隔离；详情、扫码、状态和重提只能访问当前 API Key 创建的订单。重提前检查 can_resubmit=true，该接口没有文档级幂等承诺，不能并发重复提交。成功或失败后的 result_image_url 使用本站地址。