diff --git a/server/docs/DICEY_FUN_THIRD_PARTY_ACCESS.md b/server/docs/DICEY_FUN_THIRD_PARTY_ACCESS.md index de4fd22..7a8414c 100644 --- a/server/docs/DICEY_FUN_THIRD_PARTY_ACCESS.md +++ b/server/docs/DICEY_FUN_THIRD_PARTY_ACCESS.md @@ -9,7 +9,7 @@ - provider_logo: `` - 获取大厅地址: `https://dice-v3-lobby.h55555game.top` - 后台管理地址: `https://dice-v3.h55555game.top/` -- agent_token: `[我来填]` +- agent_token: `[后台菜单查看：系统管理-用户管理-代理ID]` - agent_id: `5ef059938ba799aaa845e1c2e8a762bd` ## 2. 接口域名与协议 diff --git a/server/docs/DICEY_FUN_THIRD_PARTY_ACCESS_EN.md b/server/docs/DICEY_FUN_THIRD_PARTY_ACCESS_EN.md new file mode 100644 index 0000000..660616d --- /dev/null +++ b/server/docs/DICEY_FUN_THIRD_PARTY_ACCESS_EN.md @@ -0,0 +1,535 @@ +# Dicey Fun Third-Party Integration Guide (Based on Existing Project APIs) + +## 1. Basic Information + +- provider: `Dicey Fun` +- provider_code: `DF` +- game_type: `slot` +- game_list: `["dafuwen"]` +- provider_logo: `` +- Lobby URL (reference): `https://dice-v3-lobby.h55555game.top` +- Admin console URL: `https://dice-v3.h55555game.top/` +- agent_token: `[View in admin console menu: System Management -> User Management -> Agent ID]` +- agent_id: `5ef059938ba799aaa845e1c2e8a762bd` + +## 2. API Domain and Protocol + +- Protocol: `HTTP/HTTPS` (Production is recommended to use `HTTPS`) +- Base URL: `https://{your-domain}` (Provided by the deployment party) +- Content-Type: `application/json` +- Charset: `UTF-8` + +### 2.1 Calling Conventions (Recommended for Third Parties) + +- `/api/v1/authToken` uses `GET + Query parameters` +- Other `/api/v1/*` endpoints use `POST + JSON Body` (In this project the route is `Route::any`, but third parties are recommended to standardize on `POST`) +- Unified headers: + - `Content-Type: application/json` + - `Accept: application/json` + - `auth-token: {authtoken}` (Required for all endpoints except `/api/v1/authToken`) +- All time-related parameters use Unix timestamps (seconds) +- Recommended timeouts: connect timeout `3s`, read timeout `10s` +- Production recommendation: add caller IP whitelist and retry backoff (to avoid burst retry storms) + +--- + +## 3. Common Response Format + +All endpoints return the following structure: + +```json +{ + "code": 200, + "message": "success", + "data": {} +} +``` + +Notes: + +- `code=200` indicates success +- Failures typically return: `400/401/402/403/404/422/500` + +Common error codes: + +- `400` Invalid parameters +- `401` Missing token +- `402` Token invalid or expired +- `403` Signature or authentication failed +- `404` Resource not found +- `422` Business error (e.g., insufficient balance) +- `500` Server exception + +--- + +## 4. Authentication Flow (Platform Level) + +Before calling any `/api/v1/*` endpoint, obtain an `auth-token` first. + +### 4.1 Get auth-token + +- Path: `GET /api/v1/authToken` +- Auth parameters (Query): + - `agent_id`: Agent identifier (merchant identifier) + - `secret`: Shared secret agreed by both parties + - `time`: Unix timestamp (seconds) + - `signature`: Signature + +Signature rule: + +```text +signature = md5(agent_id + secret + time) +``` + +Signature example (source string and result): + +```text +agent_id = 9f86d081884c7d659a2feaa0c55ad015 +secret = xF75oK91TQj13s0UmNIr1NBWMWGfflNO +time = 1713753600 +sign_src = 9f86d081884c7d659a2feaa0c55ad015xF75oK91TQj13s0UmNIr1NBWMWGfflNO1713753600 +signature= md5(sign_src) +``` + +PHP signature example: + +```php +$agentId = '9f86d081884c7d659a2feaa0c55ad015'; +$secret = 'xF75oK91TQj13s0UmNIr1NBWMWGfflNO'; +$time = (string) time(); +$signature = md5($agentId . $secret . $time); +``` + +JavaScript signature example (Node.js): + +```javascript +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'); +``` + +Server-side validation logic (key points): + +- Missing any of `agent_id/secret/time/signature` => fail (`400`) +- `secret` mismatch => fail (`403`) +- `time` outside tolerance window => fail (`403`, default tolerance `300s`) +- `signature` mismatch => fail (`403`) +- If validated, the server issues `authtoken`; subsequent requests must include it in the `auth-token` header + +Anti-replay and time sync recommendations: + +- Caller server must enable NTP time synchronization +- `time` should be the current seconds timestamp at request time; do not reuse old values +- If you see “Timestamp expired or invalid”, first check server clock drift + +Success response example: + +```json +{ + "code": 200, + "message": "success", + "data": { + "authtoken": "xxx.yyy.zzz" + } +} +``` + +For subsequent calls to `/api/v1/*`, include the following header: + +```text +auth-token: {authtoken} +``` + +### 4.2 Full Call Chain (Recommended) + +1. Compute `signature = md5(agent_id + secret + time)` +2. Call `GET /api/v1/authToken` to obtain `authtoken` +3. Add header `auth-token: {authtoken}` +4. Call business endpoints (e.g., `getPlayerInfo`, `setPlayerWallet`, `getGameUrl`) +5. If `402` is returned, re-fetch `authtoken` and retry once + +--- + +## 5. Game APIs + +All endpoints below require the `auth-token` header. + +## 5.1 Get Game List (Supported) + +- Path: `POST /api/v1/getGameList` +- Header: + - `auth-token: {authtoken}` +- Body parameters: + - `lang` (optional): `zh`/`en`, default `zh` +- Response notes: + - Reads enabled games (`status=1`) from the `dice_game` table + - Currently returns only one game by default: `dafuwen` + - Returns `game_name` in Chinese/English according to `lang` + - Fields are desensitized: sensitive configs (e.g., `sensitive_config_json`) will not be returned + +Response fields (`data.game_list[]`): + +- `provider`: Provider name +- `provider_code`: Provider code +- `game_code`: Game code +- `game_key`: Unique game key +- `game_type`: Game type +- `logo`: Game logo URL +- `game_url`: Game URL +- `hall_url`: Lobby URL +- `status`: Status (`1` enabled) +- `sort`: Sort value +- `game_name`: Game name (Chinese/English based on `lang`) + +Success example (`lang=zh`): + +```json +{ + "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": "大富翁" + } + ] + } +} +``` + +Success example (`lang=en`): + +```json +{ + "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 Get Game Hall Info (Supported, Desensitized) + +- Path: `POST /api/v1/getGameHall` +- Header: + - `auth-token: {authtoken}` +- Body parameters: + - `lang` (optional): `zh`/`en`, default `zh` +- Response notes: + - Returns lobby URL `hall_url` + - Returns game list (from `dice_game`) + - Does not return sensitive information fields + +Response fields: + +- `data.provider`: Provider name +- `data.provider_code`: Provider code +- `data.hall_url`: Lobby URL +- `data.game_list`: Game list (same structure as `/api/v1/getGameList`) + +Success example: + +```json +{ + "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": "大富翁" + } + ] + } +} +``` + +Success example (`lang=en`): + +```json +{ + "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 Get Game URL (Supported) + +- Path: `POST /api/v1/getGameUrl` +- Body parameters: + - `username` (required): Player username (auto-created if not exists) + - `password` (optional): default `123456` + - `time` (optional): if omitted, server uses current timestamp + - `lang` (optional): `zh`/`en`, default `zh` + +Success example: + +```json +{ + "code": 200, + "message": "success", + "data": { + "url": "https://{game-domain}/?token=...&lang=zh" + } +} +``` + +### 5.4 Lobby URL (Recommendation for This Project) + +This project uses `getGameUrl` as the primary entry method, and `game_list` currently contains only `dafuwen`. + +- If the third party needs a standalone lobby URL, use your configured value: `[to be filled]` +- If the third party can jump directly into the game, call `getGameUrl` directly + +### 5.5 Game List API (Current Project Status) + +An independent endpoint is provided: `POST /api/v1/getGameList`, supporting both Chinese and English, with data from the `dice_game` table. + +--- + +## 6. Game Management Admin (Added) + +This update introduces a game management table and menu to centrally manage basic game information. + +### 6.1 Database Table + +- Table creation SQL: `server/db/dice_game.sql` +- Table name: `dice_game` +- Key fields: + - `logo`: Game logo + - `game_url`: Game URL + - `hall_url`: Lobby URL + - `game_code`: Game code + - `game_key`: Unique game key + - `status`: Status (1 enabled / 0 disabled) + - `game_type`: Game type + - `merchant_config_json`: Merchant-visible extensions + - `sensitive_config_json`: Sensitive configuration (not returned by hall APIs) + +### 6.2 Menu and Permissions + +- Menu SQL: `server/db/dice_game_menu.sql` +- Menu path: `/dice/game/index` +- Permission identifiers: + - `dice:game:index:index` + - `dice:game:index:read` + - `dice:game:index:save` + - `dice:game:index:update` + - `dice:game:index:destroy` + +--- + +## 7. Wallet APIs + +All endpoints below require the `auth-token` header. + +### 7.1 Query Balance (Supported) + +Method 1 (recommended): `POST /api/v1/getPlayerInfo` + +- Request parameters: + - `username` (required) +- Balance field: + - `data.coin` + +### 7.2 Credit In / Credit Out (Supported) + +Endpoint: `POST /api/v1/setPlayerWallet` + +- Request parameters: + - `username` (required) + - `coin` (required) + - `coin > 0`: Credit in (deposit) + - `coin < 0`: Credit out (withdraw) + - `coin = 0`: Invalid + +On success, returns a `wallet record` including balances before/after transfer. + +### 7.3 Get Lobby URL (Wallet-side) + +If the integrator’s wallet flow requires “return lobby URL after transfer”, call the following after `setPlayerWallet`: + +- `POST /api/v1/getGameUrl` + +--- + +## 8. Merchant (Agent) Configurable Fields + +It is recommended to configure the following fields in the integration parameter table: + +- `provider`: `Dicey Fun` +- `provider_code`: `DF` +- `agent_id`: `5ef059938ba799aaa845e1c2e8a762bd` +- `secret`: Signature secret (shared by both parties) +- `agent_token`: `[to be filled by us]` (if an additional business-layer token is needed) +- `game_url`: Game frontend domain/URL +- `lobby_url`: Lobby URL (optional) +- `lang`: Default language (`zh`/`en`) +- `callback_url`: Business callback URL (for future extension) +- `ip_whitelist`: Caller IP whitelist (recommended) + +--- + +## 9. Admin Console Information + +- Admin console URL: `https://dice-v3.h55555game.top/` +- Username: `zhuguan` +- Password: `qwer1234` + +--- + +## 10. Integration Sequence (Recommended) + +1. Platform assigns `agent_id` and `secret` +2. Third party calls `/api/v1/authToken` to obtain `authtoken` +3. Third party calls `/api/v1/getGameHall` or `/api/v1/getGameList` to obtain lobby/game info +4. Third party calls `/api/v1/getPlayerInfo` (optional, check user and balance) +5. Third party calls `/api/v1/setPlayerWallet` to credit in (if applicable) +6. Third party calls `/api/v1/getGameUrl` to get the game URL and redirect +7. After the session, call `/api/v1/setPlayerWallet` to credit out (if applicable) + +--- + +## 11. Postman / cURL Examples + +### 11.1 Get auth-token + +```bash +curl --location --request GET 'https://{your-domain}/api/v1/authToken?agent_id={agent_id}&secret={secret}&time={time}&signature={signature}' +``` + +During integration testing, it is recommended to print the following values locally before sending the request to ease troubleshooting: + +- `agent_id` +- `time` +- `sign_src` (concatenated source string before hashing) +- `signature` +- Final request URL + +### 11.2 Get Game URL + +```bash +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 Get Game List (Chinese) + +```bash +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 Get Game List (English) + +```bash +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 Get Game Hall (Chinese) + +```bash +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 Credit In + +```bash +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 Query Balance + +```bash +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" +}' +```