API وبيانات الدخول

افصل الصلاحيات#

تراخيص الخادم وصلاحيات الحساب ورموز الرفع مختلفة. تنتهي رموز الرفع وتسمح بالأدلة فقط، لا إدارة اللوحة.

معالجة الأخطاء#

تجنب حلقات المحاولة السريعة عند الأخطاء والحدود. لا تكرر تلقائيًا كتابة مالية مجهولة النتيجة. لا تنشر ترويسات المصادقة في الروابط أو العميل أو السجلات.

مطابقة الواجهة وبيانات الاعتماد والصلاحية#

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

يعرض المثال رؤوس الطلب فقط. النص البديل ليس مفتاحاً صالحاً، والمورد يصنع البروتوكول؛ JSON عشوائي لا يصبح مهمة. احفظ التوثيق بين الخوادم بعيداً عن المتصفح وURL والتحليلات والأخطاء المشتركة.

Authorization: Bearer YOUR_SERVER_LICENSE
Content-Type: application/json

• إدارة الرخصة

تمييز HTTP عن نتيجة المهمة#

يقبل الجسر POST JSON وليس SQL أو جدولاً حراً. pending أو claimed يعني استمرار التنفيذ. افحص النتيجة النهائية قبل إعلان النجاح.

• 401: افحص رخصة الخادم الصحيح وعدم إعادة توليدها.
• 403 bridge_disabled / subscription_inactive / permission_denied: راجع بطاقة Tosun Connect للخادم (bridge_disabled يعني أن الاتصال أُوقف منها) والاشتراك والصلاحية؛ التكرار لا يمنح وصولاً.
• 405 / 415: صحح الطريقة وJSON Content-Type، ولا تكرر JSON غير صالح.
• 429: احترم Retry-After وانتظر؛ يحد الجسر التزامن ويزيد التأخير عند الخطأ.
• 503 / timeout: سجّل وقتاً ومرجعاً منقحين وافحص الاتصال.

• الجسر والأخطاء

الاختبار بأصغر عملية مفيدة#

استخدم خادم اختبار أو شخصية مضبوطة. اقرأ مرة وقارن الشخصية والبيانات باللعبة. العمليات المحددة والصفحات ليست تفريغاً كاملاً للقاعدة. احتفظ بالمرجع لتمييز المهمة عن تكرارها.

سجّل الحالة والمدة ومرجعاً غير سري فقط. احذف الرموز وبيانات اللاعبين من التقارير العامة. أعد الفحص بعد تغيير مفتاح أو صلاحيات أو حزمة.

لا توزع رمزاً إدارياً واحداً لكل التكاملات. استخدم أقل نطاقات لازمة وألغِ غير المستخدم. بعد تغيير واجهة أو صلاحيات اختبر النجاح والرفض مجدداً دون الاعتماد على نتيجة قديمة.

1. افحص نجاح خادمك ورفض مفتاح خاطئ أو ملغى.
2. يجب رفض الموظف بلا صلاحية؛ لا تختبر خوادم عملاء آخرين.
3. اعرض pending وfailed وexpired وdone منفصلة دون نجاح عام.
4. عند unknown_outcome مالي راجع الرصيد المباشر والسجل قبل كتابة جديدة.

• طلبات محدودة
• توافق إطار العمل

افصل طلب المتصفح عن بروتوكول الخادم#

/api/tenant_db_bridge.php يستخدم جلسة الموظف. يتطلب POST وapplication/json و_csrf صالحاً وحساباً للمستأجر الحالي؛ حد الجسم 4096 بايت. action يكون enqueue أو result. إرسال ترخيص لا ينشئ جلسة متصفح. إذن القراءة لا يجيز كتابة المال؛ صلاحية العملية تُفحص مستقلاً.

/api/server_db_bridge.php ينقل صحة المورد واستلام الأعمال ونتائج خادم اللعبة. يستخدم POST JSON وترخيص Bearer بحد 65536 بايت. لا تستبدله بملفات cookie أو CSRF. حدّد المسار أولاً؛ بيانات مسار آخر لا تصلح التفويض. لا تقلّد بروتوكول المورد المدمج بمستند JSON عشوائي.

ميّز قبول الطلب من اكتمال العمل#

قد يعني ok=true قبول HTTP دون إثبات اكتمال إجراء اللعبة. تابع id وoperation وstatus داخل request. pending ينتظر وclaimed استلمه الخادم. done مكتمل وfailed فاشل وexpired انتهى عمره. حافظ على سياق server_id وrequest_id نفسه عند قراءة النتيجة.

افحص الحالة النهائية وerror قبل إعلان النجاح. الطلب المعلق المطابق قد يعيد العمل الموجود؛ هذه ليست ضماناً دائماً لتكرار غير محدود. أوقف كتابة المال عند unknown_outcome. المهلة أو النتيجة غير الصالحة لا تثبت عدم تغير الرصيد. راجع الرصيد الحي والهدف السابق والتدقيق؛ لا تحذف الأدلة لإعادة المحاولة.

اكتب تقريراً تقنياً صغيراً ومنقحاً#

في 405 افحص الطريقة، وفي 415 افحص JSON Content-Type، وفي 400 افحص JSON والحقول المسموحة. في المتصفح يتعلق 401 بالجلسة و419 بالتحقق CSRF؛ أعد الفتح بالتصفح العادي. في 404 راجع السياق دون اختبار عميل آخر. انتظر الأعمال النشطة عند 429.

