دليل SMM API: ربط الطلبات وإدارة المفاتيح

واجهة تسويق مصر تستخدم POST https://smmegy.com/api/v2 لإدارة الخدمات والطلبات من خادم تطبيقك. تدعم جسم JSON أو form-data، وتعيد بيانات JSON. لا تضف /ar أو /en إلى عنوان API. قراءة التوثيق المرجعي ضرورية إلى جانب هذا الدليل؛ فهو يوضح الحقول التفصيلية لكل نوع خدمة.

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

أنشئ مفتاحًا واحتفظ به على الخادم

يتطلب إصدار المفتاح حساب عميل موثق البريد. أنشئه من إدارة مفاتيح API، واختر الصلاحيات اللازمة ومدة الصلاحية؛ يظهر المفتاح الكامل مرة واحدة عند إنشائه. خزّنه في متغير بيئة أو مخزن أسرار على الخادم، ولا تضعه في JavaScript المتصفح أو رابط URL أو مستودع الكود.

الصلاحيات وتدوير المفاتيح

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

POST /api/v2
Authorization: Bearer YOUR_SERVER_SIDE_API_KEY
Content-Type: application/json

YOUR_SERVER_SIDE_API_KEY عنصر تعليمي؛ استبدله بالمفتاح من مخزن خادمك دون نشره.

الإجراءات التي تدعمها الواجهة

action	البيانات الأساسية	الصلاحية
services	cursor وlimit اختياريان	services
balance	لا حقول إضافية	balance
add	service وidempotency_key وحقول نموذج الخدمة؛ coupon اختياري	orders:write
status	order أو orders	orders:read
refill	order وidempotency_key	orders:actions
cancel	order وidempotency_key	orders:actions
refill_status	order	orders:actions

يعيد balance الرصيد المتاح والعملة. لا يوجد إجراء quote ضمن هذه القائمة؛ لا تبنِ استدعاء غير موثق اعتمادًا على اسم مستخدم في جزء آخر من الموقع.

اقرأ الكتالوج ونموذج الخدمة أولًا

أرسل طلبًا مثل:

{"action":"services","cursor":0,"limit":100}

الرد قائمة خدمات تتضمن service وtype وrate وcurrency وحدود الكمية وorder_form. يكون limit من 1 إلى 1000؛ وللصفحة التالية، استخدم آخر معرّف service مستلم كقيمة cursor. توقف عندما تصبح القائمة فارغة، وتجنب افتراض ثبات الأسعار أو البيانات بين القراءات.

داخل order_form، افحص supported وorderable، واقرأ blocked_reason إذا تعذر الطلب. استخدم fields وخصائص required وrequired_when وchoices وmin وmax لبناء النموذج. أرسل الحقول مباشرة في جسم add؛ لا تجمعها داخل حقل options.

النوع يحدد الحقول والكمية

نوع الخدمة	الحقول أو السلوك الأساسي
Default	link وquantity، مع حدود الخدمة
Package	link؛ لا ترسل quantity، والسعر للباقة كاملة
Custom Comments / Custom Comments Package	link وcomments مفصولة بأسطر؛ عدد السطور أو الباقة حسب النوع
Comment Replies / Comment Likes	username مع الرابط؛ comments للردود وquantity للإعجابات
Mentions Custom List	link وusernames بأسطر؛ تُحسب الكمية من الأسماء
أنواع الإشارات الأخرى	الحقول المناسبة من username أو usernames أو hashtag أو hashtags أو media بحسب النموذج
Invites from Groups / Poll / SEO	الحقل الإضافي groups أوanswer_number أوkeywords بحسب النوع
Web Traffic	country وdevice وtype_of_traffic؛ حقول شرطية حسب مصدر الزيارة
Subscriptions	username وmin وmax وposts وdelay؛ old_posts وexpiry اختياريان

الجدول تلخيص للنموذج، وليس إذنًا لاستخدام طريقة تخالف قواعد المنصة. اقرأ المرجع الكامل لحقول كل نوع. rate_basis=per_1000 يعني سعر كل ألف، وpackage يعني سعر الباقة. وإذا كان drip=true، تدعم الخدمة runs وinterval بالدقائق، وتصبح الكمية المحاسبية quantity × runs.

الاشتراك لمتابعة المنشورات محدود: يجب أن يكون posts من 1 إلى 365، وألا يتجاوز مجموع posts + old_posts العدد 365. تُحدد ميزانية الكمية باستخدام max × (posts + old_posts)؛ الميزانية المحجوزة ليست عددًا منفذًا. استخدم خيارات delay المعادة بدل اختراع قيمة.

