توثيق واجهة API

نظرة عامة

يوفّر Toplistbot واجهتَي HTTP. كلتاهما تستخدمان JSON عبر HTTPS وتخصمان من رصيد الرموز نفسه — اختر ما يناسب طريقة الدمج لديك.

واجهة لوحة SMM

نقطة اتصال واحدة متوافقة مع Perfect Panel. إذا كانت لوحتك تتحدث بروتوكول SMM القياسي بالفعل، وجّهها إلى هنا وستعمل دون أي تعديل برمجي.

واجهة المنصة

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

الرابط الأساسي

Base URL

https://backend.toplistbot.com/api

البدء

من حساب جديد إلى حملة قيد التشغيل في خمس خطوات. كل ما يلي يستخدم نقطة اتصال SMM لأنها الأسرع؛ وتعمل واجهة المنصة بالطريقة نفسها بمجرد حصولك على JWT.

أنشئ حسابًا
سجّل حسابًا وفعّل بريدك الإلكتروني. يمنحك التفعيل 100 رمز مجاني في رصيدك، وهو ما يكفي لتشغيل حملة حقيقية قبل أن تنفق شيئًا.
انسخ مفتاح API
افتح لوحة التحكم وأنشئ مفتاح API. تعامل معه كأنه كلمة مرور — فهو ينفق من رصيد الرموز لديك. يمكنك تجديده في أي وقت، وعندها يبطل المفتاح القديم فورًا.
3
ابحث عن الخدمة المطلوبة
اعرض كل المواقع التي يمكنك الطلب عليها. لكل عنصر معرّف خدمة رقمي وسعر بالرموز لكل 1000 إجراء. دوّن معرّف الموقع الذي تريد الترويج عليه.
cURL
```
curl -X POST https://backend.toplistbot.com/api/v2 -d "key=YOUR_API_KEY" -d "action=services"
```
4
أنشئ طلبك الأول
أرسل معرّف الخدمة، والرابط الذي ستعمل عليه الحملة، وعدد الإجراءات المطلوبة. تُخصم التكلفة فورًا، وتتضمن الاستجابة معرّف الطلب.
cURL
```
curl -X POST https://backend.toplistbot.com/api/v2 \
  -d "key=YOUR_API_KEY" \
  -d "action=add" \
  -d "service=9" \
  -d "link=https://arena-top100.com/index.php?a=in&u=yourserver" \
  -d "quantity=1000"
```
5
تابع التنفيذ
استعلم عن معرّف الطلب لمعرفة ما تم تنفيذه. وعندما تطمئن إلى سير العمل، اربط الاستدعاءات نفسها بلوحتك أو بسكربتاتك.
cURL
```
curl -X POST https://backend.toplistbot.com/api/v2 -d "key=YOUR_API_KEY" -d "action=status" -d "orders=184223"
```

ربط Perfect Panel

إذا كنت تستخدم Perfect Panel أو برنامج لوحة SMM متوافقًا، فلا حاجة لكتابة أي كود — أضف Toplistbot كمزوّد بهذه الإعدادات ثم استورد قائمة الخدمات.

رابط API: https://backend.toplistbot.com/api/v2
مفتاح API: YOUR_API_KEY
طريقة HTTP: POST

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

المصادقة

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

مفتاح API (نقطة اتصال SMM)

أرسل مفتاحك في حقل `key` مع كل طلب — كحقل نموذج أو معامل استعلام أو ترويسة `Authorization: Bearer`. يمكنك إنشاؤه وتجديده من لوحة التحكم. ويعيد طلب GET إلى نقطة الاتصال نفسها الحالة ok، وهي طريقة سريعة للتحقق من صلاحية المفتاح.

Health check

curl https://backend.toplistbot.com/api/v2?key=YOUR_API_KEY

‏JWT (واجهة المنصة)

سجّل الدخول للحصول على رمز، ثم أرسله كرمز bearer في المسارات المحمية. تنتهي صلاحية الرموز — استدعِ ‎/auth/refresh للحصول على رمز جديد.

curl -X POST https://backend.toplistbot.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","password":"..."}'

Authenticated request

curl https://backend.toplistbot.com/api/orders/getAll \
  -H "Authorization: Bearer YOUR_JWT"

ينفق مفتاح API من رصيد رموز حقيقي. احتفظ به على الخادم: أي مفتاح يصل إلى المتصفح أو يُرفع إلى مستودع يجب اعتباره مكشوفًا وتجديده من لوحة التحكم.

الرموز والأسعار

