YGAPI 接口文档

当前在线调试环境 Sandbox

Sandbox APIhttps://openapi-test.yibo-api.com

Production APIhttps://api.yibo-api.com

Production 在线执行已关闭

Sandbox 资金操作Dry-run，不产生真实余额变化

公共 Demo仅限 System / Meta 只读接口

业务联调请使用分配的专用 Sandbox Merchant 和 Secret

YG OpenAPI v1

快速完成 YG OpenAPI 首次联调

先按业务流程跑通会员、钱包、游戏、注单和回调，再回看签名、Nonce、基础数据同步等高级规则。游戏、厂商、币种、语言和维护状态全部通过接口动态返回。

生产 API 地址https://api.yibo-api.com

测试环境Sandbox / 非生产环境

请求协议HTTPS + JSON

Content-Typeapplication/json; charset=UTF-8

字符编码UTF-8

签名方式HMAC-SHA256

当前版本OpenAPI v1

测试资料公共只读 Demo 已自动配置；业务联调需申请专用凭据

Quick Start

快速接入

接口优先

获取测试 Merchant ID 和 Signing Key只使用测试资料，生产密钥不得输入文档站。
获取基础数据和游戏列表游戏、厂商、币种、语言和维护状态不写死。
创建会员会员首次进入游戏平台前创建或复用映射。
查询会员余额用于联调和对账，金额按字符串小数处理。
钱包上分或下分测试环境只做 dry-run / sandbox。
获取游戏登录地址进入游戏前检查维护状态。
查询订单和注单资金先查单，注单按窗口分页拉取。
配置并验证回调回调由 YG 主动请求下游地址，必须验签和幂等。

首次联调

1. 获取测试资料 2. 调系统时间 3. 完成签名测试 4. 创建测试会员 5. 查询余额 6. 获取游戏地址

接口通用规则

项目	说明	下游处理建议
请求地址	Sandbox 固定为 `https://openapi-test.yibo-api.com`；Production 仅展示，文档站不可在线执行。	SDK 导入本 Spec 时默认使用 Sandbox；生产地址只能在下游服务端显式配置。
请求方式	按接口定义使用 GET 或 POST。	GET 参数放 Query / Path，通常无 Body；POST / PUT / PATCH 使用 JSON Body。
Content-Type	请求体统一使用 `application/json; charset=UTF-8`，响应同样为 JSON UTF-8。	签名前后不得改变实际发送的 Raw Body。
Body SHA256	有 Body 时对实际发送的 UTF-8 原始字节计算 SHA256；空 Body 使用空字节 SHA256。	JSON 字段顺序会影响签名，因为服务端校验的是原始请求体字节。
Query 规范化	服务端按 UTF-8 解码 Query 参数，按参数名、再按同名参数值排序；排除 `sign`，以原始解码值拼成 `key=value&key=value`。	发送 URL 时仍需按 RFC 3986 编码；当前参数值不得包含会造成歧义的 `&` 或 `=`。无 Query 时签名第三行为空行。
请求头	签名接口必须携带商户号、时间戳、随机串和签名。	签名必须由商户服务端或安全签名组件生成。
业务结果	HTTP 200 也可能业务失败。	先看 HTTP 状态，再以响应 `code` 判断业务结果。
动态枚举	基础数据接口在 OpenAPI 内部归类为 Meta 接口。	不要写死游戏、厂商、币种、语言和维护状态。

API Reference

业务接口

加载中

接口文档

请选择左侧接口查看业务场景、参数、示例和错误码。

时间戳、Nonce 与幂等

Timestamp毫秒时间戳。服务端用于判断请求是否过期，防止旧请求被重放。

Nonce一次性随机字符串。同一商户在有效窗口内重复使用会被拒绝。

Idempotency幂等控制，防止重复提交。资金接口以 orderNo 作为幂等键。

Canonical String签名原文。由方法、路径、Query、Body Hash、时间戳、Nonce 和商户号组成。

Security

签名规则

下沉规则区

签名请求头

