مقدمه

سوپر اپلیکیشن مهراد

مهراد یک کیف پول دیجیتال با قابلیت مدیریت انواع دارایی است. کاربر می‌تواند دارایی‌های خود را در سایت، اپلیکیشن یا فروشگاه فیزیکی پذیرندگان خرج کند. این مجموعه‌مستندات، راهنمای پیاده‌سازی این ارتباط برای توسعه‌دهندگان پذیرنده است.

انتخاب مستند مناسبCopy Anchor Link

بر اساس هدف پیاده‌سازی، یکی از مسیرهای زیر انتخاب می‌شود:

مسیر متداول یک پذیرندهٔ فروشگاهی، ترکیب SSO (ورود کاربر) و سفارش (پرداخت) است.

مدل کلی یکپارچه‌سازیCopy Anchor Link

request‌های پذیرنده به API مهراد از سمت سرور ارسال می‌شوند و بسته به نوع عملیات، یکی از روش‌های authentication زیر به کار می‌رود:

برخی عملیات، مانند خرید حضوری، از طریق رابط کاربری پنل پذیرنده نیز در دسترس هستند و در این حالت به پیاده‌سازی API نیاز ندارند.

آدرس سرویسCopy Anchor Link

فرآیند دسترسی به محیط عملیاتی: پیاده‌سازی باید ابتدا به‌طور کامل روی محیط تست (Staging) انجام شود. پس از ارائهٔ دمو و تأیید آن از سمت مهراد، دسترسی محیط عملیاتی (Production) در اختیار شما قرار می‌گیرد.

تمام pathهای این مستندات نسبت به همین آدرس پایه هستند؛ برای مثال POST /gateway/sso/token یعنی https://api.mehrad.app/gateway/sso/token.

هر آدرسی که API بازمی‌گرداند — مانند payment_url، draft_url یا آدرس بازگشت کاربر — باید دقیقاً به همان شکل استفاده شود. ساختار این آدرس‌ها بخشی از قرارداد نیست و نباید توسط پذیرنده ساخته یا تغییر داده شود.

قالب response‌هاCopy Anchor Link

بیشتر endpoint‌ها response را در یک پوشش استاندارد برمی‌گردانند:

{
  "success": true,
  "data": {},
  "meta": null
}

endpoint‌های استاندارد SSO (token، introspection، discovery و JWKS) و endpoint‌های اطلاعات کاربر، بنا بر استاندارد OpenID، response را بدون این پوشش و به صورت شیء مستقیم برمی‌گردانند. در هر بخش نمونهٔ دقیق response آمده است.

خطاها همیشه این ساختار را دارند:

{
  "success": false,
  "error": {
    "code": "SSO_INVALID_GRANT",
    "message": "کد موقت ورود نامعتبر است یا دیگر قابل استفاده نیست.",
    "details": null
  }
}

مقدار code برای تصمیم‌گیری برنامه‌نویسی پایدار است؛ متن message برای نمایش به کاربر نهایی نوشته شده و ممکن است تغییر کند. منطق برنامه باید بر مبنای code پیاده‌سازی شود، نه بر مبنای متن پیام.

details در بیشتر خطاها null است. خطاهایی که در details اطلاعات تکمیلی دارند، در فهرست خطاهای هر مستند مشخص شده‌اند. کد HTTP و کد خطای هر مورد به تفکیک endpoint در بخش «فهرست خطاها» هر مستند آمده است.

خطای اعتبارسنجیCopy Anchor Link

اگر فیلدی از body، path یا query ارسال نشده باشد، نوع آن نادرست باشد یا مقدارش خارج از محدودهٔ مجاز باشد، response آن با کد ۴۲۲ و خطای VALIDATION_ERROR برگردانده می‌شود. در details، کلید هر عضو مسیر فیلد و مقدار آن فهرست پیام‌های خطای همان فیلد است. مسیر فیلدهای تودرتو با . و اندیس آرایه‌ها با عدد مشخص می‌شود؛ خطایی که به کل body مربوط است، کلید خالی ("") دارد.

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "بعضی فیلدها را اشتباه پر کرده‌اید یا مقدارشان خارج از محدودهٔ مجاز است.",
    "details": {
      "amount": ["Field required"],
      "shipments.0.items.1.price": ["Input should be greater than 0"]
    }
  }
}

پیام‌های داخل details برای اشکال‌زدایی هستند و نباید به کاربر نهایی نمایش داده شوند.

خطاهای مشترکCopy Anchor Link

خطاهای زیر در همهٔ مستندات مشترک‌اند و در فهرست خطاهای هر endpoint تکرار نمی‌شوند، مگر آن‌که معنای خاصی داشته باشند:

{
  "success": false,
  "error": {
    "code": "FINANCIAL_OPERATIONS_FROZEN",
    "message": "عملیات مالی به‌طور موقت متوقف شده است؛ لطفاً بعداً دوباره تلاش کنید.",
    "details": null
  }
}

مفاهیم مشترکCopy Anchor Link

واحد مبلغCopy Anchor Link

همهٔ مبالغ در API عدد صحیح و به ریال هستند و باید به صورت عدد صحیح ارسال شوند.

نکات مشترک امنیتیCopy Anchor Link

• client_secret، کلید خصوصی و tokenها فقط باید روی سرور پذیرنده نگهداری شوند؛ نباید در اپلیکیشن موبایل، کد سمت مرورگر یا localStorage قرار گیرند.
• request‌های حساس (ایجاد پرداخت، تأیید پرداخت، اصلاح و لغو سفارش) باید از سمت سرور پذیرنده ارسال شوند.