في 503 أو شبكة غير مؤكدة سجّل الوقت والمسار وحالة HTTP والعملية ومرجعاً غير سري. المثال ملاحظة دعم وليس جسم طلب. استبعد cookie وAuthorization و_csrf والتراخيص وبيانات اللاعبين. أصلح المرحلة المعنية بدل تكرار سريع، وابدأ التحقق بقراءة واحدة مضبوطة.

Endpoint: /api/tenant_db_bridge.php
Method: POST
HTTP status: 419
Error: csrf_failed
Operation: players.list
Reference: YOUR_REQUEST_REFERENCE
Time: YOUR_ERROR_TIME

اقرأ صفحة لاعبين باستخدام جسمَي JSON تم التحقق منهما#

يوضح المثال قراءة الصفحة الأولى للاعبين من متصفح سجّل الدخول بالفعل إلى لوحة حسابك. الخادم 123 ومعرّف الطلب قيمتان افتراضيتان؛ استخدم خادمك وقيمة request.id من رد enqueue. استبدل CURRENT_PAGE_CSRF بالقيمة الصالحة من الصفحة الحالية. هذه ليست رخصة الخادم ولا ينبغي نسخها إلى رسالة الدعم. يلزم POST إلى المصدر نفسه مع application/json وجلسة المتصفح. تتطلب القراءة servers.manage أو players.view، ويُرفض enqueue في وضع العرض التوضيحي للقراءة فقط. لا تستخدم رخصة الخادم بدلاً من تسجيل الدخول في المتصفح.

يرسل الجسم الأول cursor فارغاً فقط؛ تعيد هذه العملية 25 سجلاً كحد أقصى لكل صفحة. لا تضف limit أو SQL أو اسم جدول أو سلسلة اتصال أو معاملات للأموال. إذا كان الرد الأول pending، فاستخدم الجسم الثاني لمتابعة المهمة نفسها بدلاً من إنشاء مهمة أخرى. عند done اقرأ request.result.items. إذا كانت request.result.has_more تساوي true، استخدم request.result.next_cursor عند طلب الصفحة التالية بشكل مقصود. فسّر القائمة الفارغة مع حالة اكتمال ناجح، ولا تعتبر الطلب المعلّق دليلاً على غياب اللاعبين. لا تحتوي القوالب على بيانات سرية صالحة للاستخدام. احصر الاختبار الأول في قراءة واحدة على خادم الاختبار الخاص بك، ولا تستخدم المثال لمنح إضافات متصفح عامة صلاحيات إدارية.

POST /api/tenant_db_bridge.php
Content-Type: application/json

Enqueue:
{
  "_csrf": "CURRENT_PAGE_CSRF",
  "server_id": 123,
  "action": "enqueue",
  "operation": "players.list",
  "params": {"cursor": ""}
}

Result (use request.id from the enqueue response):
{
  "_csrf": "CURRENT_PAGE_CSRF",
  "server_id": 123,
  "action": "result",
  "request_id": "00112233445566778899aabbccddeeff"
}

• جسر MySQL
• الوصول إلى اللوحة والحساب

افصل مهلة HTTP عن مدة المهمة في قائمة الانتظار#

لنفترض أن enqueue قُبل في 14:03:10 وحُفظت request.id، لكن اتصال طلب result اللاحق انقطع. قد يتوقف طلب HTTP واحد في اللوحة بعد 12 ثانية، بينما تنتهي صلاحية المهمة بعد 120 ثانية من إنشائها. إيقاف طلب المتصفح لا يلغي المهمة على الخادم. لذلك لا تعرض «لم يصل رد» بوصفه نتيجة expired أو failed. احتفظ بالمعرّف المعروف واقرأ result باستخدام server_id نفسه بعد عودة الاتصال. تتابع اللوحة عادةً النتيجة المعلّقة كل ثلاث ثوانٍ؛ لا تضف حلقة استعلامات متواصلة. سجّل آخر حالة مؤكدة ولا تستنتج النتيجة من مؤقت محلي.

إذا انتهت قراءة players.list بحالة expired وخطأ request_expired، سجّل الخطأ وأصلح الاتصال ثم ابدأ قراءة جديدة مقصودة. أما player.money.set فقد ينتج unknown_outcome عند انتهاء المدة بعد claimed أو وصول نتيجة غير صالحة؛ وهذا لا يثبت أن الرصيد لم يتغير. أوقف الكتابات الجديدة وافحص الرصيد الحالي وسجل العملية الموجودة. النتائج ليست أرشيفاً دائماً؛ تُحذف السجلات المنتهية لاحقاً ضمن تنظيف محدود. إذا لم يعد السجل موجوداً فلا تحاول تخمين نتيجته بإرسال تغيير مالي آخر. احتفظ للدعم بمرجع غير سري والوقت وoperation وآخر حالة معروفة فقط، من دون ملفات تعريف الارتباط أو قيمة CSRF أو الرخصة.

Illustrative observations; not an API request body:
14:03:10  enqueue accepted; save request.id
14:03:22  HTTP timeout; job outcome is not established
Later     result with the same server_id + request_id

Read:  expired + request_expired -> investigate before a new read
Write: expired + unknown_outcome -> stop writes and reconcile

• جسر MySQL
• الأداء وفترات الانتظار