توثيق واجهة API

action=services

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

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

[
  {
    "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

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

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"

{
  "order_id": 184223
}

action=status

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

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

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

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

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

تقبل `status` و`cancel` ما لا يزيد عن 100 معرّف طلب في الاستدعاء الواحد. اجمعها بدل التكرار: استدعاء واحد بمئة معرّف أرخص كثيرًا للطرفين من مئة استدعاء.

action=balance

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

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

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

action=cancel

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

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

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

الفهرس والاستكشاف#

عام ولا يحتاج بيانات اعتماد. ابدأ من getAllWebsites: فهو يحمل المعرّف والسعر والسقف الساعي ومعدل القبول، وهي كل ما تحتاجه لتسعير الطلب وضبط حجمه.

• GET/orders/getAllWebsitesعامالفهرس الكامل: كل موقع مع أسعاره وحدوده وبياناته الوصفية
• GET/orders/getAllBasicWebsitesDetailsعام20 اسم موقع عشوائيًا، للودجات والإكمال التلقائي
• POST/orders/getWebsiteDetailsByNameعامموقع واحد باسمه الدقيق
• POST/products/getSuggestionsعاممواقع مرتبطة بمجموعة من المعرّفات
• GET/products/demand?days=30عاممقدار الطلب على كل موقع مؤخرًا
• GET/products/tokensعامباقات الرموز المتاحة للشراء
• POST/products/suggestمفتاح APIاطلب منا إضافة موقع جديد
• GET/api/news/timelineعامسجل تغييرات المنتج

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

اطلب أقل

الفهرس الكامل نحو 665 كيلوبايت لـ 396 موقعًا، ونصف ذلك الحجم يأتي من حقلين لن تطلب بهما أبدًا: كتلة JSON للشعبية والوصف التسويقي. اقتصر على الحقول التي تطلب بها واستبعد المواقع غير الفعّالة فيصبح نحو 40 كيلوبايت.

# The whole catalog is ~665 KB across 396 sites.
# Projected to what you actually order with: ~40 KB.
curl -s "https://backend.toplistbot.com/orders/getAllWebsites" \
  | jq '[.[]
      | select(.active == 1)
      | {id, name, price_per_1000, max_per_hour, accept_rate, subscribeable}]'

الحساب والجلسات#

يحتاج التسجيل إلى متصفح لأنه محمي بتحدٍّ من Cloudflare. سجّل مرة واحدة على app.toplistbot.com ثم أتمت كل ما بعد ذلك.

• POST/api/auth/registerعامإنشاء حساب — من المتصفح فقط، محمي بكابتشا
• POST/api/auth/loginعاماستبدال بيانات الاعتماد برمز JWT
• POST/api/auth/refreshJWTإصدار رمز JWT جديد من آخر توشك صلاحيته على الانتهاء
• POST/api/auth/logoutJWTإبطال رمز JWT الحالي
• GET/api/auth/user-profileJWTالحساب المسجّل دخوله، مع الرصيد ومفتاح API
• GET/api/userJWTكائن المستخدم نفسه على مسار أقصر
• GET/api/api_tokenمفتاح APIتحديد صاحب مفتاح API — استخدمه للتحقق من مفتاح
• POST/api/auth/reset-api-keyJWTتدوير مفتاح API؛ والقديم يبطل فورًا
• POST/api/auth/fingerprintJWTتسجيل بصمة متصفح على الحساب
• POST/api/auth/ipJWTتسجيل عنوان IP الحالي للحساب
• POST/api/auth/forgot-passwordعامإرسال رابط إعادة تعيين صالح 60 دقيقة
• POST/api/auth/reset-passwordعامتعيين كلمة مرور جديدة بالرمز المرسل بالبريد

التحقق بخطوتين وتسجيل الدخول#

يحمي التحقق بخطوتين تسجيل الدخول بكلمة المرور، ولا ينطبق على مفاتيح API، ولهذا يكون المفتاح خيارًا أفضل للعمل دون إشراف.

• POST/api/2fa/enableJWTبدء التسجيل: يعيد السر ورابط رمز QR ورموز الاسترداد
• POST/api/2fa/verifyJWTتأكيد رمز من ستة أرقام وتفعيل التحقق بخطوتين
• POST/api/2fa/disableJWTإيقاف التحقق بخطوتين
• POST/api/account/verification/requestJWTإرسال رابط تحقق إلى عنوان الحساب
• GET/api/account/verification/confirm?token=عامعرض صفحة التأكيد — لا تكتب شيئًا
• POST/api/account/verification/confirmعامإتمام التحقق
• GET/api/auth/googleعامبدء تسجيل الدخول بجوجل
• GET/api/auth/google/callbackعامعودة تسجيل الدخول بجوجل
• GET/api/auth/discordعامبدء تسجيل الدخول بديسكورد
• GET/api/auth/discord/callbackعامعودة تسجيل الدخول بديسكورد

التفضيلات والتنبيهات#

مفاتيح البريد والإشعارات، وسجل تنبيهات الحساب.

• GET/api/user/email-preferencesJWTحالة الاشتراك في رسائل التسويق
• POST/api/user/email-preferencesJWTتغييرها
• GET/api/user/notification-preferencesJWTتفضيل إشعارات التصويت الحية
• POST/api/user/notification-preferencesJWTتغييره: يجب أن يكون قيمة منطقية JSON حقيقية
• GET/api/user/alerts?limit=20JWTتنبيهات الحساب، الأحدث أولًا، مقسّمة بـ ?before
• POST/api/user/alerts/readJWTوسم تنبيه كمقروء
• POST/api/user/alerts/dismissJWTإخفاء تنبيه
• GET/api/email/unsubscribe?token=عامإلغاء الاشتراك بنقرة واحدة عبر رمز مُرسل بالبريد

الحملات#

أنشئ الحملات ووجّهها أثناء عملها وأنهها. هذا هو قلب واجهة المنصة.

• GET/orders/getAllمفتاح APIحملاتك، الأحدث أولًا، ومعها بيانات مواقعها
• GET/orders/get/{id}مفتاح APIحملة واحدة
• POST/orders/checkoutمفتاح APIإنشاء حملات وخصم قيمتها من الرصيد
• POST/orders/updateمفتاح APIتعديل حملة
• POST/orders/pauseمفتاح APIإيقاف حملة عاملة مؤقتًا
• POST/orders/unpauseمفتاح APIاستئناف حملة موقوفة
• POST/orders/archiveمفتاح APIأرشفة حملة
• POST/orders/unarchiveمفتاح APIاستعادة حملة مؤرشفة
• PATCH/orders/updateLimitمفتاح APIضبط أو إزالة السقف اليومي للأصوات

POST /orders/checkout

الجسم مصفوفة JSON من سطور السلة في المستوى الأعلى، لا كائنًا. كل سطر حملة. تُتحقَّق السلة كاملة قبل أي خصم، والخصم والإدراج معاملة واحدة: فإما أن يتم الطلب كله أو لا يتم أصلًا.

سطر بكمية ثابتة

الحالة المعتادة: تسليم عدد محدد من الأصوات إلى رابط واحد.

curl -X POST "https://backend.toplistbot.com/orders/checkout?key=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "id": 9,
      "amount": 1000,
      "ownName": "https://arena-top100.com/index.php?a=in&u=yourserver",
      "custom_max_per_hour": 60
    }
  ]'

