وثائق واجهة برمجة التطبيقات

تكامل النظام لـ حساب الرهانات وقسائم اللعب

تم تصميم هذا النظام لمشغلي المراهنات الرياضية، ووكلاء المراهنات، ومطوري المنصات الذين يهدفون إلى أتمتة عملية حساب الرهانات وإدارة قسائم اللعب. وهو يتيح دمجاً سريعاً لحسابات النتائج، ويوفر بيانات دقيقة عن حالات قسائم اللعب (فوز، خسارة، أو استرداد)، ويبسط التفاعل بين خادم المشغل ونظام الحساب.

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"
}

كيف يعمل النظام؟

كيف يعمل نظام حساب الاحتمالات والنتائج؟

يتكون التكامل مع نظام حساب الرهانات وقسائم اللعب الخاص بنا من ثلاث مراحل رئيسية:

الخطوة 1: الترخيص

في المرحلة الأولى، تحتاج إلى الترخيص في النظام. يتم ذلك عن طريق إجراء طلب POST باستخدام بيانات اعتماد المستخدم (اسم المستخدم وكلمة المرور). يعيد الترخيص الناجح جلسة ممثلة كـ cookie، والتي يجب حفظها. هذه الكوكيز مطلوبة لجميع الطلبات اللاحقة حيث يتم استخدامها لتحديد جلسة المستخدم في النظام.

الخطوة 2: إرسال الرهان

في هذه المرحلة، يتم إرسال رمز الرهان إلى نظامنا ويحتوي على:

معرّف المباراة، المقابل للحدث.
رمز الرهان، الذي يصف النتيجة المحددة (مثل فوز الفريق، الإعاقة، أو الإجمالي).
احتمالات الرهان، الصالحة في وقت الإرسال.

عند إرسال البيانات، يجب تضمين الكوكيز التي تم الحصول عليها أثناء الترخيص. يضمن هذا تحديد هوية المستخدم ومعالجة الرهان بشكل صحيح.

الخطوة 3: تلقي النتائج

بعد حساب النتائج أو قسائم اللعب، يرسل نظامنا طلبات POST إلى عنوان remote_host المحدد. يتضمن هذا الطلب:

حالة قسيمة اللعب (فوز، خسارة، أو استرداد).
حالات جميع النتائج المشمولة في قسيمة اللعب.

يتم إرسال النتائج بمجرد تحديد النتيجة. على سبيل المثال:

إذا تم وضع الرهان على نتيجة متوسطة (مثل الإعاقة 2.5، وتم تسجيل الهدف الثالث)، فقد يتم إجراء الحساب أثناء المباراة.
إذا كان الرهان على النتيجة النهائية (مثل فوز الفريق)، فسيتم إرسال معلومات الحالة فور انتهاء المباراة.

الآن راجع كل خطوة على حدة. لقد وصفنا الطلبات والمعلمات واستجابات واجهة برمجة التطبيقات بالتفصيل.

ترخيص المستخدم

يمكن الحصول على اسم المستخدم وكلمة المرور والمضيف لإرسال الطلبات من المدير.

عنوان URL للطلب:

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

نوع إرسال البيانات: POST

البيانات المرسلة:

المعلمة	الوصف
`login`	اسم مستخدم المستخدم
`password`	كلمة مرور المستخدم

هام!

أثناء الترخيص، تتضمن الاستجابة كوكيز (cookies). يجب حفظ هذه الكوكيز وإرسالها مع الطلبات اللاحقة.

توصيات لتسهيل التكامل:

تأكد من تمرير حقل login كسلسلة نصية.
تحقق من حفظ وإرسال الكوكيز بشكل صحيح، لأن هذا يؤثر على تنفيذ الطلبات اللاحقة.
في حالة حدوث خطأ، سيعيد الطلب كائناً فارغاً. تأكد من معالجة هذا السيناريو بشكل مناسب.

تكون الكوكيز صالحة لمدة 3 أشهر. ومع ذلك، قد يتم إعادة تعيينها في حال إعادة تشغيل الخادم. لذلك، تحتاج إلى إعادة الترخيص إذا واجهت خطأ أثناء حفظ القسيمة.

استجابة الخطأ json

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

مثال على إرسال طلب (استخدم البيانات المقدمة من المدير):

مثال على الاستجابة:

ناجحة:

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

غير ناجحة:

{"d":{}}

وصف حقول الاستجابة:

الحقل	الوصف
`UserId`	معرّف المستخدم الفريد
`d`	الكائن الجذري للاستجابة

توصيات عامة:

قبل الطلب الأول، تأكد من قيام المستخدم بإدخال بيانات الاعتماد الصحيحة.
قم بإعداد معالجة الأخطاء لعرض أسباب فشل الترخيص للمستخدم (مثل اسم مستخدم أو كلمة مرور غير صحيحة).
سجل المحاولات الناجحة وغير الناجحة للتحليل والمراقبة.

