الاحتمالات والمراهنات وقسائم اللعب — الوثائق الفنية لواجهة API

• واجهة برمجة تطبيقات URL الأساسية؛
• تسجيل الدخول إلى حساب العميل وكلمة المرور؛
• عند استخدام رد الاتصال - قم بتمكين الوظيفة والعبارة السرية 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: معرف اللاعب الاختياري؛
• المحددات # و| مدعومة.

لا تجمع المؤشر أو تصححه يدويًا - قم بتمرير القيمة التي تم الحصول عليها من السطر دون تغيير.

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. حساب sha256=<hex(HMAC-SHA256(raw_body, callback_secret))> من بايتات المصدر الدقيقة للنص قبل تحليل JSON ومقارنة التوقيعات بطريقة آمنة؛
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 دقيقة - بما لا يزيد عن خمس عمليات إرسال. لا توجد إعادة محاولة تلقائية على HTTP 200 باستخدام success: false أو processed الجزئي.

حتى مع رد الاتصال، تحقق بشكل دوري من النتائج:

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

بعد استراحة لأكثر من 120 دقيقة، استخدم POST /api/partner/coupons/results على coupon_ids المحفوظة أو فترات الإنشاء التي تصل إلى 24 ساعة. إن الحصول على نفس الثروة مرة أخرى لا ينبغي أن يكرر المعاملات المالية.

• تخزين تسجيل الدخول وكلمة المرور وJWT وcallback_secret فقط على الخادم؛
• لا تمرر JWT في عنوان URL ولا تكتب الرمز المميز الكامل في السجلات؛
• استخدام النوع العشري مقابل المال؛
• قم بتخزين coupon_code كسلسلة؛
• حفظ amount، وبيانات العطاء المطلوبة وcurrency، في حالة استخدامها؛
• التمييز بين حالات القسيمة وعروض الأسعار؛
• قبول الحقول غير المعروفة ورموز الأسباب دون أخطاء؛
• جعل جميع المعاملات المالية للمستخدم النهائي غير فعالة.

يستمر دعم المسارات القديمة، ولكن يجب أن تستخدم عمليات التكامل الجديدة /api/partner/**. الإجابات والأخطاء القديمة لها تنسيقات مختلفة. لتحديث عميل موجود، استخدم ملفًا واحدًا “الترحيل من واجهة برمجة التطبيقات القديمة”.

Cashout قيد التطوير، ولم يتم اختباره بالكامل ولا يوصى بإنتاجه.

• تم استلام BASE_URL وتسجيل الدخول وكلمة المرور.
• يتم إرسال JWT كرمز مميز لحامله.
• يتم أخذ المؤشرات من السطر دون تعديل.
• يتم حفظ سلة التسوق كقسيمة مقبولة فقط بعد code = 1.
• تمت معالجة multi، والقيود والأخطاء السريعة 501–507.
• وقد تم أخذ الشطب التلقائي لرصيد العميل بعين الاعتبار.
• يتم حفظ جميع معرفات coupon_code ومعرفات العطاءات.
• يتم أخذ العائد النهائي من real_win.
• يتم التحقق من رد الاتصال مقابل وحدات البايت المصدر وإلغاء تكراره باستخدام batchId.
• تم تكوين الاقتراع الاحتياطي.
• رصيد المستخدم منفصل عن رصيد العميل SportAPI.

تبدأ الوثائق التفصيلية بـ نظرة عامة على واجهة برمجة التطبيقات. خريطة نقطة النهاية الكاملة موجودة في يدويًا.