用于 投注与彩票结算 的系统集成

赔率和赛果计算系统如何工作？

与我们的投注和彩票结算系统集成包含三个关键阶段：

步骤 1：授权

在第一阶段，您需要在系统中进行授权。这通过发送包含用户凭据（登录名和密码）的 POST 请求来完成。授权成功后会返回代表会话的 cookie，必须将其保存。这些 cookie 是后续所有请求所必需的，因为它们用于识别系统中的用户会话。

步骤 2：发送投注

在此阶段，包含以下内容的投注代码会被发送到我们的系统：

• 与赛事相对应的比赛 ID。
• 描述所选赛果的投注代码（例如，球队获胜、让球或大小球）。
• 在提交时有效的投注赔率。

提交数据时，必须包含授权期间获得的 cookie。这确保了正确的用户识别和投注处理。

步骤 3：接收结果

在赛果或彩票计算出来后，我们的系统会向指定的 remote_host 发送 POST 请求。该请求包括：

• 彩票状态（赢、输或退款）。
• 彩票中包含的所有赛果的状态。

赛果一经确定便会立即发送。例如：

• 如果投注是针对中间赛果（例如，让球 2.5，且打入了第三个进球），则结算可能会在比赛期间进行。
• 如果投注是针对最终结果（例如，球队获胜），则状态信息将在比赛结束后立即发送。

现在详细查看每个步骤。我们详细描述了请求、参数和 API 响应。

可以从经理那里获得登录名、密码和发送请求的主机地址。

请求 URL：

{APIHOST}/WebServices/BCService.asmx/LogIn/

数据提交类型： POST

提交的数据：

参数	说明
login	用户登录名
password	用户密码

重要提示！

• 授权期间，响应中包含 cookie。必须保存这些 cookie 并随后续请求一起发送。

简化集成的建议：

• 确保 login 字段作为字符串传递。
• 验证 cookie 的正确保存和发送，因为这会影响后续请求的执行。
• 如果发生错误，请求将返回一个空对象。请确保妥善处理此情况。

Cookie 的有效期为 3 个月。但是，如果服务器重新启动，它们可能会被重置。因此，如果您在保存彩票时遇到错误，则需要重新进行授权。

"errorCode":1,
"fullErrorCode":99,
"errorMessage":"Invalid access level"

响应示例：

成功：

{"d":{"UserId":"36557"}}

失败：

{"d":{}}

响应字段说明：

字段	说明
UserId	唯一用户标识符
d	响应的根对象

通用建议：

• 在发送第一个请求之前，确保用户输入了正确的凭据。
• 设置错误处理，向用户显示授权失败的原因（例如，登录名或密码错误）。
• 记录成功和失败的尝试，以便进行分析和监控。

必须保存 Cookie 并随后续请求一起发送。

import requests
import json

url = "https://example-domain-calc.com/WebServices/BCService.asmx/LogIn/"

payload = json.dumps({
  "login": "[email protected]",
  "password": "demo-password"
})
headers = {
  'Content-Type': 'application/json'
}

print(response.text)

$curl = curl_init();

