API همکاران

احراز هویت

در صفحه همکار خود یک کلید بسازید و آن را در سرآیند Authorization بفرستید. کلیدها شبیه mdp_pk_3f9a1c07de_… هستند؛ ما فقط اثر انگشت نگه می‌داریم، پس کلید گم‌شده دوباره نمایش داده نمی‌شود: کلید جدید بسازید.

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

چرخش بدون وقفه: چرخش یک کلید جدید می‌سازد و کلید قدیم را ۲۴ ساعت فعال نگه می‌دارد. کلید جدید را در سیستم‌هایتان قرار دهید، سپس کلید قدیم خودش منقضی می‌شود (یا فوراً باطلش کنید). هرگز کلید را در صفحه وب یا اپ موبایل نگذارید: API را از سرور خودتان فراخوانی کنید.

محدودیت‌ها: ۱۲۰ درخواست در دقیقه برای هر همکار؛ کلیدهای ناموفق زیاد از یک نشانی ۱۰ دقیقه مسدود می‌شوند. خطاها 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٪ کمتر از قیمت عادی، بسته‌های 10, 50, 250تایی).

ساخت کدها

POST /partner/v1/codes با بدنه JSON:

یک سرآیند Idempotency-Key (هر متن یکتا) بفرستید: اگر درخواستتان دوباره ارسال شود، به‌جای کدهای جدید همان کدها را می‌گیرید (به مدت ۲۴ ساعت).

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 — فقط کدهای استفاده‌نشده؛ جایگاه بلافاصله آزاد می‌شود.

امنیت

• هر فراخوانی از طریق HTTPS است؛ کلیدها در زمان ثابت مقایسه می‌شوند و فقط اثر انگشت کلیددار آن‌ها ذخیره می‌شود.
• هر بار که کلیدی ساخته یا چرخانده شود، به نشانی تماس شما ایمیل می‌زنیم.
• کدها ۱۶ نویسه از ۳۲ نماد (۸۰ بیت) هستند، یک بار نشان داده می‌شوند، فقط به‌صورت اثر انگشت ذخیره می‌شوند و هنگام وارد کردن به ۱۰ تلاش در ساعت برای هر حساب محدودند.