MarketAPI logoMarketAPI

الوثائق

API الشركاء

للشركاء المعتمدين: أنشئ رموز تفعيل Chart Premium لعملائك من أنظمتك الخاصة (CRM، منطقة العملاء، التسجيل)، واطّلع على المستخدَم منها. عن برنامج الشركاء.

المصادقة

أنشئ مفتاحًا في صفحة الشريك وأرسله في ترويسة Authorization. تبدو المفاتيح مثل mdp_pk_3f9a1c07de_…؛ لا نحتفظ إلا ببصمة، فلا يمكن عرض المفتاح المفقود مجددًا: أنشئ مفتاحًا جديدًا.

curl https://app.marketapi.app/partner/v1/account \
  -H "Authorization: Bearer mdp_pk_YOUR_KEY"

تدوير دون انقطاع: يُنشئ التدوير مفتاحًا جديدًا ويُبقي القديم يعمل 24 ساعة. ضع المفتاح الجديد في أنظمتك، ثم ينتهي القديم تلقائيًا (أو أبطله فورًا). لا تضع مفتاحًا أبدًا في صفحة ويب أو تطبيق جوال: استدعِ الـ API من خادمك.

الحدود: 120 طلبًا في الدقيقة لكل شريك؛ ويُحظر العنوان الذي يرسل مفاتيح فاشلة كثيرة لمدة 10 دقائق. الأخطاء بصيغة JSON: {"error": "…", "code": "invalid"} مع HTTP 400 أو 401 أو 405 أو 429.

مقاعدك

GET /partner/v1/account

{"partner_id": "MP-7KQ3TA", "name": "Example Broker", "status": "active",
 "seats": [{"plan": "pro", "name": "Pro", "days": 30, "left": 48, "trial": false, "expires_at": null}]}

كل مقعد رمز تفعيل لخطة ومدة (30 أو 91 أو 182 أو 365 يومًا). اشترِ حزم المقاعد من صفحة الشريك (بخصم 30% من السعر العادي، حزم من 10, 50, 250).

إنشاء الرموز

POST /partner/v1/codes مع جسم JSON:

الحقلالمعنى
planpro أو proplus
months1 أو 3 أو 6 أو 12 (مدة المقعد)، أو days
countعدد الرموز (1–5000)؛ يمكن حذفه عند تقديم المراجع
customer_refsاختياري: مرجعك الخاص لكل رمز (مثل رقم حساب العميل)، حتى 120 حرفًا لكلٍّ منها. نخزّنه مقنّعًا (45•••68) مع بصمة مُفتاحية، فيمكنك إيجاد الرمز بالمرجع الكامل، لكننا لا نحتفظ به أبدًا.
expires_daysالمدة التي يبقى فيها الرمز غير المستخدَم صالحًا (الافتراضي 365؛ وتنتهي المقاعد التجريبية أبكر). الرمز غير المستخدَم الذي تنتهي صلاحيته يعيد مقعده.
batchاسم اختياري لتمييز الدفعة

أرسل ترويسة Idempotency-Key (أي نص فريد): إذا أُعيدت محاولة طلبك تحصل على الرموز نفسها بدل رموز جديدة (لمدة 24 ساعة).

curl -X POST https://app.marketapi.app/partner/v1/codes \
  -H "Authorization: Bearer mdp_pk_YOUR_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: onboarding-45123468" \
  -d '{"plan": "pro", "months": 1, "customer_refs": ["45123468"]}'
201 {"count": 1, "codes": [{"code": "K7QM-3XTP-9RWA-FD2H", "hint": "FD2H", "customer_ref": "45•••68",
      "plan": "pro", "days": 30, "expires_at": "2027-10-17T08:00:00+00:00"}]}

تظهر الرموز في الرد مرة واحدة فقط. أعطِ كل عميل رمزه؛ يُدخله في https://app.marketapi.app/premium (بعد تسجيل الدخول) فتبدأ الخطة فورًا، أو بعد الخطة التي لديه.

الدفعات الكبيرة: تُنشئ قائمة المهام لدينا أكثر من 100 رمز. يكون الرد 202 {"job": 812, "url": "/partner/v1/jobs/812"}؛ استعلم ذلك العنوان حتى يصبح status هو done؛ وتظهر الرموز في ذلك الرد في المرة الأولى فقط.

GET /partner/v1/jobs/812
{"status": "queued", "position": 2, "eta_s": 4.0}  →  {"status": "done", "count": 2000, "codes": [ … ]}

البحث عن الرموز

GET /partner/v1/codes?customer_ref=45123468&status=unused&limit=100&offset=0 — الحالة: unused أو redeemed أو cancelled.

{"codes": [{"id": 9134, "hint": "FD2H", "customer_ref": "45•••68", "plan": "pro", "days": 30, "status": "redeemed",
            "created_at": "…", "expires_at": "…", "redeemed_at": "…"}]}

إلغاء رمز

POST /partner/v1/codes/9134/cancel — للرموز غير المستخدمة فقط؛ ويصبح المقعد متاحًا فورًا.

الأمان