和平精英战区修改文档

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

本文件说明 product_type=peace_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 订单不存在或不属于当前 Key，40901 幂等或订单状态冲突，40902 可用点数不足，42901 频率限制，50201 上游错误。

2. 业务参数与入口

项目	值
`product_type`	`peace_warzone`
`game_id`	固定为 `2`
用户入口	`/h?=<卡券编号>`
地区接口	`/api/v1/public/games/2/district/*`

和平精英不保留王者荣耀战区的旧卡券兼容，不接受省略模式后自动按 classic 处理。卡券服务页面使用四步流程：选择系统 -> 选择模式 -> 选择地区 -> 扫码授权。

3. 模式

`pubgm_mode`	中文名称
`classic`	经典模式
`metro`	地铁模式
`tomb`	古墓模式
`oasis`	绿洲模式
`arena`	赛场模式

4. 独立地区接口

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

q 和 keyword 二选一，limit 范围 1-100，默认 30。地区记录包含 id、game_id=2、source_id、province、city、district、longitude、latitude、platform、location_addr 和 location。

创建时必须使用同一条和平地区记录的 district_id 与 district_source_id。district_platform 只允许 any、ios、android，并需与地区记录和区服匹配。王者荣耀地区 ID、source_id 和坐标不能传入本业务。

5. 创建订单

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

{
  "product_type": "peace_warzone",
  "external_order_no": "merchant-20261001-0001",
  "game_id": 2,
  "game_area": 4,
  "pubgm_mode": "classic",
  "district_id": 4200,
  "district_source_id": "1698242647633182720",
  "district_platform": "any",
  "province": "广东省",
  "city": "深圳市",
  "district": "南山区",
  "location_addr": "广东省/深圳市/南山区",
  "longitude": 113.923552,
  "latitude": 22.528499
}

字段约束：

字段	必填	说明
`product_type`	是	固定为 `peace_warzone`
`external_order_no`	是	当前 API 客户端内唯一
`game_id`	是	固定为 `2`
`game_area`	是	`1=苹果微信`、`2=苹果QQ`、`3=安卓微信`、`4=安卓QQ`
`pubgm_mode`	是	`classic`、`metro`、`tomb`、`oasis`、`arena`
`district_id`	是	必须来自 `game_id=2` 的地区目录
`district_source_id`	是	与和平地区记录对应的字符串 ID
`district_platform`	否	`any`、`ios`、`android`，按地区和区服匹配
位置字段	条件必填	省、市、区、地址、经纬度要么全部省略，要么全部传入

如果传入位置组，location_addr 必须严格等于 province/city/district；经度范围 -180..180，纬度范围 -90..90。服务端内部会映射上游 product_type=warzone，但始终保留 game_id=2 和和平地区身份。

只生成入口而不创建订单：

POST https://zhanqudingwei.com/api/v1/open/card-links
X-API-Key: API_xxxxxxxxxxx
Idempotency-Key: peace-link-20261001-0001
Content-Type: application/json

{ "product_type": "peace_warzone" }

返回 public_path=/h?=<code>，不访问上游、不创建订单、不扣点。

6. 扫码授权与轮询

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_start_scan=true 时才主动 POST 扫码；二维码生成、等待扫码和确认阶段约每 2 秒读取状态。scan.expires_in 单位为秒，已有扫码任务时不要重复 POST。

和平精英不套用王者荣耀周一出码规则。扫码成功后请退出游戏并保持游戏角色离线；已授权排队阶段约每 15 秒读取，确认设备进入 processing 后前 5 分钟约每 5 秒，超过 5 分钟自动降为约 15 秒。

7. 状态、结果和重提

`status`	`status_text`	含义
`waiting_scan`	使用未授权	等待扫码
`authorized`	已授权	等待排队或设备领取
`processing`	修改中	设备已经领取并正在处理
`success`	修改成功	终态
`failed`	修改失败	终态

上游 status=2 不能直接显示为本站 processing。结果成功或失败后停止轮询，使用本站返回的 result_image_url。

允许时可重提：

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

调用前检查 can_resubmit=true，不能并发重复提交。创建或详情返回的 game_id、pubgm_mode、district_id、district_source_id 和 game_area 应与请求一致；上游稀疏响应未回显的可选字段由本站保留，不要自行判定失败。