جستجوی کالا

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

این سند دو endpoint را توضیح می‌دهد که پذیرنده روی سرور خود پیاده‌سازی می‌کند تا کالاهایش در جستجوی کالای اپلیکیشن مهراد نمایش داده شود. در این ارتباط مهراد request ارسال می‌کند و پذیرنده پاسخ می‌دهد.

نمای کلیCopy Anchor Link

پیش‌نیازهاCopy Anchor Link

این آدرس‌ها در فرآیند راه‌اندازی به مهراد اعلام می‌شوند. نمونه:

https://shop.example.com/products/mehrad/
https://shop.example.com/products/{product_id}/mehrad/

فهرست endpoint‌هاCopy Anchor Link

مهراد request‌ها را بدون header Authorization ارسال می‌کند. هر دو endpoint باید فقط داده‌های عمومی کالا را برگردانند.

قواعد مشترکCopy Anchor Link

• پاسخ موفق باید کد ۲۰۰ و body از نوع JSON داشته باشد.
• پاسخ باید در کمتر از ۱۰ ثانیه ارسال شود.
• مبالغ به ریال و به صورت عدد صحیح ارسال می‌شوند.
• rate امتیاز کالا از ۰ تا ۵ است.
• فیلدی که در جدول‌ها اختیاری است می‌تواند ارسال نشود یا null باشد.

endpoint فهرست کالاCopy Anchor Link

GET https://shop.example.com/products/mehrad/?limit=10&offset=0&title=ساعت&is_available=1

این request هنگام جستجو و پیمایش صفحه‌به‌صفحهٔ فهرست کالاها در اپلیکیشن ارسال می‌شود.

پارامترهاCopy Anchor Link

مقادیر boolean به صورت 1 و 0 ارسال می‌شوند. به جز limit و offset، سایر پارامترها اختیاری‌اند. اگر پارامتری ارسال نشود، فیلتر آن اعمال نمی‌شود.

ResponseCopy Anchor Link

{
  "total_items": 37,
  "data": [
    {
      "id": "260",
      "title": "ساعت مچی عقربه‌ای کوارتز مردانه مدل EM610",
      "image_thumbnail_urls": [
        "https://shop.example.com/media/products/260_thumb.webp"
      ],
      "min_available_price": 2975000,
      "max_available_price": 2975000,
      "is_available": true,
      "has_fast_shipping": false,
      "has_in_store_purchase": true,
      "is_domestic": true,
      "rate": 5
    }
  ]
}

endpoint جزئیات کالاCopy Anchor Link

GET https://shop.example.com/products/260/mehrad/

به جای {product_id} در آدرس، id کالا از فهرست کالا قرار می‌گیرد. این request پارامتر query ندارد.

اگر کالایی با این ID در سیستم پذیرنده وجود ندارد، پاسخ آن باید کد ۴۰۴ داشته باشد.

ResponseCopy Anchor Link

data آرایه‌ای است که کالا تنها عضو آن است.

{
  "data": [
    {
      "id": "260",
      "url": "https://shop.example.com/products/260",
      "title": "ساعت مچی عقربه‌ای کوارتز مردانه مدل EM610",
      "rate": 5,
      "is_domestic": true,
      "specifications": [
        {
          "title": "مشخصات کلی",
          "attributes": [{ "name": "وزن", "value": "180 گرم" }]
        }
      ],
      "bold_attributes": [{ "name": "برند", "value": "الگانس" }],
      "shared_medias": [
        {
          "type": "IMAGE",
          "url": "https://shop.example.com/media/products/260.webp",
          "thumbnail_url": "https://shop.example.com/media/products/260_thumb.webp"
        }
      ],
      "variants": [
        {
          "id": "260",
          "url": "https://shop.example.com/products/260",
          "title": "مشکی",
          "sku": "MS-21695508",
          "key_properties": [{ "name": "رنگ", "value": "مشکی", "hex_code": "#000000" }],
          "min_available_price": 2975000,
          "max_available_price": 2975000,
          "has_fast_shipping": false,
          "has_in_store_purchase": true,
          "medias": []
        }
      ]
    }
  ]
}

نکات پیاده‌سازیCopy Anchor Link

• فیلترها و صفحه‌بندی باید در سمت پذیرنده اعمال شوند.
• total_items باید تعداد کل نتایج همان فیلترها باشد، نه تعداد کالاهای همین صفحه.
• ID کالا باید پایدار باشد؛ id بازگشتی در فهرست کالا باید در endpoint جزئیات کالا همان کالا را برگرداند.
• آدرس تصاویر و رسانه‌ها باید کامل و از طریق HTTPS در دسترس باشد.
• ارتباط باید فقط روی HTTPS برقرار شود.

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

• پیاده‌سازی endpoint فهرست کالا با پارامترهای limit، offset و فیلترها
• بازگرداندن total_items برابر تعداد کل نتایج فیلترشده
• پیاده‌سازی endpoint جزئیات کالا با {product_id} در آدرس
• بازگرداندن کد ۴۰۴ برای کالای ناموجود در endpoint جزئیات کالا
• ارسال مبالغ به ریال و rate بین ۰ و ۵
• پاسخ در کمتر از ۱۰ ثانیه
• اعلام آدرس‌های فهرست و جزئیات کالا به مهراد