ملخص سريع
جمعنا للموزعين طريقة الطلب في API v2 القياسية للوحات SMM وقيم action الست وأمثلة الردود ورسائل الأخطاء وحدود الطلبات.
API للوحة SMM طريقة ربط تُرسل بها الطلبات تلقائيًا وتتابع حالتها من لوحة أخرى أو من برنامج صنعته بنفسك. تستخدم 1PANEL PLUS API v2 القياسية للوحات SMM، فإذا كان لديك كود مربوط بلوحة أخرى يكفي تغيير العنوان والمفتاح للربط فورًا. تستخدم API والموقع الخدمات نفسها والسعر نفسه لكل 1,000 والرصيد نفسه.
من يستخدم API للوحة SMM؟
- الموزعون: يعرضون الخدمات في لوحاتهم ويحولون طلبات العملاء تلقائيًا
- الوكالات: يرسلون طلبات عدة قنوات دفعة واحدة في أوقات محددة
- المطورون: يكتبون سكربتات تطلب مع بدء البث أو رفع فيديو جديد
- المشغلون: يجمعون الرصيد وحالة الطلبات في شاشات الإدارة الخاصة بهم
كيف أحصل على مفتاح API؟
بعد إضافة أول شحن أنشئ المفتاح من صفحة مفاتيح API في لوحة التحكم. يظهر المفتاح مرة واحدة فقط لحظة إنشائه، فانسخه فورًا واحفظه في مكان آمن. عند إنشاء مفتاح جديد يتوقف المفتاح السابق عن العمل فورًا، لذلك إذا ظننت أن مفتاحك انكشف فأنشئ مفتاحًا جديدًا بدلًا منه.
كيف أرسل طلبات API؟
تُرسل كل الطلبات عبر POST إلى عنوان واحد هو https://1panelplus.com/api/v2. استخدم ما يناسبك من حقول النموذج (application/x-www-form-urlencoded أو multipart) أو جسم JSON (Content-Type: application/json)، وضع key وaction في كل طلب. كل الردود بصيغة JSON.
مثال على الطلب (حقول نموذج): key=YOUR_API_KEY&action=balance
مثال على الطلب (JSON): {"key": "YOUR_API_KEY", "action": "balance"}
| action | القيم المرسلة معه | القيم المستلمة |
|---|---|---|
| services | لا شيء | قائمة الخدمات |
| add | service، link، quantity أو comments | order (رقم الطلب) |
| status | order واحد أو orders (حتى 100 مفصولة بفواصل) | charge، start_count، status، remains، currency |
| refill | order | refill (رقم إعادة التعبئة) |
| refill_status | refill | status |
| balance | لا شيء | balance، currency |
- action
- services
- القيم المرسلة معه
- لا شيء
- القيم المستلمة
- قائمة الخدمات
- action
- add
- القيم المرسلة معه
- service، link، quantity أو comments
- القيم المستلمة
- order (رقم الطلب)
- action
- status
- القيم المرسلة معه
- order واحد أو orders (حتى 100 مفصولة بفواصل)
- القيم المستلمة
- charge، start_count، status، remains، currency
- action
- refill
- القيم المرسلة معه
- order
- القيم المستلمة
- refill (رقم إعادة التعبئة)
- action
- refill_status
- القيم المرسلة معه
- refill
- القيم المستلمة
- status
- action
- balance
- القيم المرسلة معه
- لا شيء
- القيم المستلمة
- balance، currency
كيف أحصل على قائمة الخدمات عبر services؟
عند إرسال action=services تصلك كل الخدمات المتاحة في مصفوفة. تحتوي كل خدمة على service (رقم الخدمة) وname وtype وcategory وrate وmin وmax وrefill وcancel. rate هو السعر لكل 1,000 (USD)، وإذا كان type هو Package فهو سعر باقة واحدة. refill تكون true إذا كانت للخدمة مدة إعادة تعبئة، وcancel دائمًا false. وتحتوي category على اسم المنصة والفئة معًا، فتنشئ فئات لوحتك كما هي.
مثال على الرد: [{"service": SERVICE_ID, "name": "اسم الخدمة", "type": "Default", "category": "YouTube - اسم الفئة", "rate": "السعر لكل 1,000", "min": "الحد الأدنى للكمية", "max": "الحد الأقصى للكمية", "refill": true, "cancel": false}]
قد تتغير الأسعار والخدمات، لذلك يُستحسن للموزع أن يعيد جلب services على فترات منتظمة ليضبط أسعار لوحته والحد الأدنى والأقصى للكمية.
كيف أرسل طلبًا عبر add؟
أرسل مع action=add كلًا من service (رقم الخدمة) وlink (رابط عام) وquantity (الكمية)، فيُستلم الطلب ويُخصم المبلغ من الرصيد فورًا. قيمة order في الرد هي رقم الطلب، فاحفظه لتستخدمه في status وrefill. يمكن إرسال الطلبات من الحسابات التي أُضيف إليها أول شحن.
- الخدمات العادية: أرسل service وlink وquantity
- خدمات Custom Comments: أرسل comments بدل quantity. تعليق واحد في كل سطر، حتى 500 حرف للسطر، وعدد الأسطر هو الكمية
- خدمات Package: لا حاجة لإرسال الكمية. يُطلب كباقة واحدة
مثال على الطلب: key=YOUR_API_KEY&action=add&service=SERVICE_ID&link=https://www.youtube.com/watch?v=videoid&quantity=1000
مثال على الرد: {"order": ORDER_ID}
كيف أتحقق من حالة الطلب عبر status؟
أرسل مع action=status قيمة order (رقم طلب واحد) لتصلك حالة ذلك الطلب، أو أرسل في orders أرقام الطلبات مفصولة بفواصل لتستعلم عن حتى 100 طلب دفعة واحدة. إذا كنت تدير طلبات كثيرة فالاستعلام المجمع عبر orders يوفر عدد الطلبات كثيرًا.
مثال على الرد (طلب واحد): {"charge": "المبلغ المدفوع", "start_count": "الرقم عند البدء", "status": "In progress", "remains": "الكمية المتبقية", "currency": "USD"}
مثال على الرد (عدة طلبات): {"ORDER_ID_1": {"charge": "...", "start_count": "...", "status": "Completed", "remains": "0", "currency": "USD"}, "ORDER_ID_2": {"error": "Incorrect order ID"}}
| قيمة status | المعنى |
|---|---|
| Pending | استُلم وينتظر البدء أو ينتقل إلى المعالجة |
| In progress | قيد التسليم |
| Completed | سُلّم بالكامل |
| Partial | سُلّم جزء منه وعاد المبلغ المتبقي إلى الرصيد |
| Canceled | تعذرت معالجته وعاد المبلغ كاملًا إلى الرصيد |
- قيمة status
- Pending
- المعنى
- استُلم وينتظر البدء أو ينتقل إلى المعالجة
- قيمة status
- In progress
- المعنى
- قيد التسليم
- قيمة status
- Completed
- المعنى
- سُلّم بالكامل
- قيمة status
- Partial
- المعنى
- سُلّم جزء منه وعاد المبلغ المتبقي إلى الرصيد
- قيمة status
- Canceled
- المعنى
- تعذرت معالجته وعاد المبلغ كاملًا إلى الرصيد
charge هو المبلغ المدفوع مطروحًا منه المبلغ المسترد، فبعد الاكتمال الجزئي أو الإلغاء يظهر المبلغ المستخدم فعلًا مباشرة. تتحدث حالة الطلب تلقائيًا كل دقيقة تقريبًا، لذلك يكفي الاستعلام عبر status بفاصل دقيقة تقريبًا.
كيف أستخدم refill وrefill_status؟
أرسل order مع action=refill لطلب إعادة التعبئة، فيصلك refill (رقم إعادة التعبئة). يُقبل الطلب في الطلبات المكتملة أو المكتملة جزئيًا لخدمة لها مدة إعادة تعبئة، خلال مدة إعادة التعبئة من يوم انتهاء الطلب، عندما لا توجد إعادة تعبئة قيد التنفيذ وقد مرت 24 ساعة على آخر طلب. وعند إرسال refill مع action=refill_status تصلك الحالة، وهي واحدة من Pending أو In progress أو Completed أو Rejected.
أمثلة على الردود: {"refill": REFILL_ID} و{"status": "Completed"}
قواعد إعادة التعبئة مطابقة للموقع. جمعنا الشروط التفصيلية في شرح مدة إعادة التعبئة.
كيف أتحقق من الرصيد عبر balance؟
عند إرسال action=balance يصلك الرصيد الحالي والعملة (USD). إذا كنت موزعًا فتحقق من الرصيد قبل تحويل الطلبات، واضبط تنبيهًا عندما ينخفض الرصيد عن مبلغ معين لتستمر الطلبات دون انقطاع.
مثال على الرد: {"balance": "الرصيد الحالي", "currency": "USD"}
ماذا تعني رسائل أخطاء API؟
تصل الأخطاء بصيغة JSON وفي حقل error جملة باللغة الإنجليزية. لكل جملة سبب محدد، فقارنها كما هي في برنامجك وعالجها.
| قيمة error | المعنى |
|---|---|
| Invalid API key | المفتاح مفقود أو غير صحيح |
| Too many requests | تجاوزت عدد الطلبات في الدقيقة. أعد الإرسال بعد قليل |
| Add funds first | يمكنك الطلب بعد إضافة أول شحن |
| Incorrect service ID | ليس رقم خدمة متاحة |
| Incorrect link | صيغة الرابط غير صحيحة |
| Quantity out of range | الكمية خارج نطاق الحد الأدنى والأقصى للخدمة |
| Incorrect comments | أسطر التعليقات فارغة أو تجاوز سطر 500 حرف |
| Not enough funds on balance | الرصيد أقل من مبلغ الطلب |
| Incorrect order ID | ليس رقم طلب في هذا الحساب |
| Incorrect refill ID | ليس رقم إعادة تعبئة في هذا الحساب |
| Incorrect action | قيمة action ليست واحدة من القيم الست |
- قيمة error
- Invalid API key
- المعنى
- المفتاح مفقود أو غير صحيح
- قيمة error
- Too many requests
- المعنى
- تجاوزت عدد الطلبات في الدقيقة. أعد الإرسال بعد قليل
- قيمة error
- Add funds first
- المعنى
- يمكنك الطلب بعد إضافة أول شحن
- قيمة error
- Incorrect service ID
- المعنى
- ليس رقم خدمة متاحة
- قيمة error
- Incorrect link
- المعنى
- صيغة الرابط غير صحيحة
- قيمة error
- Quantity out of range
- المعنى
- الكمية خارج نطاق الحد الأدنى والأقصى للخدمة
- قيمة error
- Incorrect comments
- المعنى
- أسطر التعليقات فارغة أو تجاوز سطر 500 حرف
- قيمة error
- Not enough funds on balance
- المعنى
- الرصيد أقل من مبلغ الطلب
- قيمة error
- Incorrect order ID
- المعنى
- ليس رقم طلب في هذا الحساب
- قيمة error
- Incorrect refill ID
- المعنى
- ليس رقم إعادة تعبئة في هذا الحساب
- قيمة error
- Incorrect action
- المعنى
- قيمة action ليست واحدة من القيم الست
في طلبات إعادة التعبئة قد تصلك Refill is not available for this service (خدمة دون مدة إعادة تعبئة)، وOrder is not finished yet (طلب لم ينتهِ بعد)، وRefill period has ended (طلب انتهت مدة إعادة تعبئته)، وRefill already requested, try again later (طلب فيه إعادة تعبئة قيد التنفيذ أو لم تمر عليه 24 ساعة).
كم طلب API يمكنني إرسال؟
يمكن لكل مفتاح إرسال حتى 300 طلب في الدقيقة. اجمع استعلامات الحالة في orders بمئة طلب في كل مرة، وأعد جلب قائمة الخدمات عند الحاجة فقط، فيكفيك الحد بسهولة. فمثلًا إذا كان لديك 1,000 طلب قيد التنفيذ تستعلم عنها كلها بـ 10 طلبات مرة في الدقيقة.
كيف يحدد الموزع سعر البيع؟
قيمة rate التي تصلك عبر API هي سعر 1PANEL PLUS لكل 1,000، أما سعر البيع في لوحتك فيحدده الموزع بنفسه. فمثلًا إذا أضفت 25% إلى خدمة rate الخاصة بها $2.00 يصبح سعر البيع $2.50 لكل 1,000، وإذا طلب العميل 4,000 يكون مبلغ البيع $10.00 والمبلغ المخصوم في 1PANEL PLUS هو $8.00. هذه الأسعار أمثلة لتوضيح الحساب.
ما الترتيب المناسب لربط API؟
- اشحن رصيدك وأنشئ مفتاح API من لوحة التحكم
- تحقق من المفتاح والاتصال عبر balance
- اجلب قائمة الخدمات عبر services واعرضها في لوحتك
- أرسل add مرة واحدة بأقل كمية واحصل على رقم الطلب
- تأكد من تغير الحالة عبر status ثم فعّل الطلبات التلقائية
أمثلة curl وPHP وPython وNode.js وشرح كل الحقول في توثيق API، والأسئلة الأخرى في مجموعة API في الأسئلة الشائعة.