200 OK
Successfully purchased with token balance

سطر اشتراك

للمواقع التي قيمة `subscribeable` فيها 1. يُسعَّر من subscription_price_1d للموقع مضروبًا في عدد الأيام وفي خصم المستوى: Weekly هو 0.90، وMonthly هو 0.80، وأي شيء آخر 1.00. أما الكمية المسلَّمة فتُشتق في الخادم من subscription_speed الخاص بالموقع، فلا شيء ترسله يغيّرها.

[
  {
    "type": "subscription",
    "website": { "id": 9 },
    "subscription_days": 30,
    "tier": { "name": "Monthly" },
    "url": "https://arena-top100.com/index.php?a=in&u=yourserver"
  }
]

الاستجابات

• 200أُنشئت كل السطور وخُصم المبلغ من الرصيد. الجسم نص بسيط.
• 400الجسم لم يكن JSON صالحًا.
• 402الرصيد غير كافٍ. الرسالة تذكر المبلغ المطلوب ولم يُخصم شيء.
• 422سطر أو أكثر غير صحيح. لم يُخصم شيء.
• 429أُرسلت السلة نفسها خلال آخر 60 ثانية. أعد المحاولة بعد المدة المذكورة.

استجابة 422 تسمّي السطر المخالف: تُفهرس الأخطاء بصيغة items.[index].[field]، فسلة فيها ثلاثة سطور خاطئة تُصلَح في جولة واحدة لا في ثلاث.

