王者荣耀主页名片海报文档

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

本文件说明王者荣耀主页名片和元流海报的图库、卡券入口、素材选择和订单创建。

1. 接口认证与通用规则

公共图库不需要 API Key；创建卡券和订单必须携带：

X-API-Key: API_xxxxxxxxxxx
Idempotency-Key: request-20261001-0001

Idempotency-Key 仅用于卡券链接、创建订单和补发订单，长度 8-128 个可打印 ASCII 字符。相同 API Key、相同幂等键和相同请求内容重试会复用原结果；同键不同内容返回 409。成功响应的业务码为 0，响应头和响应体都会带 request_id。

2. 产品与入口

`product_type`	产品	用户入口
`namecard`	王者荣耀主页名片	`/y?=<卡券编号>`
`poster`	王者荣耀元流海报	`/q?=<卡券编号>`

3. 公共图库

GET https://zhanqudingwei.com/api/v1/public/gallery?category=namecard&page=1&page_size=12
GET https://zhanqudingwei.com/api/v1/public/gallery?category=yuanliu_poster&page=1&page_size=12
GET https://zhanqudingwei.com/api/v1/public/gallery?category=yuanliu_poster&sequence_no=32
GET https://zhanqudingwei.com/api/v1/public/gallery/namecard-categories

主页名片可以关联多个分类，按分类查询：

GET https://zhanqudingwei.com/api/v1/public/gallery?category=namecard&namecard_category_id=1&page=1&page_size=12

列表项：

字段	说明
`id`	数据库图片 ID，创建订单传 `gallery_image_id`
`category`	`namecard` 或 `yuanliu_poster`
`sequence_no`	对外展示编号，只用于展示和搜索
`thumbnail_url`	列表缩略图
`content_url` / `public_url`	原图
`mime_type`、`width`、`height`	图片信息
`categories`	名片的全部分类，海报返回空数组

列表使用缩略图，查看大图使用原图：

GET https://zhanqudingwei.com/api/v1/public/gallery/namecard/32/thumbnail
GET https://zhanqudingwei.com/api/v1/public/gallery/namecard/32/content

海报只能使用系统启用的图库素材，不接受第三方用户上传海报。名片支持从图库选择或提交用户图片，具体处理结果以订单状态接口为准。

4. 只生成卡券服务入口

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

主页名片：

{ "product_type": "namecard" }

元流海报：

{ "product_type": "poster" }

接口返回 public_path，分别为 /y?=<code> 和 /q?=<code>。生成入口时不创建上游订单、不扣点；用户在卡券服务提交后才创建上游订单。

5. 创建主页名片订单

名片订单只能使用 multipart/form-data，只能出现以下四个表单键，每个键恰好一次：

字段	类型	约束
`product_type`	text	固定为 `namecard`
`external_order_no`	text	当前 API 客户端内唯一
`game_area`	text integer	`1=苹果微信`、`2=苹果QQ`、`3=安卓微信`、`4=安卓QQ`
`image`	file	JPEG 内容，精确 `1280×720`，不超过 `8 MiB`

curl -X POST "https://zhanqudingwei.com/api/v1/open/orders" \
  -H "X-API-Key: API_xxxxxxxxxxx" \
  -H "Idempotency-Key: namecard-20261001-0001" \
  -F "product_type=namecard" \
  -F "external_order_no=merchant-20261001-0001" \
  -F "game_area=4" \
  -F "image=@namecard.jpeg;type=image/jpeg"

服务端按图片内容校验，不按扩展名判断；只满足 16:9 但不是 1280×720 的图片会被拒绝。卡券服务和代理上传后也会先裁剪并转换为合规 JPEG。

6. 创建元流海报订单

先从公共图库取得 category=yuanliu_poster 的列表，使用列表项中的数据库 id：

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

{
  "product_type": "poster",
  "external_order_no": "merchant-20261001-0002",
  "game_area": 4,
  "gallery_image_id": 32,
  "poster_scheme": 1
}

gallery_image_id 必须指向已启用、类别为 yuanliu_poster 且配置了上游素材 ID 的记录；sequence_no 不能代替 id。poster_scheme 为 1-5。海报订单不要上传文件，不要传地区字段。

7. 名片图库选择与结果

按卡券获取可选的名片图库：

GET https://zhanqudingwei.com/api/v1/public/cards/:code/gallery/namecard?namecard_category_id=1&page=1&page_size=10

该接口不需要 API Key，但 :code 必须是有效卡券编号。订单状态使用：

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

二维码使用 POST /api/v1/open/orders/:code/scan，成功或失败后停止轮询。只有 success 或 failed 终态才返回 result_image_url，结果图走本站地址，不要直接展示上游地址。