SoftAggregator 娱乐场API文档

通过一个无缝钱包API接入 40,000+ 款娱乐场游戏。本参考文档涵盖获取游戏列表、创建玩家、启动游戏、读取玩家历史以及处理钱包回调所需的全部内容。

简介

SoftAggregator API 采用无缝钱包模式：玩家余额保存在您的平台上，每次查询余额、投注和派彩时，我们的API都会调用您的回调地址。所有API方法均以 POST 请求、JSON 请求体发送至同一个接口地址。

Base URL
https://api.softaggregator.com/api/v1

鉴权

每个请求都需携带您的 api_login 和 api_password（审核通过后在运营商后台发放）。method 字段用于指定要执行的操作。

{
  "api_login": "YOUR_API_LOGIN",
  "api_password": "YOUR_API_PASSWORD",
  "method": "getGameList"
}

一个账户运营多个网站

您可以在一个 SoftAggregator 账户下运营多个网站或项目。在运营商后台（API integration → Your other sites）添加每个站点后，系统会为其发放独立的 api_login、api_password、salt_key 以及独立的回调地址。额度余额、游戏目录、价格与结算仍在同一账户下共享。

每个站点还可在同一界面设置独立的默认玩家币种。它只是默认值：您在 createPlayer / getGame 中传入的 currency 字段始终优先，因此按玩家区分的多币种功能保持不变。优先级顺序：调用中的 currency → 该玩家已记录的币种 → 站点默认币种 → 账户默认币种。

请始终使用玩家所属站点的密钥调用我们。玩家归属于创建他们时所用密钥对应的站点，因此两个站点可以安全地使用相同的 user_username（例如两边都是 1042），互不影响对方钱包：每笔投注与派彩只会回调到该站点的回调地址，用户名与您发送的完全一致。

如果您只运营一个网站，则无需任何改动，现有密钥和回调地址照常使用。

币种

所有涉及资金的方法（createPlayer、getGame 与 getGameDemo）都接受可选的 currency 字段（ISO 4217 代码，例如 EUR、USD、BRL、INR、PKR）。它决定玩家在游戏中看到的币种，包括投注限额与余额。

钱包回调（balance / debit / credit）携带相同的 currency，amount 始终以该币种的最小单位表示（例如 2.50 → 250）。您可用的币种由 SoftAggregator 配置，如需为账户开通新币种，请联系 客服 或 @mentionso。

getCurrencies获取您的币种

返回您账户已开通的币种，便于您以程序方式选择正确的 currency 值，而不必写死在代码中。

POST /api/v1
{ "api_login":"...", "api_password":"...", "method":"getCurrencies" }

→ {
  "error": 0,
  "response": {
    "default": "PKR",            // 在 getGame / createPlayer 中传入此值（或省略以使用它）
    "currencies": ["PKR","EUR"], // 您的账户可使用的币种
    "settlement": "EUR"          // 您账户的结算币种
  }
}

getGameList获取游戏列表

返回您可使用的全部游戏。启动游戏时请使用每款游戏的 id_hash。

POST /api/v1
{ "api_login": "...", "api_password": "...", "method": "getGameList" }

→ {
  "error": 0,
  "response": [
    {
      "id": 483,
      "name": "Game Name",
      "game_type": "slots",          // 标准化品类，请用它来搭建游戏大厅
      "provider": "pragmaticplay",   // 工作室键值，与 getProviderList 对应
      "provider_name": "Pragmatic Play",
      "provider_logo": "https://cdn.imagesai.org/p/pragmaticplay.png",
      "type": "Video Slots",         // 工作室原始标签，不统一，仅为兼容保留
      "category": "pragmaticplay",   // 工作室原始代码，仅为兼容保留
      "id_hash": "provider/GameName",
      "freerounds_supported": false,       // 见“免费回合”一节
      "play_for_fun_supported": true,
      "image": "https://.../GameName.webp"
    }
  ]
}

getProviderList获取供应商

返回您可使用的游戏工作室，包含显示名称和标志。每个 provider 值都与 getGameList 中每款游戏的 provider 字段一一对应，便于直接搭建供应商筛选器。 以多个代码发布的工作室（例如两路 Pragmatic Play 游戏源）只返回一次。

POST /api/v1
{ "api_login": "...", "api_password": "...", "method": "getProviderList" }

→ {
  "error": 0,
  "response": [
    {
      "provider": "pragmaticplay",
      "name": "Pragmatic Play",
      "logo": "https://cdn.imagesai.org/p/pragmaticplay.png",
      "games": 3410
    }
  ]
}

标志为 PNG 格式，400×160，由我们自己的 CDN 提供，不依赖外部主机，不会被各国运营商网络屏蔽。 标志缓存一天，我们优化后的标志无需您做任何改动即可呈现给玩家。

createPlayer创建玩家

在启动游戏前于系统中创建（或确认）玩家。

{ "api_login":"...", "api_password":"...", "method":"createPlayer",
  "user_username":"player123", "user_password":"secret", "currency":"EUR" }

→ { "error": 0, "response": { ... } }

getGame启动游戏

返回用于在 iframe 中加载游戏的 URL。请将 getGameList 返回的 id_hash 作为 gameid 传入。

{ "api_login":"...", "api_password":"...", "method":"getGame",
  "user_username":"player123", "user_password":"secret",
  "gameid":"provider/GameName", "lang":"en", "currency":"EUR",
  "country":"BR", "homeurl":"https://yourcasino.com" }

