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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

هام!

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

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

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

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

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

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

ناجحة:

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

غير ناجحة:

{"d":{}}

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

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

توصيات عامة:

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

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

import requests
import json

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

payload = json.dumps({
  "login": "demo-login@demosportapi.net",
  "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":"demo-login@demosportapi.net",
    "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": "demo-login@demosportapi.net",
    "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\":\"demo-login@demosportapi.net\",\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/

{
    "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	اللغة التي يتم حفظ الرهان وقسيمة اللعب بها. على سبيل المثال: "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. الكوكيز: قم بتضمين الكوكيز التي تم الحصول عليها أثناء الترخيص لتحديد جلسة المستخدم بنجاح.
3. معالجة الأخطاء: عالج استجابات الخادم، خاصة الحالات التي يتم فيها إرجاع errorCode = 1.
4. الاختبار: أجرِ اختبارات في جميع مراحل التكامل، بما في ذلك إرسال الرهانات الفردية والمتعددة.

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

المعلمة	الوصف
betCode	رقم الرهان الفريد في نظامنا
errorCode	الحالة الرئيسية لنتيجة الطلب
fullErrorCode	تفاصيل الخطأ
errorMessage	رسائل الخطأ النصية للنظام
AmountOut	مبلغ الفوز المحتمل
CountEvents	عدد الرهانات في قسيمة اللعب
Coef	مؤشرات النتائج
IsLive	نوع الرهان: مباشر أو قبل المباراة (true/false)
LinesId	معرّف المباراة
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	لا يملك المستخدم الصلاحيات لإجراء هذه العملية. على الأرجح، مطلوب إعادة الترخيص، أو الكوكيز مفقودة، أو الحساب مغلق.
99	Error exist remote host!	معلمة remote_host غير صحيحة أو مفقودة. تحقق من إعدادات خادمك.

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

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

{
  "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. يجب أن يكون خادمك جاهزاً لقبول بيانات JSON في المسار remote_host + /api/bet/result.

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