REST API v2

نظرة عامة

هذه هي الواجهة التي يقودها وكيل ذكاء اصطناعي. كل استدعاء فعل واحد يختاره action، فيبحث الوكيل في الكتالوج، ويقرأ السعر والحدود، ثم ينفّذ. ابحث-ثم-نفّذ، مع تأكيد السعر قبل تحرّك أي مال. خادم MCP وCLI يغلّفان هذه الاستدعاءات نفسها؛ هذه الصفحة هي البروتوكول الخام تحتها.

يتبع API الشكل المعتمد على نطاق واسع لـ SMM API v2، فتعمل برمجيات اللوحات والسكربتات وتكاملات الوكلاء الحالية بأقل تعديلات. كل عملية تمرّ عبر نقطة نهاية واحدة وتختار الفعل بمعامل action. الردود JSON. سهلة على سكربت أو نموذج لغوي للتحليل والتسلسل.

نقطة النهاية

POST https://api.socialgo.com/api/v2

المصادقة

المصادقة لكل طلب. بلا جلسة، بلا مصافحة، وهذا بالضبط ما يجعله قابلاً للاستدعاء بواسطة وكيل. أرسل key السرّي في كل استدعاء. اعثر عليه ودوّره في لوحة التحكم تحت الحساب ← API. عامل المفتاح كأنه كلمة مرور: احتفظ به على الخادم، ولا تضعه أبداً في كود العميل أو موجّه وكيل.

صيغة الطلب

أرسل معاملات نموذج application/x-www-form-urlencoded عبر POST. كل رد JSON. معاملان في كل استدعاء:

• key: مفتاح API الخاص بك (مطلوب)
• action: الفعل المراد تشغيله (مطلوب)

صيغة الخطأ

عند الفشل يحمل الرد حقل error برسالة مقروءة، وحالة HTTP تعكس المشكلة (مثل 400 طلب خاطئ، 401 مفتاح غير صالح). شكل واحد متوقَّع، فيستطيع سكربت أو وكيل التفرّع بناءً عليه بلا تخمين.

{
  "error": "Incorrect request"
}

الإجراءات

كل فعل يؤدي مهمة واحدة. يسلسلها الوكيل بالترتيب: services لإيجاد ما يشتري، add لشرائه، status لتتبّعه. استدعاءات القراءة (services وstatus وbalance) تتيح له تأكيد السعر والأموال قبل استدعاءات الكتابة (add وrefill وcancel) التي تنفق شيئاً.

1. سرد الخدمات

الكتالوج الذي يقرؤه الوكيل أولاً: كل خدمة يمكنه طلبها، مع معرّف الخدمة والفئة والسعر (لكل 1000) والحد الأدنى/الأقصى للكمية. يستخدم معرّفات service المُعادة لوضع الطلبات. والسعر لتأكيد التكلفة قبل الإنفاق.

الطلب

key=YOUR_API_KEY
action=services

الرد

[
  {
    "service": 1,
    "name": "Instagram Followers",
    "type": "Default",
    "category": "Instagram",
    "rate": "0.90",
    "min": "50",
    "max": "10000",
    "refill": true,
    "cancel": true
  },
  {
    "service": 2,
    "name": "Instagram Likes",
    "type": "Default",
    "category": "Instagram",
    "rate": "0.40",
    "min": "10",
    "max": "20000",
    "refill": false,
    "cancel": true
  }
]

2. إضافة طلب

استدعاء الكتابة. يضع طلباً لخدمة واحدة. مرّر معرّف service والرابط الهدف link والكمية quantity. يعيد الرد معرّف order الجديد لتتبّعه. لا يشغّله الوكيل إلا بعد تأكيد السعر والحدود.

المعاملات

• service: معرّف الخدمة من سرد الخدمات
• link: رابط المنشور / الملف / القناة
• quantity: عدد الوحدات المراد تسليمها

الطلب

key=YOUR_API_KEY
action=add
service=1
link=https://instagram.com/example
quantity=1000

الرد

{
  "order": 23501
}

3. إضافة طلب · التغذية بالتقطير

يقسّم طلباً واحداً إلى تسليمات أصغر موزّعة على الوقت، لمنحنى أكثر ثباتاً. اضبط runs (عدد التسليمات) وinterval (الدقائق بين كل تسليم). الإجمالي المُسلَّم هو quantity × runs: الحساب الذي يستخدمه الوكيل لتحجيم حملة دون أن تفعله يدوياً.

معاملات إضافية

• runs: عدد دورات التسليم
• interval: الدقائق بين كل دورة

الطلب

