赔率、投注和彩票 — API 技术文档

• 基本 URL API；
• 客户帐户登录名和密码；
• 使用回调时 - 启用该功能和秘密短语 callback_secret。

这些示例使用条件地址：

BASE_URL="https://coupon-api.example.com"

在生产中，使用 HTTPS。所有日期都以毫秒为单位的 Unix 时间戳传输，货币值以没有固定精度的十进制数字传输。

成功：

{
  "code": 1,
  "body": {},
  "error_code": null,
  "error_message": null,
  "date": 1784970000000,
  "time_ms": 5,
  "path": "/api/partner/example"
}

业务错误通常还伴随HTTP 200：

{
  "code": 0,
  "body": null,
  "error_code": 1002,
  "error_message": "Not all params",
  "date": 1784970000000,
  "time_ms": 5,
  "path": "/api/partner/example"
}

始终检查 HTTP 代码，然后是 code，然后是 error_code。请勿使用文本 error_message 作为软件密钥。

POST /api/partner/login
Content-Type: application/json

{
  "username": "partner-demo",
  "password": "strong-password"
}

支持字段 login 作为兼容别名 username。

成功响应：

{
  "code": 1,
  "body": {
    "token": "<jwt-token>",
    "user_id": 17,
    "username": "partner-demo"
  },
  "error_code": null,
  "error_message": null
}

在所有受保护的请求中，传递：

Authorization: Bearer <jwt-token>

基本登录错误：

这些错误是从 HTTP 200、code = 0 返回的。受保护方法的 HTTP 401 表示 JWT 丢失、无效、过期或撤销；再次登录。 HTTP 403 表示不适当的角色或访问被拒绝。

每个选定的结果都作为体育线路中的现成线路传输：

line_type#game_id#group_id#type_id#rate#coefficient[#player_id]

示例：

line#737779544#1#1#0#1.85
live#738917381|119|5869|0.5#3.6#149439538

• line_type：line或live；
• rate：总/让分参数或0；
• player_id：可选玩家ID；
• 支持分隔符 # 和 |。

不要手动收集或更正指针 - 将从行获得的值保持不变。

POST /api/partner/coupons/place
Authorization: Bearer <jwt-token>
Content-Type: application/json

{
  "list_bets": [
    "line#737779544#1#1#0#1.85"
  ],
  "amount": 10,
  "currency": "USD",
  "callback_url": "https://partner.example.com/api/coupon-result",
  "lang": "en",
  "mode": "reject",
  "mode_type": null,
  "multi": false
}

赔率

单打、多重彩和 multi

一组累加器序列最多可包含 15 个事件。您不能在同一场比赛中合并多个投注，包括主比赛、半场、赛节、角球、犯规和其他相关子赛事。该组合返回 506。

完整成功响应，包含 events_data 内的优惠券和接受的投注数据：

{
  "code": 1,
  "body": {
    "coupons": [
      {
        "coupon_code": "000000000272",
        "amount": 10,
        "win": 18.5,
        "potential_win": 18.5,
        "real_win": null,
        "coef": 1.85,
        "original_coef": 1.85,
        "calculate_coef": null,
        "has_return": false,
        "date": 1784970000000,
        "status": 0,
        "asian": false,
        "calculate_date": null,
        "coupon_type": 1,
        "events_count": 1,
        "events_data": [
          {
            "id": 912,
            "game_id": 737779544,
            "main_game_id": 737779544,
            "is_sub_game": false,
            "parent_game_id": null,
            "sub_game_key": null,
            "raw_pointer": "line#737779544#1#1#0#1.85",
            "line_type": "line",
            "is_live": false,
            "bet_group_id": 1,
            "bet_group_name": "Match result",
            "bet_id": 1,
            "bet_name": "First team to win",
            "sport_id": 1,
            "sport_name": "Football",
            "tournament_id": 10001,
            "tournament": "National League",
            "event_date": 1784971800000,
            "status": 0,
            "opp1": "Team A",
            "opp2": "Team B",
            "coef": 1.85,
            "calc_coef": null,
            "bet_score": "line#737779544#1#1#0#1.85",
            "calculate_date": null,
            "calculate_score": null,
            "settlement_reason_code": null,
            "settlement_reason": null,
            "placement_score_full": null,
            "placement_score_periods": null,
            "calculation_score_full": null,
            "calculation_score_periods": null,
            "timer": null,
            "dop_name": null,
            "rate": "0",
            "sgame_id": null,
            "game_num": null,
            "stat_id": null,
            "team1_id": 101,
            "team2_id": 102,
            "opp_icon1": 101,
            "opp_icon2": 102
          }
        ]
      }
    ]
  },
  "error_code": null,
  "error_message": null,
  "date": 1784970000015,
  "time_ms": 45,
  "path": "/api/partner/coupons/place"
}

优惠券字段

每件商品 body.coupons[] 都是单独创建的优惠券。

投注字段

events_data[] 的每个元素都描述了优惠券中特定的接受投注。

对于尚未计算或不可用的数据，值 null 是正常的。不要自动将其替换为 0 或空字符串。

仅当 code = 1 且 body.coupons 中存在对象时才考虑接受优惠券。在此之前，篮子是一个初步选择：选择可能会消失、被阻止或赔率发生变化。

成功后：

1. 保存所有 body.coupons 对象，而不仅仅是第一个；
2. 将 coupon_code 存储为带有前导零的字符串；
3. 从events_data中保存所需数据；
4. 将优惠券与最终用户相匹配；
5. 在合作伙伴的系统中记录用户的财务交易。