أنشئ طلبًا بمعرّف ثابت للعملية

هذا مثال بنيوي لخدمة Default؛ الرقم والرابط والكمية توضيحية، ويجب استبدالها بخدمة قابلة للطلب وهدف مأذون وحدودها الحالية. لا يمثل المثال خدمة محددة في الكتالوج.

curl --request POST 'https://smmegy.com/api/v2' \
  --header "Authorization: Bearer ${SMMEGY_API_KEY}" \
  --header 'Content-Type: application/json' \
  --data '{"action":"add","service":123,"link":"https://www.instagram.com/p/REPLACE_WITH_OWNED_POST/","quantity":100,"idempotency_key":"demo-order-2026-0001"}'

SMMEGY_API_KEY متغير بيئة على الخادم؛ لا تستبدله بمفتاح داخل نص منشور. استخدم مرجعًا فريدًا لكل عملية طلب مقصودة. يقبل idempotency_key الخاص بـadd من 8 إلى 128 حرفًا من الحروف اللاتينية والأرقام و._:-.

عند انقطاع الاتصال، أعد نفس المفتاح المرجعي ونفس البيانات للحصول على الطلب نفسه إذا كان قد أُنشئ. تغيير البيانات مع المرجع نفسه يُرفض. لا تولّد مرجعًا جديدًا آليًا لكل محاولة؛ فقد يؤدي ذلك إلى طلب آخر. احتفظ ببيانات العملية ومعرّفها على خادمك لتستطيع المطابقة بعد إعادة التشغيل.

افصل الإنشاء عن التنفيذ

يرجع add حقول order وpublic_id وcharge وcurrency. إنشاء الطلب يضعه في queued ويحجز الرصيد؛ الرد الناجح ليس إثبات تنفيذ. تظهر حالة active بعد قبول التنفيذ، بينما تعني completed اكتمال الطلب المسجل. لا تعرض رسالة «تم التنفيذ» بمجرد استلام معرّف.

للمتابعة أرسل {"action":"status","order":12345} مع معرّف الطلب الحقيقي. ولعدة طلبات، استخدم orders كسلسلة مفصولة بفواصل، بحد أقصى 100 معرّف. يعيد الرد الحالة والمبلغ والعملة وremains وreserved وrefunded وsettlement_review؛ المبالغ نصوص عشرية، فتعامل معها بدقة عشرية.

لا تكشف المتابعة طلبات حساب آخر. وعندما تكون settlement_review=true في اشتراك محدود، لا تستنتج اكتمال التسوية من مؤشرات المنصة؛ تابع السجل حتى تحديث الحالة. refill وcancel مرتبطان بإتاحة الخدمة وحالة الطلب. أما refill_status فيعيد أحدث سجلات إجراءات الطلب، حتى عشرة سجلات، وقد تشمل التعويض والإلغاء؛ استلام سجل إجراء لا يثبت إكماله.

تعامل مع الأخطاء وإعادة المحاولة

افحص حالة HTTP وجسم JSON معًا؛ بعض النتائج مثل «الطلب غير موجود» تأتي في حقل error داخل رد ناجح HTTP. 401 يعني مفتاحًا غير صالح، و403 صلاحية غير كافية، و422 إجراءً أو بيانات غير مقبولة، و413 جسم طلب أكبر من الحد. الحد الكلي للجسم 65,536 بايت، حتى إذا سمح تعريف حقل بعدد أحرف أكبر.

429 يتعلق بحدود الاستخدام أو محاولات المصادقة، و503 بعدم إتاحة الواجهة مؤقتًا. احترم Retry-After عندما يظهر، واستخدم تراجعًا تدريجيًا مع تنويع توقيت المحاولات وحد أقصى لها. لا تكرر أخطاء الصلاحيات والبيانات دون تصحيحها. الافتراضي لكل مفتاح 60 طلبًا في الدقيقة و10,000 يوميًا، ويمكن للإدارة تغييره؛ مهلة إعادة المحاولة لا تعني انتهاء الحصة اليومية.

اجمع الاستعلام عن الحالات عندما يناسب ذلك، وحدّث الكتالوج دون استدعائه مع كل عنصر واجهة. احتفظ فقط بمعرّفات الخدمة والطلب والمعلومات اللازمة للمتابعة؛ لا ترسل كلمات مرور العملاء أو معلومات البطاقات. عند طلب مساعدة، أرفق رمز الخطأ والمعرّف بعد إزالة المفتاح والبيانات غير الضرورية عبر البريد أو تليجرام، أو راجع صفحة التواصل.