key=YOUR_API_KEY
action=add
service=1
link=https://instagram.com/example
quantity=1000
runs=10
interval=60

الرد

{
  "order": 23502
}

4. حالة الطلب

يعيد الحالة الحالية لطلب واحد: الرسم، العدّ الابتدائي، الحالة، الكمية المتبقية، والعملة. هكذا يراقب الوكيل طلباً دون أن تُحدّث لوحة التحكم. وهكذا يرصد انخفاضاً يستحق الإشارة لإعادة التعبئة.

الطلب

key=YOUR_API_KEY
action=status
order=23501

الرد

{
  "charge": "0.90",
  "start_count": "4250",
  "status": "In progress",
  "remains": "200",
  "currency": "USD"
}

قيم status الممكنة: Pending, In progress, Processing, Completed, Partial, Canceled.

5. حالة طلبات متعددة

تحقّق من طلبات كثيرة في استدعاء واحد. مرّر قائمة معرّفات مفصولة بفواصل في معامل orders. الرد مفهرَس بمعرّف الطلب، فيستعلم الوكيل عن حملة كاملة في جولة واحدة بدل استدعاء لكل طلب.

الطلب

key=YOUR_API_KEY
action=status
orders=23501,23502,23503

الرد

{
  "23501": {
    "charge": "0.90",
    "start_count": "4250",
    "status": "Completed",
    "remains": "0",
    "currency": "USD"
  },
  "23502": {
    "charge": "9.00",
    "start_count": "1200",
    "status": "In progress",
    "remains": "500",
    "currency": "USD"
  },
  "23503": {
    "error": "Incorrect order ID"
  }
}

6. إعادة التعبئة

يطلب إعادة تعبئة لطلب تدعم خدمته ذلك (refill: true في سرد الخدمات) ويعيد معرّف إعادة تعبئة لتتبّعه. مرّر order واحداً أو قائمة orders مفصولة بفواصل. فيطلب الوكيل إعادات التعبئة بالجملة بعد أن يُشير فحص الحالة إلى انخفاضات.

الطلب (فردي)

key=YOUR_API_KEY
action=refill
order=23501

الرد

{
  "refill": 4001
}

الطلب (متعدد)

key=YOUR_API_KEY
action=refill
orders=23501,23502

الرد

[
  { "order": 23501, "refill": 4001 },
  { "order": 23502, "refill": { "error": "Refill not available" } }
]

7. الإلغاء

يطلب إلغاء الطلبات التي لم تُعالَج بعد (الخدمات التي بها cancel: true). مرّر قائمة orders مفصولة بفواصل؛ يبلّغ الرد بالنتيجة لكل طلب. هذا التراجع الذي يلجأ إليه الوكيل عندما يُصطفّ شيء بالخطأ.

الطلب

key=YOUR_API_KEY
action=cancel
orders=23501,23502

الرد

[
  { "order": 23501, "cancel": 1 },
  { "order": 23502, "cancel": { "error": "Incorrect order ID" } }
]

8. الرصيد

يعيد رصيد حسابك وعملته. يقرؤه الوكيل لضبط الإنفاق قبل وضع طلب. وتقرؤه لوحتك لعرض الأموال. أرخص استدعاء للتأكد من وجود مال للإنفاق.

الطلب

key=YOUR_API_KEY
action=balance

الرد

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

استدعِه من أي شيء

نقطة نهاية واحدة، معاملات نموذج بسيطة. فيستطيع shell أو مهمة cron أو وكيل قيادتها بنفس الطريقة. إليك طلباً كاملاً موضوعاً من سطر الأوامر:

curl -X POST https://api.socialgo.com/api/v2 \
  -d "key=YOUR_API_KEY" \
  -d "action=add" \
  -d "service=1" \
  -d "link=https://instagram.com/example" \
  -d "quantity=1000"

ملاحظات وأفضل الممارسات

• اقرأ قبل أن تكتب. استدعِ services (أو balance) لتأكيد السعر والحدود والأموال، ثم استدعِ add: نفس ضمانة ابحث-ثم-نفّذ التي تستخدمها لوحة التحكم وخادم MCP فلا شيء يُنفَق دون سعر مؤكَّد.
• خزّن سرد الخدمات مؤقتاً وحدّثه دورياً. المعرّفات والأسعار والحدود تتغيّر.
• تحقّق من الحد الأدنى/الأقصى للكمية قبل إرسال طلب لتجنّب الاستدعاءات المرفوضة.
• استعلم عن الحالة دفعات بنداء الطلبات المتعددة بدل استدعاء لكل طلب.
• أبقِ مفتاحك على الخادم. إن انكشف يوماً، دوّره فوراً من لوحة التحكم.