curl_setopt_array($curl, array(
    CURLOPT_URL => 'https://example-domain-calc.com/WebServices/BCService.asmx/LogIn/',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => '',
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 0,
    CURLOPT_FOLLOWLOCATION => true,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_POSTFIELDS =>'{
    "login":"[email protected]",
    "password":"demo-password"
}',
    CURLOPT_HTTPHEADER => array(
    'Content-Type: application/json'
    ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

const myHeaders = new Headers();
myHeaders.append("Content-Type", "application/json");

const raw = JSON.stringify({
    "login": "[email protected]",
    "password": "demo-password"
});

const requestOptions = {
    method: "POST",
    headers: myHeaders,
    body: raw,
    redirect: "follow"
};

fetch("https://example-domain-calc.com/WebServices/BCService.asmx/LogIn/", requestOptions)
    .then((response) => response.text())
    .then((result) => console.log(result))
    .catch((error) => console.error(error));

OkHttpClient client = new OkHttpClient().newBuilder()
.build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\r\n    \"login\":\"[email protected]\",\r\n    \"password\":\"demo-password\"\r\n}");
Request request = new Request.Builder()
.url("https://example-domain-calc.com/WebServices/BCService.asmx/LogIn/")
.method("POST", body)
.addHeader("Content-Type", "application/json")
.build();
Response response = client.newCall(request).execute();

要提交投注，您必须使用在授权阶段获得的 cookie。这些数据是识别您的会话和处理请求所必需的。

请求 URL：

{HOST_API}/bet/place/

{
    "data":{
        "list_bets":[
            "line#586464528|17|954|2.5#4.27",  "live#586464528|87|4|0#1.12"
        ],
        "realAmount":"2",
        "currency":"USD",
        "lang":"en",
        "remote_host":"https://mysites.com",
        "rate_mode":"reject"
    }
}

字段说明

参数	说明
list_bets	投注代码和赔率。格式："event_type#match_ID|bet_code#odds"。示例："live#579216393|1|1|0#2.1"
realAmount	投注金额。必须作为字符串传递，例如 "150"。
currency	彩票货币。
lang	保存投注和彩票的语言。例如："zh"、"en"、"ru" 或 "tr"。
remote_host	发送彩票计算结果的 URL。不要包含尾随斜杠。
rate_mode	赔率改变时处理彩票接收的选项："reject"（改变时拒绝）或 "accept"（忽略变化接受）。默认值："accept"。

注意： 确保参数以正确的格式传递。例如，即使只有一项投注，list_bets 也必须是一个数组。

我们不验证投注金额。您可以提交实际的投注金额或任意值。这是为了确保您财务数据的机密性。我们的任务是提供结算结果。您负责向您的玩家发放奖金。

提交投注所需的参数：

• list_bets — 包含有关投注和相应比赛的信息。
• remote_host — 我们发送彩票或赛果结算结果的 URL。
• rate_mode — 决定系统如何处理赔率变化。

其他参数也应该发送，但它们是可选的，可以为了您的方便而使用。

remote_host 参数的说明

remote_host 是您的服务器地址，我们向其发送包含投注计算结果的请求。此主机必须配置为接受来自我们服务器的请求。以下是可能的值以及关于使用此参数的具体细节示例。

您可以为 remote_host 指定各种选项：

• 简单主机： https://mysites.com
• 带端口的主机： https://mysites.com:78665
• 带附加路径的主机： https://mysites.com/request/sportapi/sender
• 带参数的主机： https://mysites.com/request.php?action=webhook

重要提示： 发送请求时，我们的系统会自动将字符串 /api/bet/result 追加到指定的 remote_host。因此，接收请求的最终地址格式为 remote_host + "/api/bet/result"。确保您的服务器已配置为在此路径接收数据。

示例：

• 您指定 remote_host = https://mysites.com。我们向以下地址发送请求：https://mysites.com/api/bet/result。
• 您指定 remote_host = https://mysites.com/request.php?action=webhook。我们向以下地址发送请求：https://mysites.com/request.php?action=webhook/api/bet/result。

技术细节：

• 请求使用 POST 方法发送。
• 您的服务器必须准备好接受我们发送的 JSON 数据。
• 您的服务器在成功接收数据后必须返回 200 状态码。

确保您的服务器正确处理了指定的路径和请求。下一节提供了我们服务器发送的数据结构示例。

rate_mode 参数的说明

rate_mode 参数定义了赔率变化时系统的行为。它可以取两个值：

• accept：在此模式下，即使赔率发生变化，彩票也会以当前赔率被接受。例如，玩家以 2.02 的赔率添加了“曼联获胜”的投注。当他们按下“下注”按钮时，赔率变为了 1.37 或 2.78。在 accept 模式下，系统会以新赔率保存彩票，而不会通知您的系统。
• reject：在此模式下，如果赔率发生变化，系统将拒绝彩票。响应将包含一个错误，通知赔率已更改。

选择最适合您业务流程并为您的用户提供便利的模式。

重要建议

1. JSON 格式化： 确保在发送之前将数据正确序列化为 JSON 格式。
2. Cookie： 包含在授权期间获得的 cookie，以成功识别用户会话。
3. 错误处理： 处理服务器响应，特别是返回 errorCode = 1 的情况。
4. 测试： 在集成的所有阶段进行测试，包括发送单张和多张投注。

响应字段

参数	说明
betCode	我们系统中唯一的投注号码
errorCode	请求结果的主要状态
fullErrorCode	错误详情
errorMessage	系统错误文本消息
AmountOut	潜在赢取金额
CountEvents	彩票中的投注数量
Coef	结果系数
IsLive	投注类型：滚球或赛前（true/false）
LinesId	比赛 ID
EventDate	比赛日期

下注错误说明

提交投注时可能会发生各种错误。服务器响应包含三个关键字段：

• errorCode： 主要请求状态。
• fullErrorCode： 错误详情。
• errorMessage： 错误的文本描述。

如果投注被成功接受，服务器将返回成功响应（见上文）。彩票已被接受，且没有错误。

如果发生错误，服务器将返回常规错误响应（见上文）。发生了其中一种可能的错误。以下是错误代码和消息。

可能的错误代码和说明

错误代码 (fullErrorCode)	错误消息 (errorMessage)	说明
1	error_wrong_bet_data	投注数据不正确。检查 list_bets 参数和其他必填字段。
1	error_block_bet_data	投注被暂时锁定，无法接受。
1	error_repeat_bet_data	不允许对同一场比赛的相同结果进行重复投注。
2	label_change_rate	赔率已发生变化。由于指定的赔率与当前赔率不匹配，彩票被拒绝。
3	error_exist_bet	指定的投注结果已不存在。检查数据的准确性。
99	Invalid access level	用户无权执行此操作。最有可能的是需要重新授权，cookie 缺失或账户被锁定。
99	Error exist remote host!	remote_host 参数不正确或缺失。检查您的服务器设置。

错误处理建议

• 输入数据验证： 确保正确提供了所有必需的参数。检查 list_bets 的格式以及所有必填字段的存在。
• 处理赔率： 如果使用 rate_mode = reject，请处理与赔率变化相关的错误 (label_change_rate)。
• 服务器配置： 确保在 remote_host 参数中正确指定了您的服务器。
• 错误日志记录： 记录所有错误（errorCode、fullErrorCode、errorMessage），以简化调试和与支持人员的沟通。
• 关键错误的操作： 如果发生 99 级别的错误，请检查您那侧的访问权限和 API 配置。

{
  "errorCode": 1,
  "fullErrorCode": [ERROR_CODE],
  "errorMessage": "[ERROR_DESCRIPTION]"
}

当投注被添加到我们的系统并完成计算后，我们会向您的服务器发送彩票结果。这些可以包括：

• 彩票结果（完整结算）。
• 彩票状态（赢、输、退款）。

请求会被发送到您在 remote_host 参数中指定的地址。字符串 /api/bet/result 会自动追加到该地址。确保您的服务器已配置为在此路径接收数据。

最终地址示例：

如果您指定了：remote_host = https://mysite.com，我们将会把数据发送到：https://mysite.com/api/bet/result。

{
    "remote_host": "https://mysite.com",
    "Heads": [{
        "KeyHead": {
            "Id": "344143",
            "BarCode": "x9c52i8411"
        },
        "Status": 2,
        "ExtStatus": 0,
        "AmountOut": 11130,
        "DateReceive": "1597075782"
    }]
}

字段说明

字段	说明
remote_host	发送您的数据的服务器地址。
Id	我们系统中唯一的投注标识符。在大多数情况下会被忽略。
BarCode	唯一的彩票号码。
Status	彩票的当前状态。可能的值：2 — 赢，4 — 输。
ExtStatus	退款时的附加状态：0 — 无变化，1 — 一个或多个赛果以改变的系数进行了计算。
AmountOut	赢取金额（如果彩票赢了）。
DateReceive	彩票结算的时间和日期。

如何解读 Status 和 ExtStatus

• Status = 2 且 ExtStatus = 0： 彩票赢了。
• Status = 4 且 ExtStatus = 0： 彩票输了。
• Status = 2 且 ExtStatus = 1： 退款。彩票以系数 1 进行计算。

集成的关键要点

• 处理 ExtStatus = 1： 如果比赛被取消或提前结束，可能会发生这种情况。在这些情况下，所有投注都以系数 1 计算。
• 技术要求： 请求使用 POST 方法发送。您的服务器必须准备好在路径 remote_host + /api/bet/result 接受 JSON 数据。

{
    "remote_host": "https://mysite.com",
    "Heads": [{
        "KeyHead": {
            "Id": "313",
            "BarCode": "75vz48t935"
        },
        "Status": 2,
        "ExtStatus": 0,
        "AmountOut": 19.85,
        "DateReceive": "1592937968"
    }, {
        "KeyHead": {
            "Id": "312",
            "BarCode": "77i0r6e15t"
        },
        "Status": 2,
        "ExtStatus": 0,
        "AmountOut": 12.51,
        "DateReceive": "1592937280"
    }]
}