API Reference
明爵商户公开 API 的契约、参数、响应和错误结构
公开 API 的参数、响应、认证头和错误结构均来自当前 OpenAPI 契约。页面构建前会自动同步 /contracts/openapi/public/v1/openapi.json，不在 Markdown 中重复维护接口定义。
读取当前商户能力
授权
商户编码
Unix 秒，10 位十进制字符串（如 1790150400）；与服务端相差超过正负 300 秒返回 401 REQUEST_EXPIRED
HMAC-SHA256 的 64 位小写十六进制结果，无前缀；签名串为 X-Timestamp、HTTP 方法、原始请求目标、Idempotency-Key、If-Match 各占一行后接原始 body
响应
商户能力
读取当前商户已授权游戏
目录仅表示授权与当前目录状态；launch_supported 表示当前游戏是否可启动。category 为分类编码，展示名见 category_detail；icon、localizations、provider 提供展示元数据，图标经 /v1/catalog-assets/{asset_id} 下载。游标绑定商户和 status 筛选，24 小时有效。
授权
商户编码
Unix 秒，10 位十进制字符串（如 1790150400）；与服务端相差超过正负 300 秒返回 401 REQUEST_EXPIRED
HMAC-SHA256 的 64 位小写十六进制结果，无前缀；签名串为 X-Timestamp、HTTP 方法、原始请求目标、Idempotency-Key、If-Match 各占一行后接原始 body
参数
查询参数
"AVAILABLE""MAINTENANCE""DISABLED"1100010014096响应
授权游戏页
下载当前商户可见的游戏目录图标
要求 catalog:read scope。仅当图标被当前商户已授权游戏、其多语言项、其厂商或厂商多语言项引用时可见，否则统一 404 RESOURCE_NOT_FOUND；asset_id 须为小写规范 UUID。同一 asset_id 内容不可变：ETag 为带引号的内容 SHA-256 小写十六进制，响应 Cache-Control 固定为 private, max-age=31536000, immutable；If-None-Match 命中返回 304 且无响应体。
授权
商户编码
Unix 秒，10 位十进制字符串（如 1790150400）；与服务端相差超过正负 300 秒返回 401 REQUEST_EXPIRED
HMAC-SHA256 的 64 位小写十六进制结果，无前缀；签名串为 X-Timestamp、HTTP 方法、原始请求目标、Idempotency-Key、If-Match 各占一行后接原始 body
参数
请求头参数
1024路径参数
"uuid"响应
图标原始字节
创建或取得当前商户玩家
同一商户 external_player_id 唯一；已有绑定不会隐式修改 display_name。同一幂等键同内容重放原HTTP状态并返回 Idempotency-Replayed: true。
授权
商户编码
Unix 秒，10 位十进制字符串（如 1790150400）；与服务端相差超过正负 300 秒返回 401 REQUEST_EXPIRED
HMAC-SHA256 的 64 位小写十六进制结果，无前缀；签名串为 X-Timestamp、HTTP 方法、原始请求目标、Idempotency-Key、If-Match 各占一行后接原始 body
写请求业务幂等键，1至128字符并参与签名；Transfer 和 Gift 创建请求必须与 external_id 完全相同；Gift 取消请求也必须携带此头
请求体
响应
玩家绑定已存在
读取当前商户已创建钱包
要求 wallets:read scope。查询不会创建钱包；Transfer 返回平台账本余额，Seamless 仅返回最近可信观察且可能为 null。游标绑定商户和全部筛选条件。nonzero_only 仅允许与 offline_only=true 组合并只查询 Transfer。
授权
商户编码
Unix 秒，10 位十进制字符串（如 1790150400）；与服务端相差超过正负 300 秒返回 401 REQUEST_EXPIRED
HMAC-SHA256 的 64 位小写十六进制结果，无前缀；签名串为 X-Timestamp、HTTP 方法、原始请求目标、Idempotency-Key、If-Match 各占一行后接原始 body
参数
查询参数
"uuid""^[A-Z0-9]{2,16}$"falsefalse1100010014096响应
钱包权威查询页
读取当前商户钱包详情
要求 wallets:read scope。Transfer 读取平台账本；Seamless 必须实时调用商户钱包，无法确认时返回 503，不能以列表观察或余额 0 代替。
授权
商户编码
Unix 秒，10 位十进制字符串（如 1790150400）；与服务端相差超过正负 300 秒返回 401 REQUEST_EXPIRED
HMAC-SHA256 的 64 位小写十六进制结果，无前缀；签名串为 X-Timestamp、HTTP 方法、原始请求目标、Idempotency-Key、If-Match 各占一行后接原始 body
参数
路径参数
"uuid"响应
钱包权威详情
按外部业务 ID 恢复查询交易
要求 transactions:read scope。最多返回当前商户一个权威匹配；无匹配返回空页，不表示可换 external_id 重做原资金请求。
授权
商户编码
Unix 秒，10 位十进制字符串（如 1790150400）；与服务端相差超过正负 300 秒返回 401 REQUEST_EXPIRED
HMAC-SHA256 的 64 位小写十六进制结果，无前缀；签名串为 X-Timestamp、HTTP 方法、原始请求目标、Idempotency-Key、If-Match 各占一行后接原始 body
参数
查询参数
"^[A-Za-z0-9._:-]{1,128}$"响应
零或一项交易结果
按交易 UUID 读取权威交易
要求 transactions:read scope。UNKNOWN 是 200 响应中的业务状态，不等于失败。
授权
商户编码
Unix 秒，10 位十进制字符串（如 1790150400）；与服务端相差超过正负 300 秒返回 401 REQUEST_EXPIRED
HMAC-SHA256 的 64 位小写十六进制结果，无前缀；签名串为 X-Timestamp、HTTP 方法、原始请求目标、Idempotency-Key、If-Match 各占一行后接原始 body
参数
路径参数
"uuid"响应
钱包权威交易
按创建时间窗口快照分页读取注单
要求 records:read scope，每商户限流 2 次/秒（以 capabilities.limits.record_requests/record_seconds 为准）。首次请求必须提供 created_from 与 created_to，半开区间 [created_from, created_to)，窗口大于 0 且不超过 24 小时，时间为 RFC3339 且最多毫秒精度；后续页只允许 cursor 与 limit。首次请求冻结 snapshot_watermark（从未产生注单的商户为 0 且为空页），同一游标链按 (created_at, record_id) 升序且不漏不重；游标绑定商户、筛选条件与水位，自首次签发起 24 小时后返回 410 CURSOR_EXPIRED。快照之后的派奖、退款等修订通过 /v1/record-changes 获取。响应中的时间均为 UTC 固定三位毫秒（如 2026-09-23T08:00:00.000Z）。
授权
商户编码
Unix 秒，10 位十进制字符串（如 1790150400）；与服务端相差超过正负 300 秒返回 401 REQUEST_EXPIRED
HMAC-SHA256 的 64 位小写十六进制结果，无前缀；签名串为 X-Timestamp、HTTP 方法、原始请求目标、Idempotency-Key、If-Match 各占一行后接原始 body
参数
查询参数
首次请求必填，包含
"date-time"首次请求必填，不包含
"date-time""uuid""uuid"11000100续页游标；携带时不得再传筛选参数
4096响应
注单快照页
按持久游标读取注单变更流
要求 records:read scope，与 /v1/records 共享每商户限流。since、from_now=true、cursor 三者必须且只能提供一个。每项是某注单某个 revision 的完整状态，sequence 严格递增；同一注单可能多次出现，接入方按 record_id 保留最大 revision 去重。响应总是返回可持久化的 next_cursor，即使本页为空。变更保留 90 天，起点早于保留期返回 410 CURSOR_EXPIRED；投影副本落后时返回 503。
授权
商户编码
Unix 秒，10 位十进制字符串（如 1790150400）；与服务端相差超过正负 300 秒返回 401 REQUEST_EXPIRED
HMAC-SHA256 的 64 位小写十六进制结果，无前缀；签名串为 X-Timestamp、HTTP 方法、原始请求目标、Idempotency-Key、If-Match 各占一行后接原始 body
参数
查询参数
从该变更时间起读取
"date-time"从当前位置开始，不返回历史变更
409611000100响应
注单变更页
执行 Transfer 钱包入款或出款
仅适用于 Transfer 钱包账户，要求 transfers:write scope。Idempotency-Key 必须与 external_id 完全相同；金额按账户 decimal_scale 精确换算，不舍入。
授权
商户编码
Unix 秒，10 位十进制字符串（如 1790150400）；与服务端相差超过正负 300 秒返回 401 REQUEST_EXPIRED
HMAC-SHA256 的 64 位小写十六进制结果，无前缀；签名串为 X-Timestamp、HTTP 方法、原始请求目标、Idempotency-Key、If-Match 各占一行后接原始 body
写请求业务幂等键，1至128字符并参与签名；Transfer 和 Gift 创建请求必须与 external_id 完全相同；Gift 取消请求也必须携带此头
请求体
响应
Transfer 原子执行成功或同内容重放成功
创建现金活动奖励任务
要求 operations:write scope。Idempotency-Key 必须与 external_id 完全相同；金额按账户 decimal_scale 精确换算，不舍入。QUEUED 或 EXECUTING 返回 202，完成态返回 201。
授权
商户编码
Unix 秒，10 位十进制字符串（如 1790150400）；与服务端相差超过正负 300 秒返回 401 REQUEST_EXPIRED
HMAC-SHA256 的 64 位小写十六进制结果，无前缀；签名串为 X-Timestamp、HTTP 方法、原始请求目标、Idempotency-Key、If-Match 各占一行后接原始 body
写请求业务幂等键，1至128字符并参与签名；Transfer 和 Gift 创建请求必须与 external_id 完全相同；Gift 取消请求也必须携带此头
请求体
响应
现金奖励已进入完成态
读取当前商户现金奖励任务
要求 operations:read scope。任务状态与资金状态独立返回；资金 UNKNOWN 时任务为 EXECUTING 且仅返回 recovery_reason，不返回赠送失败。
授权
商户编码
Unix 秒，10 位十进制字符串（如 1790150400）；与服务端相差超过正负 300 秒返回 401 REQUEST_EXPIRED
HMAC-SHA256 的 64 位小写十六进制结果，无前缀；签名串为 X-Timestamp、HTTP 方法、原始请求目标、Idempotency-Key、If-Match 各占一行后接原始 body
参数
路径参数
"uuid"响应
现金奖励任务
取消尚未派发的现金奖励任务
要求 operations:write scope 和 Idempotency-Key。相同取消请求由 Wallet 权威结果重放，并在 Wallet 标记重放时返回 Idempotency-Replayed: true；仅 QUEUED 且资金 CREATED 的任务可取消，已取得派发资格、UNKNOWN 或完成态返回 409 CANCELLATION_NOT_ALLOWED。
授权
商户编码
Unix 秒，10 位十进制字符串（如 1790150400）；与服务端相差超过正负 300 秒返回 401 REQUEST_EXPIRED
HMAC-SHA256 的 64 位小写十六进制结果，无前缀；签名串为 X-Timestamp、HTTP 方法、原始请求目标、Idempotency-Key、If-Match 各占一行后接原始 body
写请求业务幂等键，1至128字符并参与签名；Transfer 和 Gift 创建请求必须与 external_id 完全相同；Gift 取消请求也必须携带此头
参数
路径参数
"uuid"请求体
响应
取消成功或权威结果重放
分页读取当前商户运营配置
要求 operations:read scope。查询无副作用；没有配置时返回空页，不虚构默认已生效配置。游标绑定商户和全部筛选条件；未知查询参数返回 400 VALIDATION_FAILED，游标无效返回 400 CURSOR_INVALID。
授权
商户编码
Unix 秒，10 位十进制字符串（如 1790150400）；与服务端相差超过正负 300 秒返回 401 REQUEST_EXPIRED
HMAC-SHA256 的 64 位小写十六进制结果，无前缀；签名串为 X-Timestamp、HTTP 方法、原始请求目标、Idempotency-Key、If-Match 各占一行后接原始 body
参数
查询参数
"PLAYER_RTP_POLICY""NEW_PLAYER_POLICY""PLAYER_POLICY""uuid"1100010014096响应
运营配置分页
创建运营配置
要求 operations:write scope 和 Idempotency-Key。只允许 capabilities.operations 中 supported=true 的 kind，target 与 parameters 按 kind 校验；额度按 management 策略原子占用。执行器已确认（ACTIVE）或明确拒绝（FAILED）返回 201，结果未知（PENDING）返回 202。同键同内容重放原 HTTP 状态和 data 并返回 Idempotency-Replayed: true。
授权
商户编码
Unix 秒，10 位十进制字符串（如 1790150400）；与服务端相差超过正负 300 秒返回 401 REQUEST_EXPIRED
HMAC-SHA256 的 64 位小写十六进制结果，无前缀；签名串为 X-Timestamp、HTTP 方法、原始请求目标、Idempotency-Key、If-Match 各占一行后接原始 body
写请求业务幂等键，1至128字符并参与签名；Transfer 和 Gift 创建请求必须与 external_id 完全相同；Gift 取消请求也必须携带此头
请求体
响应
执行器已确认（ACTIVE）或明确拒绝（FAILED）
完整替换运营配置参数
要求 operations:write scope、Idempotency-Key 和 If-Match。parameters 为完整替换，按原配置 kind 校验；If-Match 期望版本纳入幂等摘要，已完成的同键请求先重放，再对新命令比较版本。执行器已确认或明确拒绝返回 200，结果未知（PENDING）返回 202。
授权
商户编码
Unix 秒，10 位十进制字符串（如 1790150400）；与服务端相差超过正负 300 秒返回 401 REQUEST_EXPIRED
HMAC-SHA256 的 64 位小写十六进制结果，无前缀；签名串为 X-Timestamp、HTTP 方法、原始请求目标、Idempotency-Key、If-Match 各占一行后接原始 body
写请求业务幂等键，1至128字符并参与签名；Transfer 和 Gift 创建请求必须与 external_id 完全相同；Gift 取消请求也必须携带此头
参数
请求头参数
期望的配置版本，形如 "3"（带双引号的正十进制整数）；参与签名并纳入幂等摘要，缺少返回 428 PRECONDITION_REQUIRED，格式无效返回 400 VALIDATION_FAILED
"^\"[1-9][0-9]{0,18}\"$"路径参数
"uuid"请求体
响应
执行器已确认或明确拒绝
取消运营配置
要求 operations:write scope、Idempotency-Key 和 If-Match。取消策略不是资金退款，不撤销已产生的资金责任；执行器已确认返回 200 CANCELLED，等待确认返回 202 CANCELLING。已有配置在执行器离线时仍可取消。同键同内容重放原结果并返回 Idempotency-Replayed: true。
授权
商户编码
Unix 秒，10 位十进制字符串（如 1790150400）；与服务端相差超过正负 300 秒返回 401 REQUEST_EXPIRED
HMAC-SHA256 的 64 位小写十六进制结果，无前缀；签名串为 X-Timestamp、HTTP 方法、原始请求目标、Idempotency-Key、If-Match 各占一行后接原始 body
写请求业务幂等键，1至128字符并参与签名；Transfer 和 Gift 创建请求必须与 external_id 完全相同；Gift 取消请求也必须携带此头
参数
请求头参数
期望的配置版本，形如 "3"（带双引号的正十进制整数）；参与签名并纳入幂等摘要，缺少返回 428 PRECONDITION_REQUIRED，格式无效返回 400 VALIDATION_FAILED
"^\"[1-9][0-9]{0,18}\"$"路径参数
"uuid"请求体
响应
取消已确认（CANCELLED）
签发游戏启动票据
创建一次性、短期的游戏启动票据。同一 Idempotency-Key 同内容重放原结果；过期启动需要使用新幂等键重新签发。
授权
商户编码
Unix 秒，10 位十进制字符串（如 1790150400）；与服务端相差超过正负 300 秒返回 401 REQUEST_EXPIRED
HMAC-SHA256 的 64 位小写十六进制结果，无前缀；签名串为 X-Timestamp、HTTP 方法、原始请求目标、Idempotency-Key、If-Match 各占一行后接原始 body
写请求业务幂等键，1至128字符并参与签名；Transfer 和 Gift 创建请求必须与 external_id 完全相同；Gift 取消请求也必须携带此头
请求体
响应
启动票据签发成功
最后更新于 13小时前