{
  "errors": {
    "items.2.amount": ["Enter 0 or more votes; a negative amount is not allowed."]
  }
}

POST /orders/update

`id` مطلوب؛ وأرسل فقط الحقول التي تغيّرها. ولا يمكن تعديل طلبات الاشتراك.

curl -X POST "https://backend.toplistbot.com/orders/update?key=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id":184223,"amount_to_do":2000,"custom_name":"EU launch"}'

السقف اليومي

القيمة `type: "delete"` تزيل السقف. ومع ذلك يظل المدقق يطلب `max_votes_per_day` في تلك الحالة: أرسل أي عدد صحيح.

curl -X PATCH "https://backend.toplistbot.com/orders/updateLimit?key=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id":184223,"max_votes_per_day":500,"type":"set"}'

السجلات والتحليلات#

بيانات التسليم، صوتًا بصوت ومجمّعة. تقرأ قاعدة سجلات منفصلة وهي أبطأ من بقية الواجهة: استعلمها كل دقائق لا كل ثوانٍ.

• GET/orders/logs/{id}مفتاح APIسجل تسليم الحملة صوتًا بصوت
• GET/orders/graph/{id}مفتاح APIسلسلة زمنية لحملة واحدة، جاهزة للرسم
• GET/api/orders/graph/summaryJWTسلسلة واحدة تشمل كل حملاتك
• GET/orders/grouped/usernames/{id}مفتاح APIالتسليمات مجمّعة حسب اسم المستخدم المصوّت
• POST/orders/averageمفتاح APIمتوسط التسليم عبر عدة حملات
• GET/api/logs/{id}/filtered-graphJWTسلسلة زمنية مُرشّحة

ملفات التصويت والوكيل#

ملف التصويت هو قائمة مسمّاة بأسماء المستخدمين التي تصوّت بها الحملة. وملف الوكيل هو قائمة دول مسموح بها لعناوين IP المستخدمة. اربط أيًّا منهما بحملة عبر username_profile_id أو proxy_profile_id في /orders/update.

• GET/advanced/profile/getمفتاح APIملفات التصويت الخاصة بك
• GET/advanced/profile/get/{id}مفتاح APIملف تصويت واحد
• POST/advanced/profile/createمفتاح APIإنشاء ملف تصويت، أو الكتابة فوق واحد بالمعرّف
• DELETE/advanced/profile/delete/{id}مفتاح APIحذف ملف تصويت
• GET/advanced/profile/proxy/getمفتاح APIملفات الوكيل الخاصة بك
• GET/advanced/profile/proxy/get/{id}مفتاح APIملف وكيل واحد
• POST/advanced/profile/proxy/createمفتاح APIإنشاء ملف وكيل، أو الكتابة فوق واحد بالمعرّف
• DELETE/advanced/profile/proxy/delete/{id}مفتاح APIحذف ملف وكيل

رموز ديسكورد#

للقوائم التي توثّق المصوّتين عبر ديسكورد. وإضافة الرمز نفسه مرتين تُرفض كنسخة مكررة.

• GET/api/discord-tokensJWTرموز ديسكورد الخاصة بك
• POST/api/discord-tokensJWTإضافة رمز
• GET/api/discord-tokens/statsJWTإحصاءات استخدام رموزك
• GET/api/discord-tokens/{id}JWTرمز واحد
• PATCH/api/discord-tokens/{id}JWTتغيير رمز أو حالة تفعيله
• DELETE/api/discord-tokens/{id}JWTإزالة رمز
• PUT/api/discord-tokens/{id}/toggleJWTتبديل الرمز بين مفعّل ومعطّل

الفوترة والمدفوعات#

شراء الرموز ينتهي دائمًا في صفحة دفع مستضافة، لذا لا يمكن أن يكون الشحن آليًا بالكامل. أما كل ما بعد الشحن فيمكن.