Header	说明
`X-YG-Merchant-Id`	测试或正式商户号。
`X-YG-Timestamp`	毫秒时间戳，过期拒绝。
`X-YG-Nonce`	一次性随机字符串，重复拒绝。
`X-YG-Sign`	HMAC-SHA256 十六进制签名。
`X-YG-Sign-Version`	当前固定为 `V1`。

固定测试向量

Method: POST
Path: /openapi/v1/players
Query 原始值: (空)
Query 排序后: (空)
Raw Body: {"memberId":"YG_TEST_PLAYER","currency":"CNY"}
Body SHA256: 6c29ddf983122d0126f322dc8dae285a254d31020cadb2e157fe1e4c5c7c2889
Merchant ID: YG_TEST_MERCHANT
Timestamp: 1735689600000
Nonce: 550e8400-e29b-41d4-a716-446655440000
Sign Version: V1
Test Signing Key: YG_DOC_TEST_KEY_ONLY
Canonical String:
POST
/openapi/v1/players

6c29ddf983122d0126f322dc8dae285a254d31020cadb2e157fe1e4c5c7c2889
1735689600000
550e8400-e29b-41d4-a716-446655440000
YG_TEST_MERCHANT
HMAC-SHA256: 7520bd5e0056bb727356ba5bd03e0489936b8e897da9298f31e79526d688aa97
Final Sign: 7520bd5e0056bb727356ba5bd03e0489936b8e897da9298f31e79526d688aa97

最终 Header 与 cURL

X-YG-Merchant-Id: YG_TEST_MERCHANT
X-YG-Timestamp: 1735689600000
X-YG-Nonce: 550e8400-e29b-41d4-a716-446655440000
X-YG-Sign: 7520bd5e0056bb727356ba5bd03e0489936b8e897da9298f31e79526d688aa97
X-YG-Sign-Version: V1
Content-Type: application/json; charset=UTF-8

curl --request POST 'https://openapi-test.yibo-api.com/openapi/v1/players' \
  --header 'Content-Type: application/json; charset=UTF-8' \
  --header 'X-YG-Merchant-Id: YG_TEST_MERCHANT' \
  --header 'X-YG-Timestamp: 1735689600000' \
  --header 'X-YG-Nonce: 550e8400-e29b-41d4-a716-446655440000' \
  --header 'X-YG-Sign: 7520bd5e0056bb727356ba5bd03e0489936b8e897da9298f31e79526d688aa97' \
  --header 'X-YG-Sign-Version: V1' \
  --data-raw '{"memberId":"YG_TEST_PLAYER","currency":"CNY"}'

固定向量用于本地断言签名实现；其中时间戳已过期，cURL 仅用于核对请求结构，不能作为实时调用。真实 Sandbox 请求必须使用当前毫秒时间戳和全新 nonce。公共 Demo Key 是仅限 System / Meta 只读范围的公开测试资料；专用测试 Key 只在当前页面内存参与签名，刷新或离开页面后清除。生产 Signing Key 永不进入文档站。

Errors

错误码

当前后端除关闭/不存在使用 HTTP 404、限流使用 HTTP 429 外，多数校验和业务失败仍返回 HTTP 200 + 非 0 code。HTTP 400/401/403/409/500 仅为规划中的传输层映射，不得视为当前已支持。客户端必须同时检查 HTTP Status 与 response.code；资金接口超时后必须先查单，不能盲目换单号重复提交。

回调接口

回调方向为：YG 平台主动请求下游提供的 callback URL。当前文档中的回调接口为示例 / Stub / Dry-run 说明，用于下游实现验签、幂等和成功响应格式。

主题	规则
配置方式	下游在商户配置中提供 HTTPS callback URL，正式启用前由 YG 审核。
请求方式	POST JSON，携带与普通请求一致的签名头。
超时与重试	待后端回调策略正式确认；未确认前不得把最大重试次数、间隔或总周期写成固定值。
幂等处理	以下游收到的 `eventId` 或唯一业务编号做幂等键，重复回调只处理一次。
成功响应	返回 HTTP 200 且业务成功结构，例如 `{"code":0,"message":"success"}`。
排查建议	记录 requestId、eventId、HTTP 状态和业务 code，日志必须脱敏 sign、token 和 secret。

Sandbox Only

在线调试