يجب حفظ الكوكيز وإرسالها مع الطلبات اللاحقة.

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)

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

$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;

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

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));

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

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();

طريقة إرسال الرهان أو قسيمة اللعب

لإرسال رهان، يجب استخدام الكوكيز التي تم الحصول عليها أثناء مرحلة الترخيص. هذه البيانات مطلوبة لتحديد جلستك ومعالجة الطلبات.

عنوان 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`	اللغة التي يتم حفظ الرهان وقسيمة اللعب بها. على سبيل المثال: "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: في هذا الوضع، يرفض النظام قسيمة اللعب إذا تغيرت الاحتمالات. ستتضمن الاستجابة خطأ يخطر بأن الاحتمالات قد تغيرت.

اختر الوضع الذي يناسب عمليات عملك ويوفر الراحة لمستخدميك.

توصيات هامة

تنسيق JSON: تأكد من تسلسل البيانات بشكل صحيح إلى تنسيق JSON قبل الإرسال.
الكوكيز: قم بتضمين الكوكيز التي تم الحصول عليها أثناء الترخيص لتحديد جلسة المستخدم بنجاح.
معالجة الأخطاء: عالج استجابات الخادم، خاصة الحالات التي يتم فيها إرجاع errorCode = 1.
الاختبار: أجرِ اختبارات في جميع مراحل التكامل، بما في ذلك إرسال الرهانات الفردية والمتعددة.

حقول الاستجابة ووصف الأخطاء

حقول الاستجابة

المعلمة	الوصف
`betCode`	رقم الرهان الفريد في نظامنا
`errorCode`	الحالة الرئيسية لنتيجة الطلب
`fullErrorCode`	تفاصيل الخطأ
`errorMessage`	رسائل الخطأ النصية للنظام
`AmountOut`	مبلغ الفوز المحتمل
`CountEvents`	عدد الرهانات في قسيمة اللعب
`Coef`	مؤشرات النتائج
`IsLive`	نوع الرهان: مباشر أو قبل المباراة (true/false)
`LinesId`	معرّف المباراة
`EventDate`	تاريخ المباراة

وصف الخطأ لإرسال الرهان

قد تحدث أخطاء مختلفة عند إرسال الرهان. تحتوي استجابة الخادم على ثلاثة حقول رئيسية:

errorCode: حالة الطلب الرئيسية.
fullErrorCode: تفاصيل الخطأ.
errorMessage: الوصف النصي للخطأ.

عملية ناجحة

عملية ناجحة json

{
  "errorCode": 0,
  "fullErrorCode": 0,
  "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	لا يملك المستخدم الصلاحيات لإجراء هذه العملية. على الأرجح، مطلوب إعادة الترخيص، أو الكوكيز مفقودة، أو الحساب مغلق.
99	Error exist remote host!	معلمة `remote_host` غير صحيحة أو مفقودة. تحقق من إعدادات خادمك.

توصيات لمعالجة الأخطاء

التحقق من صحة البيانات المدخلة: تأكد من تقديم جميع المعلمات المطلوبة بشكل صحيح. تحقق من تنسيق list_bets ووجود جميع الحقول الإلزامية.
العمل مع الاحتمالات: إذا تم استخدام rate_mode = reject، فعليك معالجة الأخطاء المتعلقة بتغيرات الاحتمالات (label_change_rate).
تكوين الخادم: تأكد من تحديد خادمك بشكل صحيح في معلمة remote_host.
تسجيل الأخطاء: سجل جميع الأخطاء (errorCode، fullErrorCode، errorMessage) لتسهيل تصحيح الأخطاء والتفاعل مع الدعم.
الإجراءات للأخطاء الحرجة: في حالة حدوث أخطاء من المستوى 99، تحقق من حقوق الوصول وتكوينات واجهة برمجة التطبيقات من جانبك.

خطأ عام 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 — تم حساب نتيجة واحدة أو أكثر بمعامل متغير.
AmountOut	مبلغ الفوز (إذا فازت قسيمة اللعب).
DateReceive	الوقت والتاريخ اللذين تم فيهما حساب قسيمة اللعب.

كيفية تفسير Status و ExtStatus

Status = 2 و ExtStatus = 0: فازت قسيمة اللعب.
Status = 4 و ExtStatus = 0: خسرت قسيمة اللعب.
Status = 2 و ExtStatus = 1: استرداد. تم حساب قسيمة اللعب بمعامل 1.

نقاط هامة للتكامل

معالجة ExtStatus = 1: قد يحدث هذا إذا تم إلغاء المباراة أو انتهت قبل وقتها. في مثل هذه الحالات، يتم حساب جميع الرهانات بمعامل 1.
المتطلبات التقنية: يتم إرسال الطلبات باستخدام طريقة POST. يجب أن يكون خادمك جاهزاً لقبول بيانات JSON في المسار 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"
    }]
}

تكامل آخر

Sports Line docs Sports Line API Match Results API