SportApi
APIドキュメント

ベットおよびクーポン計算の システム統合

このシステムは、ベット計算とクーポン管理プロセスの自動化を目指すスポーツベッティングオペレーター、ブックメーカー、およびプラットフォーム開発者向けに設計されています。結果計算の迅速な統合を可能にし、クーポンステータス(勝ち、負け、払い戻し)に関する正確なデータを提供し、オペレーターのサーバーと計算システム間の相互作用を簡素化します。

POST /v1/coupon json
{
  "coupon_id": "A7F3K9",
  "type": "express",
  "events": [
    { "id": 88213, "pick": "1", "odds": 2.10, "result": "win" },
    { "id": 88150, "pick": "over_2_5", "odds": 1.80, "result": "win" }
  ],
  "total_odds": 3.78, "status": "won"
}

システムはどのように機能しますか?

オッズおよび結果の計算システムはどのように機能しますか?

当社のベットおよびクーポン計算システムとの統合は、次の3つの主要な段階で構成されています:

ステップ 1: 認証

最初の段階では、システムでの認証が必要です。これは、ユーザー資格情報(ログイン名とパスワード)を使用した POSTリクエスト を実行することによって行われます。認証が成功すると、Cookie として表されるセッションが返されます。このCookieは、システム内のユーザーのセッションを識別するために使用されるため、その後のすべてのリクエストで送信する必要があります。

ステップ 2: ベットの送信

この段階では、以下を含むベットコードが当社のシステムに送信されます:

  • イベントに対応する 試合ID
  • 選択された結果(チームの勝利、ハンディキャップ、合計など)を表す ベットコード
  • 送信時に有効な ベットオッズ

データを送信する際は、認証時に取得した Cookie を含める必要があります。これにより、適切なユーザー識別とベット処理が保証されます。

ステップ 3: 結果の受信

結果またはクーポンが計算された後、当社のシステムは指定された remote_hostPOSTリクエスト を送信します。このリクエストには以下が含まれます:

  • クーポンステータス(勝ち、負け、または払い戻し)。
  • クーポンに含まれる すべての結果のステータス

結果は、結果が確定するとすぐに送信されます。例えば:

  • ベットが中間結果(ハンディキャップ2.5で、3点目が得点された場合など)に行われた場合、計算は試合中に実行されることがあります。
  • ベットが最終結果(チームの勝利など)に対するものである場合、ステータス情報は試合終了直後に送信されます。

それでは、各ステップを個別に確認しましょう。リクエスト、パラメータ、およびAPIレスポンスについて詳細に説明しています。

ユーザー認証

ログイン名、パスワード、およびリクエスト送信用のホストはマネージャーから取得できます。

リクエスト URL:

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

データ送信タイプ: POST

送信データ:

パラメータ説明
loginユーザーログイン名
passwordユーザーパスワード

重要!

  • 認証中、レスポンスには Cookie が含まれます。この Cookie を保存し、その後のリクエストで送信する必要があります。

簡単な統合のための推奨事項:

  • login フィールドが文字列として渡されていることを確認してください。
  • Cookieの正しい保存と送信を確認してください。これはその後のリクエストの実行に影響します。
  • エラーの場合、リクエストは空のオブジェクトを返します。このシナリオを適切に処理するようにしてください。

Cookie は3ヶ月間有効です。ただし、サーバーが再起動された場合はリセットされることがあります。したがって、クーポンの保存中にエラーが発生した場合は、再認証する必要があります。

エラーレスポンス json
"errorCode":1,
"fullErrorCode":99,
"errorMessage":"Invalid access level"

リクエスト送信の例(マネージャーから提供されたデータを使用してください):

レスポンス例:

成功:

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

失敗:

{"d":{}}

レスポンスフィールドの説明:

フィールド説明
UserId一意のユーザー識別子
dレスポンスのルートオブジェクト

一般的な推奨事項:

  • 最初のリクエストの前に、ユーザーが正しい資格情報を入力したことを確認してください。
  • 認証失敗の理由(ログイン名またはパスワードの誤りなど)をユーザーに表示するためのエラー処理を設定します。
  • 分析と監視のために、成功した試みと失敗した試みの両方をログに記録します。

Cookieを保存し、その後のリクエストで送信する必要があります。

POST {APIHOST}/WebServices/BCService.asmx/LogIn/ python
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)

ベットまたはクーポンの送信メソッド

ベットを送信するには、認証段階で取得したCookieを使用する必要があります。これらのデータは、セッションを識別し、リクエストを処理するために必要です。

リクエスト URL:

{HOST_API}/bet/place/
ペイロード本体の例 json
{
    "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"
    }
}

remote_host および rate_mode パラメータ

フィールドの説明