• GET/invoices/getمفتاح APIسجل الفوترة
• GET/api/subscriptions/subscriptionsJWTالاشتراكات الفعّالة
• GET/products/tokensByUserمفتاح APIباقات الرموز بأسعار حسابك
• POST/company/getمفتاح APIعنوان الفوترة الخاص بك
• POST/company/createمفتاح APIضبطه: country وregion وcity وaddress وpostalCode
• GET/api/stripe/checkout?product_id=JWTرابط Stripe Checkout لباقة رموز
• GET/api/stripe/subscription?plan=JWTرابط Stripe Checkout لخطة
• GET/api/stripe/portalJWTرابط بوابة الفوترة في Stripe
• GET/api/stripe/documentsJWTفواتير وإيصالات Stripe
• GET/coinpayments/checkoutمفتاح APIرابط دفع بالعملات الرقمية

السلة المحفوظة#

سلة لوحة التحكم، محفوظة على الخادم لتبقى بعد تغيير الجهاز. لست بحاجة إليها لإنشاء الطلبات: فـ /orders/checkout يستقبل السلة داخل الطلب نفسه.

• GET/api/cartJWTالسلة المحفوظة
• PUT/api/cartJWTاستبدالها
• POST/api/cartJWTاستبدالها، مثل PUT تمامًا
• DELETE/api/cartJWTتفريغها

الواجهات الداخلية#

توجد من أجل Stripe ومجدول المهام وتحدي مكافحة إساءة التسجيل. تُوثَّق بأسرار مشتركة أو تواقيع وليست جزءًا من واجهة التكامل: أُدرجت هنا فقط ليكتمل الجرد.

• POST/api/stripe/webhookأحداث الدفع من Stripe، موثّقة بالتوقيع
• POST/api/jobs/tickتشغيل المهام المستحقة، موثّق بسر مشترك
• POST/api/pow/challengeتحدي إثبات العمل عند التسجيل
• POST/api/logs/updateتتبّع نشاط البريد
• POST/api/order/{email}ينشئ طلبًا على حساب آخر — لقائمة المشرفين فقط
• GET/reset-password/{token}صفحة إعادة تعيين كلمة المرور القديمة المولّدة من الخادم، أُبقيت من أجل الروابط المرسلة سابقًا
• GET/عامفحص الجاهزية

كائن الموقع#

تعيده /orders/getAllWebsites و/orders/getWebsiteDetailsByName، وهو مضمَّن داخل كل حملة تحت المفتاح `website`.

الحقول غير المذكورة هنا تخدم واجهة لوحة التحكم نفسها. اقرأها إن شئت، لكنها ليست جزءًا من عقد التكامل وقد تتغير دون إشعار.

كائن الحملة#

تعيده /orders/getAll و/orders/get/. لاحظ ما هو غائب: لا يوجد حقل للحالة.

الحقول غير المذكورة هنا تخدم واجهة لوحة التحكم نفسها. اقرأها إن شئت، لكنها ليست جزءًا من عقد التكامل وقد تتغير دون إشعار.

هل تعمل؟ هل انتهت؟#

ليس للحملة حقل حالة، لذا تستنتج حالتها من أربعة أعمدة. قيّم الشروط بالترتيب وخذ أول تطابق.

التقدّم والاستردادات#

يعدّ amount_to_do الأصوات المقبولة، ويعدّ amount_done الإرسالات. ولا يُقبل من الإرسالات إلا نسبة accept_rate، فالحقلان بوحدتين مختلفتين وطرح أحدهما من الآخر مباشرة خطأ.

// accept_rate arrives as a STRING, and it is per-site, not global.
const rate = Number(order.website.accept_rate)

// amount_done counts SUBMISSIONS; amount_to_do counts ACCEPTED votes.
// Convert before comparing them.
const delivered = order.amount_done * rate / 100
const remaining = Math.max(order.amount_to_do - delivered, 0)
const percent   = 100 * delivered / order.amount_to_do

// What cancelling right now would put back on your balance:
const refund    = (remaining / 1000) * order.website.price_per_1000

الحساب نفسه يسعّر الإلغاء: فالمبلغ المسترد هو ما لم يُنفق بسعر قائمة الموقع، ما يتيح لك معرفة قيمة إيقاف حملة قبل أن تقرر.