تُدفع الحملات بالرموز التي تشتريها مسبقًا. ولكل موقع سعر معلن — عدد الرموز اللازمة لتنفيذ 1000 إجراء عليه — يُعاد في الحقل `rate` ضمن إجراء services.

Cost formula

cost_in_tokens = (rate * quantity) / 1000

موقع سعره 13 يكلّف 13 رمزًا لكل 1000 إجراء، وبالتالي يكلّف طلب من 500 إجراء 6.5 رمز. تُخصم التكلفة عند قبول الطلب، ويعيد الإلغاء ما لم يُستهلك منها.

تشير استجابتا balance وstatus إلى حقل عملة بقيمة USD من أجل التوافق مع Perfect Panel، لكن القيمة هي رصيد رموز وليست دولارات. تعامل مع الرقم على أنه رموز.

واجهة لوحة SMM

نقطة اتصال واحدة تنفّذ كل شيء. أرسل حقل `action` مع كل طلب POST لاختيار العملية؛ ويحمل كل طلب أيضًا قيمة `key` الخاصة بك.

POSThttps://backend.toplistbot.com/api/v2

الإجراء	المعاملات
`services`	—
`add`	service, link, quantity, interval?
`status`	orders
`balance`	—
`cancel`	orders

`action=services`

تعرض كل المواقع التي يمكنك الطلب عليها مع السعر الحالي والحدود. استخدم معرّف `service` في استدعاءات add.

cURL

curl -X POST https://backend.toplistbot.com/api/v2 \
  -d "key=YOUR_API_KEY" \
  -d "action=services"

Response

[
  {
    "service": 9,
    "name": "arena-top100.com 1000 upvotes",
    "type": "Default",
    "category": "Votes",
    "rate": 15,
    "min": 1,
    "max": 50000,
    "refill": false,
    "cancel": true
  }
]

‏`rate` بالرموز لكل 1000 إجراء. وقيمة `min` هي 1 و`max` هي 50000 لكل الخدمات.

`action=add`

ينشئ حملة ويخصم تكلفتها من رصيدك فورًا.

المعامل	النوع	الوصف
`key`مطلوب	string	مفتاح API الخاص بك.
`action`مطلوب	string	يجب أن يكون `add`.
`service`مطلوب	integer	معرّف الخدمة المأخوذ من إجراء services.
`link`مطلوب	url	الرابط الذي ستعمل عليه الحملة. يجب أن يكون رابطًا صالحًا.
`quantity`مطلوب	integer	عدد الإجراءات المطلوب تنفيذها، بين 1 و50000.
`interval`	integer	عدد الإجراءات في الساعة. الافتراضي 15، وبحد أقصى 4000، ولا يمكن أن يتجاوز الحد الأقصى للموقع نفسه.

cURL

curl -X POST https://backend.toplistbot.com/api/v2 \
  -d "key=YOUR_API_KEY" \
  -d "action=add" \
  -d "service=9" \
  -d "link=https://arena-top100.com/index.php?a=in&u=yourserver" \
  -d "quantity=1000" \
  -d "interval=60"

Response

{
  "order_id": 184223
}

`action=status`

يعيد تقدّم طلب واحد أو أكثر. مرّر معرّفًا واحدًا للحصول على كائن مباشر، أو قائمة مفصولة بفواصل.

cURL

curl -X POST https://backend.toplistbot.com/api/v2 \
  -d "key=YOUR_API_KEY" \
  -d "action=status" \
  -d "orders=184223"

Response — single order

{
  "charge": 13.5,
  "start_count": 0,
  "status": "Completed",
  "remains": 1000,
  "currency": "USD"
}

مع عدة معرّفات تُفهرس الاستجابة حسب معرّف الطلب، وتعيد الطلبات المجهولة أو غير التابعة لك مدخل خطأ بدل إفشال الطلب بأكمله.

Response — multiple orders

{
  "184223": { "charge": 13.5, "start_count": 0, "status": "Completed", "remains": 1000, "currency": "USD" },
  "184224": { "error": "Incorrect order ID" }
}

`action=balance`

يعيد رصيدك المتبقي من الرموز.

cURL

curl -X POST https://backend.toplistbot.com/api/v2 \
  -d "key=YOUR_API_KEY" \
  -d "action=balance"

Response

{
  "balance": 528.41,
  "currency": "USD"
}

`action=cancel`

يوقف الطلب ويعيد ما لم يُستهلك إلى رصيدك. ولا يمكن إلغاء الطلبات المكتملة.

cURL