パラメータ説明
list_betsベットコードとオッズ。形式: "event_type#match_ID|bet_code#odds"。例: "live#579216393|1|1|0#2.1"
realAmountベット額。文字列として渡す必要があります(例: "150")。
currencyクーポンの通貨。
langベットとクーポンが保存される言語(例: "ja", "en", "ru")。
remote_hostクーポンの計算結果を送信するURL。末尾のスラッシュは含めないでください。
rate_modeオッズ変更時のクーポン受け入れの処理オプション: "reject" (変更時に拒否) または "accept" (変更に関係なく受け入れ)。デフォルト: "accept"。

注意: パラメータが正しい形式で渡されていることを確認してください。例えば、list_bets は、ベットが1つだけの場合でも配列でなければなりません。

当社はベット額の検証を行いません。実際のベット額または任意の数値のどちらでも送信できます。これは、財務データの機密性を確保するためです。当社のタスクは計算結果を提供することです。プレイヤーへの勝利金の付与は貴社の責任となります。

ベット送信に必要なパラメータ:

  • 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

重要: リクエストを送信する際、当社のシステムは指定された remote_host に自動的に /api/bet/result という文字列を追加します。したがって、リクエスト受信の最終アドレスは 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 パラメータは、オッズが変更されたときのシステムの動作を定義します。2つの値を取ることができます:

  • 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試合日

ベット送信のエラー説明

ベット送信時にさまざまなエラーが発生することがあります。サーバーレスポンスには3つの主要なフィールドが含まれています:

  • errorCode: リクエストの主要ステータス。
  • fullErrorCode: エラーの詳細。
  • errorMessage: エラーのテキスト説明。

操作成功

操作成功 json
{
  "errorCode": 0,
  "fullErrorCode": 0,
  "errorMessage": ""
}

エラーコード

ベットが正常に受け入れられた場合、サーバーは成功レスポンスを返します(上記参照)。クーポンは受け入れられ、エラーはありません。

エラーが発生した場合、サーバーは一般エラーレスポンスを返します(上記参照)。発生した可能性のあるエラーのいずれかです。以下は、エラーコードとメッセージです。

発生し得るエラーコードと説明

エラーコード (fullErrorCode)エラーメッセージ (errorMessage)説明
1error_wrong_bet_data不正確なベットデータ。list_bets パラメータと他の必須フィールドを確認してください。
1error_block_bet_dataベットは一時的にブロックされており、受け入れることができません。
1error_repeat_bet_data1つの試合から同じ結果への重複ベットは許可されていません。
2label_change_rateオッズが変更されました。指定されたオッズと現在のオッズの不一致により、クーポンが拒否されました。
3error_exist_bet指定されたベット結果はもう存在しません。データの正確性を確認してください。
99Invalid access levelユーザーにはこの操作を実行する権限がありません。Cookieがないか、アカウントがブロックされているため、再認証が必要である可能性が高いです。
99Error exist remote host!remote_host パラメータが不正であるか、欠落しています。サーバー設定を確認してください。

エラー処理に関する推奨事項

  • 入力データの検証: すべての必要なパラメータが正しく提供されていることを確認してください。list_bets の形式とすべての必須フィールドの存在を確認します。
  • オッズの操作: rate_mode = reject を使用している場合、オッズ変更に関連するエラー(label_change_rate)を処理します。
  • サーバー設定: remote_host パラメータに貴社サーバーが正しく指定されていることを確認してください。
  • エラーログ: デバッグとサポートとの対話を簡素化するために、すべてのエラー(errorCode, fullErrorCode, errorMessage)をログに記録します。
  • 致命的なエラーへの対処: レベル 99 のエラーが発生した場合は、アクセス権限とAPI設定を確認してください。
一般エラー json
{
  "errorCode": 1,
  "fullErrorCode": [ERROR_CODE],
  "errorMessage": "[ERROR_DESCRIPTION]"
}

オッズが変更された際のエラー処理に関する推奨事項

オッズが変更された際のエラー処理に関する推奨事項 json
{
    "errorCode":1,
    "fullErrorCode":2,
    "errorMessage":"Odds have changed",
    "rate_mode":"reject",
    "changed":[
        {
            "gid":"586464528", // match ID
            "rb":2.15, // odds in your coupon
            "rg":"2.27", // current real odds
            "rt":0 // status of change. 0 - decreased, 1 - increased
        }
    ]
}

計算結果の送信

ベットがシステムに追加され、計算されると、クーポンの結果を貴社サーバーに送信します。これには以下が含まれます:

  • クーポンの結果(完全な計算)。
  • クーポンステータス(勝ち、負け、払い戻し)。

リクエストは、remote_host パラメータで指定したアドレスに送信されます。このアドレスには、自動的に /api/bet/result という文字列が追加されます。貴社サーバーがこのパスでデータを受信できるように設定されていることを確認してください。

最終アドレスの例:

remote_host = https://mysite.com を指定した場合、データは https://mysite.com/api/bet/result に送信されます。

単一クーポンのデータ例 json
{
    "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 — 1つ以上の結果が変更された係数(1.00)で計算されました。
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データを受け入れる準備ができている必要があります。
複数クーポンのデータ例 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"
    }]
}