测试环境

Try it out 仅用于 Sandbox。公共 Demo 凭据已自动加载，只能执行系统时间和动态 Meta 只读接口；会员、钱包、登录 URL、注单等业务接口需要专用测试凭据。禁止输入生产 Secret。

API Base URL Merchant ID Signing Key（公共演示）

公共 Demo 账号已自动加载，可直接执行只读 Meta 接口；刷新后自动恢复。

响应

未执行

{}

请求示例

核心接口在右侧接口详情中提供 cURL、请求 JSON、成功响应和常见失败示例。金额字段一律使用字符串小数，例如 "amount":"10.00"。

代码示例

以下示例先用固定测试向量断言本地签名结果，再用同一创建会员接口发起 Sandbox 请求。真实请求必须使用当前毫秒时间戳和全新 nonce；示例 Signing Key 仅为公开测试密钥。

PHP 完整示例

加载中

JavaScript / Node.js

加载中

Python

加载中

Java

加载中

字段字典与取值规则

基础数据接口在 OpenAPI 内部归类为 Meta 接口。动态枚举必须以接口实时返回为准，表格只描述字段含义、使用边界和下游处理规则。

字段	适用接口	取值来源 / 规则	下游处理要求
`vendorCode`	游戏列表、厂商列表	来自 `/openapi/v1/meta/vendors`	作为厂商唯一代码使用，不要用厂商名称做主键。
`gameCode`	游戏列表、登录 URL	来自 `/openapi/v1/meta/games`	请求登录 URL 前确认游戏未下架且未维护。
`currency`	会员、钱包、游戏登录	来自 `/openapi/v1/meta/currencies`	会员币种、钱包币种和游戏支持币种需保持一致。
`language`	游戏列表、登录 URL	来自 `/openapi/v1/meta/languages`	不支持目标语言时，下游应回退默认语言或提示不可用。
`status`	基础数据、会员、订单、注单	接口实时返回，可能随后台配置扩展	未知状态按不可用或人工确认处理，不能默认视为成功。
`memberId`	会员、钱包、登录 URL	下游会员唯一 ID	同一商户内不可复用；大小写必须一致。
`orderNo`	上分、下分、订单查询	下游生成的资金订单号	同一商户内全局唯一；超时后先查单。
`amount`	上分、下分、注单	字符串小数	使用 decimal 处理，禁止用浮点数直接计算资金。
`eventId`	回调	平台推送事件唯一号	以 eventId 做幂等；重复回调只处理一次。

Sandbox 与 Production 差异

项目	Sandbox / Dry-run	Production
Base URL	`https://openapi-test.yibo-api.com`，也是 Spec 默认 Server。	`https://api.yibo-api.com`，仅展示和供下游服务端显式配置；文档站在线执行关闭。
接口路径	使用同一套 `/openapi/v1/**` 契约。	保持兼容；新增字段向后兼容，删除字段走废弃周期。
签名算法	HMAC-SHA256，推荐 `X-YG-Sign-Version: V1`。	同算法；生产 Secret 只能在下游服务端安全保存。
Merchant 类型	测试商户，测试 Signing Key，测试 IP / Origin 白名单。	正式商户，正式密钥，严格业务权限与 IP 白名单。
资金变化	上分 / 下分为 Stub / Dry-run，不修改真实余额。	禁止通过文档站做真实资金调试。
厂商调用	不调用真实游戏厂商；登录 URL 和注单用于联调契约。	是否调用真实厂商以正式后端能力和商户权限为准。
数据隔离	测试数据独立，不代表生产配置、账务或注单。	生产数据独立，需按正式审计和日志规则处理。

上线交付边界

独立部署文档站部署到独立域名，不代理后台管理接口。

默认安全生产配置默认关闭 Try it out，并启用鉴权和 IP 白名单。

测试联调在线调试只指向真实配置的测试 API Base URL 和测试商户。

密钥隔离静态文件不包含真实 secret、token、厂商密钥或商户密钥。

更新日志

v1：发布会员、钱包、游戏、基础数据、注单、回调和签名测试向量。
新增字段必须向后兼容；删除字段必须先进入废弃周期。