curl -X POST https://backend.toplistbot.com/api/v2 \
  -d "key=YOUR_API_KEY" \
  -d "action=cancel" \
  -d "orders=184223,184224"

Response

[
  { "order": "184223", "cancel": 1, "refund": 4.5 },
  { "order": "184224", "cancel": { "error": "Incorrect order ID" } }
]

واجهة المنصة

هي واجهة REST نفسها التي تستخدمها لوحة التحكم. نقاط اتصال الدليل عامة، وكل ما عداها يتطلب رمز JWT.

الدليل

عامة وبلا مصادقة. مفيدة لبناء دليلك أو صفحة أسعارك الخاصة.

GET/orders/getAllWebsitesكل المواقع المدرجة مع الأسعار والبيانات الوصفية
POST/orders/getWebsiteDetailsByNameموقع واحد بالاسم الدقيق
GET/orders/getAllBasicWebsitesDetails20 اسم موقع عشوائيًا
POST/products/getSuggestionsمواقع ذات صلة بمجموعة معرّفات
GET/products/tokensباقات الرموز المتاحة
POST/products/suggestاقترح موقعًا لإضافته
GET/news/timelineسجل تغييرات المنتج

cURL

curl https://backend.toplistbot.com/api/orders/getAllWebsites

الحساب

التسجيل والجلسات وسجل الفواتير.

POST/auth/registerإنشاء حساب
POST/auth/loginاستبدال بيانات الدخول برمز JWT
POST/auth/refreshإصدار رمز JWT جديد JWT
POST/auth/logoutإبطال رمز JWT الحالي JWT
GET/auth/user-profileملف المستخدم الحالي JWT
POST/auth/reset-api-keyتجديد مفتاح API JWT
GET/invoices/getسجل الفواتير JWT

الحملات

أنشئ الحملات وأدرها واطّلع على سجلات تنفيذها.

GET/orders/getAllحملاتك، الأحدث أولًا
POST/orders/checkoutإنشاء حملة أو أكثر
POST/orders/updateتعديل حملة
POST/orders/pauseإيقاف حملة نشطة مؤقتًا
POST/orders/unpauseاستئناف حملة موقوفة
POST/orders/archiveأرشفة حملة
PATCH/orders/updateLimitتغيير الحد اليومي
GET/orders/logs/{id}سجل تنفيذ حملة
GET/orders/graph/{id}سلسلة زمنية للرسوم البيانية

الأخطاء

تعود الأخطاء برمز حالة HTTP مطابق. وتعيد أخطاء التحقق كائن `errors` مفهرسًا حسب اسم الحقل.

400إجراء غير صالح، أو معاملات غير صحيحة، أو معرّف خدمة غير موجود.
401بيانات اعتماد مفقودة أو غير صالحة.
403تمت المصادقة، لكن رصيد الرموز غير كافٍ للطلب.
422تم فهم الطلب لكنه لم يجتز التحقق.

Validation error

{
  "errors": {
    "quantity": ["The quantity must be at least 1."]
  }
}

الحدود وملاحظات

يجب أن تتراوح كمية الطلب بين 1 و50000 إجراء.
الفاصل الافتراضي 15 في الساعة بحد أقصى 4000. وطلب قيمة أعلى من الحد الأقصى للموقع يُرفض بالخطأ 400 مع بيان الحد.
إجراءا `refill` و`refill_status` غير مطبَّقين — أنشئ طلبًا جديدًا بدلًا من ذلك.
حقل `status` ليس بعد مؤشرًا لحظيًا للتقدّم؛ استخدم `remains` و`start_count` لتتبع التنفيذ.
تضع مواقع الإدراج قواعدها الخاصة وتغيّرها مع الوقت. وأنت مسؤول عن التأكد من توافق استخدامك مع شروط أي موقع تروّج عليه. ولا نَعِد بأي ترتيب أو موضع معيّن.

اسألنا على Discord

نظرة عامة

واجهة لوحة SMM

واجهة المنصة

الرابط الأساسي

البدء

أنشئ حسابًا

انسخ مفتاح API

ابحث عن الخدمة المطلوبة

أنشئ طلبك الأول

تابع التنفيذ

ربط Perfect Panel

المصادقة

مفتاح API (نقطة اتصال SMM)

‏JWT (واجهة المنصة)

الرموز والأسعار

واجهة لوحة SMM

action=services

action=add

action=status

action=balance

action=cancel

واجهة المنصة

الدليل

الحساب

الحملات

الأخطاء

الحدود وملاحظات

ابدأ الترويج الآن!

`action=services`

`action=add`

`action=status`

`action=balance`

`action=cancel`