mojiahui/dafuweng-saiadmin6.x

Fork 0

Files

zhenhui 90ba5b0068 新增Dicey Fun 第三方接入英文文档

2026-05-08 18:13:53 +08:00

13 KiB

Raw Blame History

Dicey Fun 第三方接入文档（基于现有项目接口）

1. 基础信息

provider: Dicey Fun
provider_code: DF
game_type: slot
game_list: ["dafuwen"]
provider_logo: ``
获取大厅地址: https://dice-v3-lobby.h55555game.top
后台管理地址: https://dice-v3.h55555game.top/
agent_token: [后台菜单查看：系统管理-用户管理-代理ID]
agent_id: 5ef059938ba799aaa845e1c2e8a762bd

2. 接口域名与协议

协议: HTTP/HTTPS（建议生产使用 HTTPS）
Base URL: https://{your-domain}（由部署方提供）
数据格式: application/json
字符编码: UTF-8

2.1 调用规范（建议第三方按此统一实现）

/api/v1/authToken 使用 GET + Query 参数
其他 /api/v1/* 接口使用 POST + JSON Body（本项目路由为 Route::any，但建议第三方统一按 POST 接入）
请求头统一：
- Content-Type: application/json
- Accept: application/json
- auth-token: {authtoken}（除 /api/v1/authToken 外必传）
时间相关参数统一使用 Unix 时间戳（秒）
建议所有请求设置超时：连接超时 3s，读取超时 10s
生产环境建议增加调用方 IP 白名单和重试退避机制（避免瞬时重试风暴）

3. 通用返回格式

所有接口统一返回：

{
  "code": 200,
  "message": "success",
  "data": {}
}

说明：

code=200 表示成功
失败时通常返回：400/401/402/403/404/422/500

常见错误码：

400 参数错误
401 未携带 token
402 token 无效或过期
403 签名或鉴权失败
404 资源不存在
422 业务错误（如余额不足）
500 服务端异常

4. 鉴权流程（平台级）

/api/v1/* 接口调用前，先获取 auth-token。

4.1 获取 auth-token

路径: GET /api/v1/authToken
鉴权参数（Query）：
- agent_id：代理标识（商户标识）
- secret：双方约定密钥
- time：Unix 时间戳（秒）
- signature：签名

签名规则：

signature = md5(agent_id + secret + time)

签名示例（原串与结果）：

agent_id = 9f86d081884c7d659a2feaa0c55ad015
secret   = xF75oK91TQj13s0UmNIr1NBWMWGfflNO
time     = 1713753600
sign_src = 9f86d081884c7d659a2feaa0c55ad015xF75oK91TQj13s0UmNIr1NBWMWGfflNO1713753600
signature= md5(sign_src)

PHP 生成签名示例：

$agentId = '9f86d081884c7d659a2feaa0c55ad015';
$secret = 'xF75oK91TQj13s0UmNIr1NBWMWGfflNO';
$time = (string) time();
$signature = md5($agentId . $secret . $time);

JavaScript 生成签名示例（Node.js）：

const crypto = require('crypto');

const agentId = '9f86d081884c7d659a2feaa0c55ad015';
const secret = 'xF75oK91TQj13s0UmNIr1NBWMWGfflNO';
const time = Math.floor(Date.now() / 1000).toString();
const signature = crypto.createHash('md5').update(agentId + secret + time).digest('hex');

服务端校验逻辑（关键点）：

agent_id/secret/time/signature 任一缺失即失败（400）
secret 不匹配即失败（403）
time 超出容差窗口即失败（403，默认容差 300s）
signature 校验失败即失败（403）
校验通过后颁发 authtoken，后续请求必须放在 Header auth-token

防重放与时间同步建议：

调用方服务器必须启用 NTP 时间同步
time 使用发起请求时的当前秒级时间戳，不要复用旧值
遇到 “Timestamp expired or invalid” 时优先检查服务器时间偏差

成功返回示例：

{
  "code": 200,
  "message": "success",
  "data": {
    "authtoken": "xxx.yyy.zzz"
  }
}

后续调用 /api/v1/* 时，请在 Header 携带：

auth-token: {authtoken}

4.2 完整调用链（推荐）

计算 signature = md5(agent_id + secret + time)
调用 GET /api/v1/authToken 获取 authtoken
在 Header 添加 auth-token: {authtoken}
调用业务接口（如 getPlayerInfo、setPlayerWallet、getGameUrl）
若返回 402，重新获取 authtoken 后重试一次

5. 游戏相关接口

以下接口均需 Header: auth-token。

5.1 获取游戏列表（已支持）

路径: POST /api/v1/getGameList
Header:
- auth-token: {authtoken}
Body 参数：
- lang（可选）：zh/en，默认 zh
返回说明：
- 从 dice_game 表读取启用状态（status=1）的游戏
- 当前默认仅返回一个游戏：dafuwen
- 按 lang 返回中英文 game_name
- 已做字段脱敏：不会返回敏感配置（如 sensitive_config_json）

返回字段（data.game_list[]）：

provider：供应商名称
provider_code：供应商编码
game_code：游戏编号
game_key：游戏唯一值
game_type：游戏类型
logo：游戏 Logo 地址
game_url：游戏地址
hall_url：大厅地址
status：状态（1 启用）
sort：排序值
game_name：游戏名称（跟随 lang 返回中文或英文）

成功返回示例（lang=zh）：

{
  "code": 200,
  "message": "success",
  "data": {
    "game_list": [
      {
        "provider": "Dicey Fun",
        "provider_code": "DF",
        "game_code": "dafuwen",
        "game_key": "dafuwen",
        "game_type": "slot",
        "logo": "",
        "game_url": "https://dice-v3-game.h55555game.top/",
        "hall_url": "https://dice-v3-game.h55555game.top/",
        "status": 1,
        "sort": 1,
        "game_name": "大富翁"
      }
    ]
  }
}

成功返回示例（lang=en）：

{
  "code": 200,
  "message": "success",
  "data": {
    "game_list": [
      {
        "provider": "Dicey Fun",
        "provider_code": "DF",
        "game_code": "dafuwen",
        "game_key": "dafuwen",
        "game_type": "slot",
        "logo": "",
        "game_url": "https://dice-v3-game.h55555game.top/",
        "hall_url": "https://dice-v3-game.h55555game.top/",
        "status": 1,
        "sort": 1,
        "game_name": "Dafuweng"
      }
    ]
  }
}

5.2 获取游戏大厅信息（已支持，脱敏）

路径: POST /api/v1/getGameHall
Header:
- auth-token: {authtoken}
Body 参数：
- lang（可选）：zh/en，默认 zh
返回说明：
- 返回大厅地址 hall_url
- 返回游戏列表（来自 dice_game）
- 不返回敏感信息字段

返回字段：

data.provider：供应商名称
data.provider_code：供应商编码
data.hall_url：大厅地址
data.game_list：游戏列表（字段结构同 /api/v1/getGameList）

成功返回示例：

{
  "code": 200,
  "message": "success",
  "data": {
    "provider": "Dicey Fun",
    "provider_code": "DF",
    "hall_url": "https://dice-v3-game.h55555game.top/",
    "game_list": [
      {
        "provider": "Dicey Fun",
        "provider_code": "DF",
        "game_code": "dafuwen",
        "game_key": "dafuwen",
        "game_type": "slot",
        "logo": "",
        "game_url": "https://dice-v3-game.h55555game.top/",
        "hall_url": "https://dice-v3-game.h55555game.top/",
        "status": 1,
        "sort": 1,
        "game_name": "大富翁"
      }
    ]
  }
}

成功返回示例（lang=en）：

{
  "code": 200,
  "message": "success",
  "data": {
    "provider": "Dicey Fun",
    "provider_code": "DF",
    "hall_url": "https://dice-v3-game.h55555game.top/",
    "game_list": [
      {
        "provider": "Dicey Fun",
        "provider_code": "DF",
        "game_code": "dafuwen",
        "game_key": "dafuwen",
        "game_type": "slot",
        "logo": "",
        "game_url": "https://dice-v3-game.h55555game.top/",
        "hall_url": "https://dice-v3-game.h55555game.top/",
        "status": 1,
        "sort": 1,
        "game_name": "Dafuweng"
      }
    ]
  }
}

5.3 获取某个游戏地址（已支持）

路径: POST /api/v1/getGameUrl
Body 参数：
- username（必填）：玩家账号（不存在会自动创建）
- password（可选）：默认 123456
- time（可选）：不传则服务端取当前时间戳
- lang（可选）：zh/en，默认 zh

成功返回示例：

{
  "code": 200,
  "message": "success",
  "data": {
    "url": "https://{game-domain}/?token=...&lang=zh"
  }
}

5.4 获取大厅地址（当前项目建议）

当前项目以 getGameUrl 作为主要入场方式，game_list 仅有 dafuwen。

若第三方需要独立大厅地址，可使用你方配置值：[代填]
若第三方可直接跳游戏，可直接调用 getGameUrl

5.5 获取游戏列表 API（当前项目状态）

已提供独立接口：POST /api/v1/getGameList，支持中英文格式，且数据来自 dice_game 表。

6. 游戏管理后台（新增）

本次已新增游戏管理数据表与菜单，用于统一管理游戏基础信息。

6.1 数据表

建表 SQL：server/db/dice_game.sql
表名：dice_game
关键字段：
- logo：游戏 logo
- game_url：游戏地址
- hall_url：大厅地址
- game_code：游戏编号
- game_key：游戏唯一值
- status：状态（1 启用 / 0 禁用）
- game_type：游戏类型
- merchant_config_json：商户可见扩展
- sensitive_config_json：敏感配置（大厅接口不返回）

6.2 菜单与权限

菜单 SQL：server/db/dice_game_menu.sql
菜单路径：/dice/game/index
权限标识：
- dice:game:index:index
- dice:game:index:read
- dice:game:index:save
- dice:game:index:update
- dice:game:index:destroy

7. 钱包相关接口

以下接口均需 Header: auth-token。

7.1 查询余额（已支持）

方式 1（推荐）：POST /api/v1/getPlayerInfo

请求参数：
- username（必填）
余额字段：
- data.coin

7.2 额度转入 / 额度转出（已支持）

接口：POST /api/v1/setPlayerWallet

请求参数：
- username（必填）
- coin（必填）
  - coin > 0：额度转入（充值）
  - coin < 0：额度转出（提现）
  - coin = 0：非法

成功返回 wallet record，包含转账前后余额等信息。

7.3 获取大厅地址（钱包侧）

如接入方钱包流程要求“转账后返回大厅地址”，可在完成 setPlayerWallet 后再调用：

POST /api/v1/getGameUrl

8. 商户（代理）可配置字段

建议在对接参数表中配置以下字段：

provider：Dicey Fun
provider_code：DF
agent_id：5ef059938ba799aaa845e1c2e8a762bd
secret：签名密钥（双方约定）
agent_token：[我来填]（如需额外业务层 token）
game_url：游戏前端域名/地址
lobby_url：大厅地址（可选）
lang：默认语言（zh/en）
callback_url：业务回调地址（如后续扩展）
ip_whitelist：调用白名单（建议）

9. 后台管理信息

后台管理地址：https://dice-v3.h55555game.top/
后台账号：zhuguan
后台密码：qwer1234

10. 对接时序（建议）

平台分配 agent_id、secret
第三方调用 /api/v1/authToken 获取 authtoken
第三方调用 /api/v1/getGameHall 或 /api/v1/getGameList 获取大厅/游戏信息
第三方调用 /api/v1/getPlayerInfo（可选，检查用户与余额）
第三方调用 /api/v1/setPlayerWallet 进行额度转入（如有）
第三方调用 /api/v1/getGameUrl 获取游戏地址并跳转
结束后调用 /api/v1/setPlayerWallet 执行额度转出（如有）

11. Postman 调用示例

11.1 获取 auth-token

curl --location --request GET 'https://{your-domain}/api/v1/authToken?agent_id={agent_id}&secret={secret}&time={time}&signature={signature}'

建议在接入测试时，先本地打印以下值再发请求，便于排查：

agent_id
time
sign_src（拼接前字符串）
signature
最终请求 URL

11.2 获取游戏地址

curl --location --request POST 'https://{your-domain}/api/v1/getGameUrl' \
--header 'Content-Type: application/json' \
--header 'auth-token: {authtoken}' \
--data-raw '{
  "username":"test_player_001",
  "lang":"zh"
}'

11.3 获取游戏列表（中文）

curl --location --request POST 'https://{your-domain}/api/v1/getGameList' \
--header 'Content-Type: application/json' \
--header 'auth-token: {authtoken}' \
--data-raw '{
  "lang":"zh"
}'

11.4 获取游戏列表（英文）

curl --location --request POST 'https://{your-domain}/api/v1/getGameList' \
--header 'Content-Type: application/json' \
--header 'auth-token: {authtoken}' \
--data-raw '{
  "lang":"en"
}'

11.5 获取游戏大厅（中文）

curl --location --request POST 'https://{your-domain}/api/v1/getGameHall' \
--header 'Content-Type: application/json' \
--header 'auth-token: {authtoken}' \
--data-raw '{
  "lang":"zh"
}'

11.6 额度转入

curl --location --request POST 'https://{your-domain}/api/v1/setPlayerWallet' \
--header 'Content-Type: application/json' \
--header 'auth-token: {authtoken}' \
--data-raw '{
  "username":"test_player_001",
  "coin":100
}'

11.7 查询余额

curl --location --request POST 'https://{your-domain}/api/v1/getPlayerInfo' \
--header 'Content-Type: application/json' \
--header 'auth-token: {authtoken}' \
--data-raw '{
  "username":"test_player_001"
}'

13 KiB Raw Blame History Unescape Escape

Dicey Fun 第三方接入文档（基于现有项目接口）

1. 基础信息

2. 接口域名与协议

2.1 调用规范（建议第三方按此统一实现）

3. 通用返回格式

4. 鉴权流程（平台级）

4.1 获取 auth-token

4.2 完整调用链（推荐）

5. 游戏相关接口

5.1 获取游戏列表（已支持）

5.2 获取游戏大厅信息（已支持，脱敏）

5.3 获取某个游戏地址（已支持）

5.4 获取大厅地址（当前项目建议）

5.5 获取游戏列表 API（当前项目状态）

6. 游戏管理后台（新增）

6.1 数据表

6.2 菜单与权限

7. 钱包相关接口

7.1 查询余额（已支持）

7.2 额度转入 / 额度转出（已支持）

7.3 获取大厅地址（钱包侧）

8. 商户（代理）可配置字段

9. 后台管理信息

10. 对接时序（建议）

11. Postman 调用示例

11.1 获取 auth-token

11.2 获取游戏地址

11.3 获取游戏列表（中文）

11.4 获取游戏列表（英文）

11.5 获取游戏大厅（中文）

11.6 额度转入

11.7 查询余额

13 KiB

Raw Blame History