الربط عبر REST API خطوة بخطوة

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

عنوان الواجهة الأساسي مكتوب في صفحة «الواجهة البرمجية» تحت ‎/docs/api، ونشير إليه هنا بـ $BASE.

الخطوات

1. 1 أنشئ مفتاحاً من صفحة «الواجهة البرمجية» في لوحتك، وامنحه أضيق الصلاحيات التي تكفي عملك: catalog.read وbalance.read وorders.read وorders.write.
2. 2 اقرأ الكتالوج من GET /v1/catalog. الأسعار الراجعة هي أسعارك أنت، محسوبة على خادمنا من حسابك.
3. 3 تحقّق من رصيدك من GET /v1/balance قبل جولة شراء، إن أردت.
4. 4 أنشئ الطلب بـ POST /v1/orders، ومعه ترويسة Idempotency-Key بقيمة فريدة من عندك — رقم فاتورتك مثلاً.
5. 5 تابع الطلب برقمه من GET /v1/orders/{number} حتى يصير delivered ويحمل الكود.
6. 6 اشترك في الإشعارات بدل الاستقصاء المتكرّر: order.delivered وorder.refunded وwallet.credited.

المفتاح

المفتاح يبدأ بـ mp_live_ ويُعرض مرة واحدة عند إنشائه — لا نحتفظ عندنا إلا ببصمته، فلا يمكننا إظهاره لك ثانية. يُرسل في ترويسة Authorization:

curl "$BASE/catalog?per_page=25" \
  -H "Authorization: Bearer mp_live_..."

إنشاء طلب

curl -X POST $BASE/orders \
  -H "Authorization: Bearer mp_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-invoice-84213" \
  -d '{"sku":"PUBG_MOBILE_60_UC","quantity":1,"player_id":null}'

player_id مطلوب لفئات الشحن المباشر على معرّف اللاعب، ولا معنى له في فئات الأكواد. وقراءة الطلب بعدها برقمه:

curl $BASE/orders/01kzhxexgmfqka0q1zmtr0f292 \
  -H "Authorization: Bearer mp_live_..."

وكل رسالة إشعار موقّعة بترويسة توقيع، تتحقّق منها قبل أن تصدّق الرسالة.

مفتاح Idempotency-Key هو أهم سطر هنا

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

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

الحدود والأخطاء

• السقف الافتراضي ستون طلباً في الدقيقة للحساب ما لم نتّفق على غيره، وكل رد يحمل X-RateLimit-Limit وX-RateLimit-Remaining. وما تجاوزه يعود 429 برمز rate_limited.
• كمية خارج حدود الفئة تعود 422 برمز invalid_quantity ولا يُنشأ طلب.
• الخطأ يعود جسماً موحّداً فيه رمز تقرؤه بالبرمجة، لا نصّاً تحلّله.

طلب تأخّر

الطلب الذي يطول بقاؤه pending قيد المراجعة عندنا. لا تُعِد إرساله لتستعجله: إعادة الإرسال بالمفتاح نفسه تعيد لك الطلب الأول ولا تحرّكه، وإعادته بمفتاح جديد تشتري مرة ثانية. ولن تُحاسَب على الطلب مرتين مهما طال.

أسئلة

هل يوجد مسار لطلب استرداد؟

لا، ولن يوجد. الاسترداد يقع من تلقاء النظام حين يتعذّر تنفيذ الطلب، فتجد الطلب refunded والمبلغ في محفظتك ويصلك order.refunded. أمّا الكود الذي صدر فنهائي.

هل تختلف الأسعار في الواجهة عنها في اللوحة؟

لا. الاثنتان تسألان الشيء نفسه على الخادم، فما تقرأه الواجهة هو ما تراه في اللوحة وهو ما يُخصم من محفظتك.

ضاع مفتاحي، ماذا أفعل؟

ألغِه من لوحتك وأنشئ غيره. لا يمكننا إظهار مفتاح قديم لأننا لا نحتفظ به، والإلغاء فوري.