Partner API

Luồng tích hợp

Đối tác / aggregator tích hợp với gameserver theo 5 bước chuẩn dưới đây. Ba bước đầu dùng API HMAC-signed, hai bước cuối là gameplay sau khi client đã vào game service.

Base URL

HTTP Base URL

WebSocket Game Services

Mỗi game có một WebSocket service riêng. Sau khi đổi sessionToken, client kết nối trực tiếp tới service tương ứng theo gameId:

Xác thực HMAC

Các API partner-facing dưới /api/partner/*, /api/user/login, và /api/user/register đều đi qua HMAC-SHA256. Mọi request phải kèm 4 header dưới đây:

x-api-key: <partner_api_key>
x-timestamp: <unix_time_ms>
x-signature: <hmac_sha256_hex>
Content-Type: application/json

3.1 Công thức ký

Payload ký được ghép theo thứ tự cố định, ngăn cách bằng ký tự |:

METHOD|PATH|TIMESTAMP|RAW_JSON_BODY

Ví dụ thực tế cho request đăng nhập:

POST|/api/user/login|1714546800000|{"username":"testuser1","password":"123456"}

3.2 Quy tắc verify thực tế

• METHOD dùng HTTP method chuẩn, thực tế là chữ in hoa như GET, POST.
• PATH chỉ lấy phần path, không bao gồm query string.
• Nếu request không có body thì body được xử lý thành {}.
• x-signature là HMAC SHA256 dạng hex chữ thường.
• x-timestamp dùng Unix time milliseconds.
• Request hết hạn nếu lệch quá 5 phút so với server.

API đối tác qua HMAC

Bộ 8 endpoints partner-facing. Tất cả đều yêu cầu HMAC. Bảng tổng hợp:

4.1 · Lấy danh sách game

HMAC

Lấy danh sách game đang available cho partner.

Response — field chính

4.2 · Lấy số dư partner

HMAC

Kiểm tra số dư hiện tại của partner trên hệ thống A3.

Response — field chính

4.3 · Lấy số dư player

HMAC

Kiểm tra số dư của player thuộc partner.

Path params

Response — field chính

• Thông tin player (id, username, ...)
• Tổng balance
• locked balance (đang trong round chưa settle)
• Danh sách ví theo từng gameId

4.4 · Cộng tiền cho player

HMAC

Cộng tiền vào tài khoản player.

Request body

{
  "playerId": 123,
  "amount": 1000,
  "description": "manual deposit"
}

Field

4.5 · Trừ tiền của player

HMAC

Trừ tiền khỏi tài khoản player.

Request body

{
  "playerId": 123,
  "amount": 1000,
  "description": "manual withdraw"
}

Field

4.6 · Tạo ví game cho player

HMAC

Tạo ví game cho player theo từng gameId. Mỗi ví là độc lập per-game.

Request body

{
  "playerId": 123,
  "gameId": 1003,
  "currency": "VND"
}

Field

4.7 · Đăng ký player

HMAC

Tạo người chơi mới. Có thể khởi tạo ví game đầu tiên ngay tại bước này.

Request body

{
  "username": "player123",
  "password": "password123",
  "initGameId": 1003,
  "gameUsername": "player123"
}

Field

4.8 · Đăng nhập player

HMAC

Đăng nhập người chơi và nhận token tạm thời để đổi sang sessionToken ở bước kế tiếp.

Request body

{
  "username": "testuser1",
  "password": "123456"
}

Response — field chính

API đổi token game session

5.1 · Đổi token sang sessionToken

Public · No HMAC

Đổi token đăng nhập sang sessionToken dùng cho game. Đây là route public, không yêu cầu HMAC — thay vào đó nó verify trực tiếp token đã được cấp ở bước trước.

Request body

{
  "token": "<login_token>"
}

Response — field chính

API sau khi player đăng nhập

Các API dưới đây không phải partner HMAC API trực tiếp. Chúng dùng Authorization: Bearer <token> của player session — phục vụ luồng player-facing trong app/web client của A3.

6.1 · Lấy profile người chơi

JWT Bearer

Lấy thông tin profile và số dư của player hiện tại (theo JWT đính kèm).

6.2 · Cập nhật balance từ phía player

JWT Bearer

Tăng hoặc giảm balance theo luồng player.

Request body

{
  "amount": 1000,
  "type": "increase",
  "reason": "manual adjustment"
}

6.3 · Lấy danh sách log chơi game

JWT Bearer

Lấy danh sách log của player.

Query params hỗ trợ

6.4 · Lấy chi tiết log

JWT Bearer

Lấy chi tiết một bản ghi log theo ID.

Nhóm API thường được đối tác quan tâm

Map nhanh từ use case → endpoint:

Điểm quan trọng cần nhớ

• Các API dưới /api/partner/* là API partner-facing rõ ràng, đều yêu cầu HMAC.
• POST /api/user/register và POST /api/user/login cũng đi qua HMAC và phục vụ tích hợp partner.
• POST /api/user/token là route public, không verify HMAC. Đổi từ login token sang sessionToken.
• GET /api/player/logs và GET /api/player/logs/:id hiện là API player-facing dùng Bearer JWT, không phải route /api/partner/*.
• Thao tác spin không phải HTTP API public riêng cho partner — spin diễn ra trong luồng gameplay sau khi client đã vào game service WebSocket tương ứng.

Danh sách gameId hiện có