۳. محصولات، قیمت و موجودی

۳.۱ چرا این بخش حیاتی است؟

همگام‌سازی صحیح محصولات، قیمت و موجودی نقش مستقیمی در کاهش NFC، جلوگیری از False Positive / False Negative و بهبود تجربه مشتری دارد.

در مدل رایج صنعت گروسری (Vendor → POS → Platform)، اختلاف بین موجودی واقعی فروشگاه و عدد ثبت‌شده در سیستم یک پدیده طبیعی عملیاتی است، نه نشانه خرابی سیستم.

• False Positive: کالا در سیستم موجود است ولی فیزیکی وجود ندارد → Reject / NFC
• False Negative: کالا موجود است ولی در سیستم ثبت نشده → از دست رفتن فروش
• Price Drift: اختلاف قیمت POS و سفارش ثبت‌شده

۳.۲ آدرس پایه و سیاست Batch

آدرس پایه APIهای محصول: https://api-proxy.snapp.express/va/v1/product

• اندازه Batch در درخواست‌های Bulk می‌تواند بین ۱۰۰ تا ۵۰۰ آیتم تنظیم شود.
  پیشنهاد می‌شود Batch Size بر اساس توان POS، کیفیت شبکه و نرخ خطا انتخاب شود.
• قیمت‌ها به تومان ارسال می‌شوند
• تخفیف‌ها به‌صورت درصد هستند

۳.۳ همگام‌سازی قیمت و تخفیف (productDetails)

این endpoint برای ارسال یا بروزرسانی قیمت مصرف‌کننده و تخفیف فروشنده استفاده می‌شود. برای محصولاتی که تازه وارد فروشگاه شده‌اند، ابتدا باید از این مسیر معرفی شوند.

POST https://api-proxy.snapp.express/va/v1/product/productDetails
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "vendorCode": "VENDOR_CODE",
  "products": [
    { "barcode": "1234", "price": 10000, "discount": 10 }
  ]
}

پاسخ شامل آرایه failedItems است و موفقیت یا شکست هر بارکد به‌صورت مجزا مشخص می‌شود.

۳.۴ همگام‌سازی موجودی (stock)

موجودی، حساس‌ترین داده عملیاتی است. تأخیر در ارسال آن یکی از رایج‌ترین دلایل NFC در گروسری آنلاین محسوب می‌شود.

POST https://api-proxy.snapp.express/va/v1/product/stock
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "vendorCode": "VENDOR_CODE",
  "stocks": [
    { "barcode": "1234", "stock": 18 }
  ]
}

۳.۵ فعال / غیرفعال‌سازی محصول

در شرایطی که محصول به‌طور فیزیکی قابل فروش نیست، می‌توان آن را به‌صورت دستی غیرفعال کرد.

PUT https://api-proxy.snapp.express/va/v1/product/
Authorization: Bearer <access_token>
Content-Type: application/json

۳.۶ بروزرسانی فقط قیمت (price)

اگر فقط قیمت تغییر کرده و تخفیف ثابت است، استفاده از این endpoint توصیه می‌شود.

POST https://api-proxy.snapp.express/va/v1/product/price
Authorization: Bearer <access_token>
Content-Type: application/json

۳.۷ ارسال عنوان محصول (title)

این endpoint برای اصلاح یا ارسال عنوان نمایشی محصولات فروشگاه استفاده می‌شود. پاسخ موفق شامل 204 No Content خواهد بود.

POST https://api-proxy.snapp.express/va/v1/product/title
Authorization: Bearer <access_token>
Content-Type: application/json

۳.۸ استعلام وضعیت ثبت‌شده (get-info)

این endpoint ابزار اصلی بررسی Drift بین POS و داده ثبت‌شده در پلتفرم است و برای دیباگ اختلاف‌ها استفاده می‌شود.

۳.۹ توصیه‌های عملی برای کاهش ریسک

• Sync موجودی را تا حد امکان به رویداد واقعی فروش نزدیک کنید
• پس از قطعی POS یا شبکه، یک Resync محدود انجام دهید
• Retry فقط برای خطاهای موقتی (timeout / 5xx)
• پاسخ هر Batch را بررسی و فقط موارد ناموفق را اصلاح کنید
• انتظار دقت ۱۰۰٪ نداشته باشید؛ هدف کاهش اثر خطاست

۳.۱۰ ادامه مسیر