标识符：

完整模型和回调中不返回currency。如果需要货币，请保存创建请求中的值。

对于 501–504，新 API 返回 body.changes[] 中的有问题的费率。字段change_type：1 - 系数已增加，2 - 减少，null - 方向不适用。

超时后不要盲目重试 POST /coupons/place：第一个请求可能已被接受，重试将创建重复的请求。

您可以使用代码传输最多 100 个值：

{
  "coupon_ids": ["000000000272", "000000000273"]
}

或者传递创建周期不超过24小时：

{
  "start_date": 1784880000000,
  "end_date": 1784966400000
}

请勿在同一查询中组合 coupon_ids 和日期。 results 按创建时间过滤，calculated 按最终结算时间过滤。

优惠券状态：

投注状态：

对于最终用户的财务应计，请使用现成的 real_win。请勿使用potential_win，也不要自行重新计算支出。计算前，real_win、calculate_coef、calc_coef、calculate_date 等于null，而不是0。

在优惠券 15 的第一个状态下，如果先前的结果已进行财务处理，则合作伙伴再次从最终用户处借记 amount，期望新的最终状态并收取新的 real_win。保护操作免受再处理。

完整模型和回调中的每个投注都有：

计算前，两个字段均等于null。对于本地化通知，请使用如下代码：

• MATCH_POSTPONED - 比赛已推迟；
• MATCH_CANCELLED - 比赛取消；
• MARKET_PUSH——按照市场规则回报。

如果代码未知，请将其保存并使用非空 settlement_reason 作为后备文本。请勿根据原因 - 使用状态和 real_win 计算支出。

这些字段解释已经执行的计算或返回，并不是比赛状态的单独实时反馈。

回调是可选的。合作伙伴只能通过投票的方式进行工作。对于回调，管理器必须启用该功能并创建callback_secret； URL 会在创建的每张优惠券中发送。

回调URL由合作伙伴自主决定。在生产中应该使用https://；在测试环境中，允许使用http://。

系统发送：

POST {callback_url}
Content-Type: application/json
X-Coupon-Signature: sha256=<hex_hmac_sha256>

短有效负载：

{
  "event": "coupons.settled",
  "batchId": "d407e986f3a64d9d36a77bf532322ef8",
  "couponCount": 1,
  "coupons": [
    {
      "coupon_code": "000000000272",
      "realWin": 18.5,
      "calculate_coefficient": 1.85,
      "status": 2,
      "calculate_date": 1784973600000,
      "events_data": [
        {
          "uuid": "912",
          "status": 1,
          "calculate_coefficient": 1.85,
          "calculate_date": 1784973600000,
          "calculate_score": "2:1",
          "settlement_reason_code": "REMOTE_WIN",
          "settlement_reason": "Win",
          "timer": 0
        }
      ]
    }
  ]
}

强制性规则：

1. 在 JSON 解析之前从正文的确切源字节计算 sha256=<hex(HMAC-SHA256(raw_body, callback_secret))> 并以安全的方式比较签名；
2. 处理所有商品coupons，包裹最多可包含100张优惠券；
3. 使用唯一索引存储 batchId ；
4. 重复batchId不应重复借记或应计；
5. 一个coupon_code在渐进计算和重新计算时可以配备不同的batchId；
6. 只有在整个数据包被安全存储后才返回 HTTP 200。

最小成功响应是空 HTTP 200。高级：

{
  "success": true,
  "processed": 1
}

processed 必须等于 couponCount。响应 201、202 和 204 不被视为成功。

仅在超时、传输错误或 HTTP 500、502、503、504 的情况下执行重播：立即，然后在 1、5、15 和 60 分钟后 - 发送不超过 5 次。对于带有 success: false 或部分 processed 的 HTTP 200 没有自动重试。

即使有回调，也要定期检查结果：

GET /api/partner/coupons/calculated?time=10

休息时间超过 120 分钟后，可在保存的 coupon_ids 或创建时间长达 24 小时内使用 POST /api/partner/coupons/results。再次接收相同的状态不应重复金融交易。

• 仅在服务器上存储登录名、密码、JWT 和 callback_secret；
• 不要在 URL 中传递 JWT，也不要将完整令牌写入日志中；
• 使用小数类型表示货币；
• 将 coupon_code 存储为字符串；
• 保存amount、所需的投注数据和currency（如果使用）；
• 区分优惠券和投注状态；
• 接受未知字段和原因代码，不会出现错误；
• 使所有最终用户金融交易幂等。

继续支持旧路由，但新集成必须使用 /api/partner/**。旧的答案和错误有不同的格式。要更新现有客户端，请使用单个文件“从旧 API 迁移”。

Cashout 正在开发中，尚未经过充分测试，不建议用于生产。

• 收到BASE_URL、登录名和密码。
• JWT 作为承载令牌传输。
• 指针取自该行，未经修改。
• 仅在 code = 1 之后，购物车才会保存为接受的优惠券。
• 已处理 multi、累加器限制和错误 501–507。
• 已考虑客户余额的自动借记。
• 所有 coupon_code 和投注 ID 均已保存。
• 最终支出取自real_win。
• 根据源字节检查回调并使用 batchId 进行重复数据删除。
• 备份轮询已配置。
• 用户余额与客户余额SportAPI是分开的。

详细文档以API概述开始。完整的端点映射在手册中。