→ { "error": 0, "response": "https://game-launch-url..." }

受限市场。少数游戏工作室会排除特定国家。我们按玩家执行这一限制，依据的是您在启动时传入的 country，绝不会根据 IP 地址推测。玩家所在国家不允许打开的游戏会返回 Game not available in your country，其余游戏正常启动。如果您的账户服务的市场存在工作室限制，我们会将 country 由可选改为必填，未携带该字段的启动请求将返回 country is required on getGame。只要在每次真钱启动时都传入该字段，无论日后开通什么都不受影响。

免费回合

促销型免费回合（free rounds）按账户单独开通。在未开通的账户上，addFreeRounds、getFreeRounds 和 deleteFreeRounds 返回 { "error": 1, "message": "Free rounds not supported" }，游戏列表中的 freerounds_supported 为 false。如需通过自己的促销活动发放免费回合，请先联系我们沟通开通方案。

游戏内的免费旋转是另一回事，且完全可用。由 Scatter 触发的免费旋转、奖励回合、购买功能和奖池完全由游戏自身运行，您无需做任何集成。它们以普通钱包回调的形式到达：免费旋转的赢额会以 action: credit 发送，带有 amount，但没有对应的 debit。只要遵守钱包回调一节中的两条规则，即可正确派彩。跳过本节不会给您带来任何损失。

getPlayerHistory玩家历史

返回您的某位玩家的回合历史，按时间倒序排列。每个游戏回合一条记录（同一回合的所有分段会合并）。金额为以分为单位的整数，币种为该回合所用币种。

{ "api_login":"...", "api_password":"...", "method":"getPlayerHistory",
  "user_username":"player123",
  "limit":50, "offset":0,
  "date_from":"2026-08-01 00:00:00", "date_to":"2026-08-01 23:59:59",
  "gameid":"x6046f4988155b46", "round_id":"..." }

只有 user_username 为必填。limit 默认 50（最大 500）；gameid 为 getGameList 返回的 id_hash；date_from/date_to 为 UTC 时间。

{ "error":0, "response":{
    "user_username":"player123", "total":128, "limit":50, "offset":0,
    "rounds":[
      { "round_id":"88c6807b55e7434c3e00aa50dc82240e",
        "gameid":"x6046f4988155b46", "game_name":"Gates of Olympus 1000",
        "currency":"USD", "bet":40, "win":58, "net":18,
        "legs":2, "rolled_back":false,
        "started_at":"2026-08-01 16:10:15", "ended_at":"2026-08-01 16:10:24" } ] } }

钱包回调

每当玩家余额发生变化，我们都会调用您的回调地址（在运营商后台设置，每个网站一个，见多站点）。回调以 GET 请求发送。您的接口必须始终返回 HTTP 200，错误只通过 JSON 响应体传达。余额始终为以分为单位的整数（例如 €2.50 → 250）。

action: balance

在会话开始时发送，用于读取玩家余额。

GET {your_callback}?username=player123¤cy=EUR&action=balance
     &call_id=...×tamp=...&key=...

← { "error": 0, "balance": 250 }

action: debit / credit

debit 扣除投注；credit 增加派彩。call_id 是唯一交易 ID，请用它去重。若 debit 时余额不足，请返回 error: 1 并附上当前余额。

GET {your_callback}?username=player123¤cy=EUR&action=debit
     &amount=100&type=bet&round_id=...&game_id=x95adbbbf8314c37
     &call_id=...×tamp=...&rb=0&key=...

← { "error": 0, "balance": 150 }

您的处理程序必须遵守两条规则。

1. 绝不要因为 type 而拒绝回调。只根据 action 分支处理。type 仅供参考，其取值会随着我们新增供应商而增加，遇到未知值请按普通投注或派彩处理。
2. credit 可能没有对应的 debit。免费旋转、奖励回合和奖池派彩都是只有 amount 的赢额，没有可匹配的投注。请仅依据 call_id 去重；若要求先有 debit，您的玩家将永远拿不到免费旋转的赢额。

签名校验

每个回调都携带 timestamp 和 key。请校验时间戳在 30 秒以内，且 key 匹配：

key = md5(timestamp + your_salt_key)

您的 salt_key 显示在运营商后台。若校验失败，请返回 { "error": 2, "balance": 0 }。

完整载荷签名（推荐）。每个回调还会携带 X-Signature HTTP 头：以您的 salt_key 为密钥，对全部查询参数计算的 HMAC-SHA256（十六进制）。它覆盖 amount、action、username、call_id、timestamp 以及其他所有字段。签名字符串的构造方式：使用解码后的参数，按名称排序，以 name=value 形式用 & 连接：

X-Signature = hex( HMAC_SHA256( salt_key,
  "action=debit&amount=250&call_id=...&currency=EUR&key=...&timestamp=...&username=player123" ) )

所有回调均从固定 IPv4 地址 85.122.129.59 发出：您可以将其加入白名单并拒绝其他来源。

错误码

集成需要帮助？请通过 Telegram @mentionso 联系我们，或发送邮件至 [email protected]。

API 变更、新增游戏供应商和计划维护都会在我们的 Telegram 频道 @casinogamessoftware 发布。负责维护本集成的同事值得关注。