王者荣耀名片修改文档

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

本文件专门说明王者荣耀主页名片订单的图片提交、扫码授权、状态查询、反馈图和重提。图库和海报素材见 王者荣耀主页名片海报文档。

1. 认证与产品

代理接口必须携带：

X-API-Key: API_xxxxxxxxxxx

创建订单、创建入口和补发订单还要携带唯一 Idempotency-Key。接口成功响应为 HTTP 200 且 code=0，request_id 同时位于响应头和 JSON body。

主页名片是实时业务，不套用普通王者微信周一出码规则，但仍必须以扫码能力字段为准。

2. 创建名片订单

POST https://zhanqudingwei.com/api/v1/open/orders
X-API-Key: API_xxxxxxxxxxx
Idempotency-Key: namecard-20261001-0001
Content-Type: multipart/form-data

表单只能出现以下四个字段，每个字段只能出现一次：

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。

3. 先生成卡券入口

如果需要让用户在卡券服务内自己上传或从图库选择图片，先生成入口：

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

{ "product_type": "namecard" }

返回的 public_path 为 /y?=<code>。生成入口时不访问上游、不扣点；用户提交图片后才创建上游订单。

4. 选择图库或用户图片

公共名片图库：

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

列表项中的 id 是创建订单使用的 gallery_image_id，sequence_no 只是展示编号。图库图片和用户上传图片都必须在本站完成裁剪，最终输出 1280×720 JPEG。

当前 Open API 没有公开“只改系统/只改图片”的单独重选 HTTP 路径。需要更换图片时，通过本站卡券服务页面完成；第三方只根据返回的 can_reselect 判断能力，不要调用未公开的内部接口。

5. 扫码授权

先查状态：

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

当 can_start_scan=true 时主动调用一次：

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

二维码生成、等待扫码和确认阶段约每 2 秒读取状态；已有 queued、starting、waiting 或 confirming 任务时不要重复 POST，否则通常返回 409。二维码过期且 can_refresh_scan=true 时才使用 ?force=true。

6. 状态、轮询和反馈图

status_text 和 message 只用于展示，程序必须使用 status、scan.status、can_rescan、can_resubmit 等字段。processing 前 5 分钟建议每 5 秒读取一次，超过 5 分钟每 15 秒读取一次；authorized 约每 15 秒读取一次。

名片状态响应可包含 namecard_image_source：gallery 表示本次提交选择了图库图片，user_upload 表示本次提交使用了用户图片。只有 namecard_image_source=gallery 时，namecard_gallery_sequence 才表示本次所选图片的展示编号；业务判断必须使用来源字段，不要根据编号是否存在反推来源。来源字段只表示本次提交方式，不代表图片的存储、展示或其他内部处理方式。

处理中示例：

{
  "code": 0,
  "data": {
    "code": "YMACW415",
    "product_type": "namecard",
    "status": "processing",
    "status_text": "修改中",
    "message": "设备已领取订单，正在修改。请勿登录游戏或重复授权。",
    "scan": { "status": "done", "expires_in": 0, "message": "扫码成功" }
  },
  "request_id": "req_1788280200_4fae617d31ad"
}

success 或 failed 终态才返回 result_image_url；地址走本站结果图代理。终态后停止订单和队列轮询，不要直接访问上游反馈图。

7. 订单详情与重提

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

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

只有详情返回 can_resubmit=true 时才重提；该写接口没有文档级幂等承诺，不能并发重复提交。结果待确认时继续查询原订单，不要换新的外部订单号制造第二笔订单。

8. 图片和安全要求

• 不接受非 JPEG 内容、超过 8 MiB 或不是 1280×720 的图片。
• 只使用本站 result_image_url，不要把上游 URL、Token 或 Cookie 返回给用户。
• 不要在日志中记录图片内容、二维码、API Secret 或用户授权信息。
• 收到 success 或 failed 后停止轮询；需要重新处理时以 can_resubmit、can_rescan、can_reselect 为准。