۱. مقدمه
این مستند فنی با هدف تشریح نحوهی تعامل سیستمهای POS فروشگاهی با سامانه فروش آنلاین اسنپ! مارکت تهیه شده است.
ارتباط میان POS و پلتفرم اسنپ! مارکت از طریق API مبتنی بر HTTPS برقرار میشود و احراز هویت با استفاده از استاندارد OAuth2 انجام میگیرد.
در تمامی اندپوینتها:
- قیمتها بر حسب تومان هستند
- زمانها بر حسب دقیقه محاسبه میشوند
۲. دامنه و کاربرد
این مستند موارد زیر را پوشش میدهد:
- احراز هویت و مدیریت توکن دسترسی
- همگامسازی اطلاعات محصول، قیمت، تخفیف و موجودی
- دریافت سفارش از طریق Webhook یا MQTT
- پردازش سفارش (Ack / Pick / Accept / Reject)
- پایش اتصال، گزارشگیری و مدیریت خطا
مخاطب این مستند، تیمهای توسعه POS، نرمافزارهای حسابداری فروشگاهی و سامانههای مرکزی چیناستورها هستند.
۳. تعاریف پایه
| اصطلاح | تعریف |
|---|---|
| Vendor (فروشگاه) | هر واحد فیزیکی یا منطقی فروش که دارای استقلال در سفارشگیری، موجودی، قیمتگذاری و پردازش سفارش است (مانند شعب یک فروشگاه زنجیرهای). |
| Product (محصول) | کالای قابل فروش که با بارکد یکتا شناسایی میشود و دارای قیمت، تخفیف، موجودی و وضعیت فعال/غیرفعال است. |
| Order (سفارش) | سبد نهاییشده کاربر شامل اقلام، تعداد، قیمت نهایی، روش ارسال و اطلاعات تحویل که برای فروشگاه ارسال میشود. |
| VendorCode | شناسه یکتای فروشگاه در سامانه اسنپ! مارکت که در بدنه بسیاری از درخواستها استفاده میشود. |
| Access Token | توکن صادرشده از سرویس احراز هویت که برای فراخوانی APIها در هدر Authorization استفاده میشود. |
۴. نگاه عملیاتی: POS و همگامسازی داده
در معماری اسنپ! مارکت، POS منبع حقیقت (Source of Truth) برای قیمت و موجودی فروشگاه محسوب میشود. بنابراین ارسال بهموقع و صحیح دادهها از POS نقش حیاتی در جلوگیری از مغایرت سفارشها دارد.
هرگونه وقفه، قطعی شبکه یا ارسال ناقص داده میتواند منجر به Data Drift (ناهمترازی دادهها) شود که نتیجه آن:
- اختلاف قیمت در سفارش
- عدم تطابق موجودی واقعی با سفارش
- افزایش Reject و تماس مرکز تماس
۵. Sync و Resync (Best Practice عملیاتی)
برای حفظ پایداری سیستم، POS باید از دو مفهوم کلیدی پشتیبانی کند:
- Sync: ارسال بلادرنگ تغییرات قیمت و موجودی در لحظه تغییر در فروشگاه
- Resync: ارسال مجدد و کامل دادهها در صورت تشخیص مغایرت یا Weak Signal
۶. نمای کلی فلو ارتباطی
- دریافت Access Token
- ارسال اطلاعات محصول، قیمت و موجودی
- دریافت سفارش از اسنپ! مارکت
- پردازش سفارش و ارسال Ack / Pick / Accept / Reject
- پایش و اصلاح مغایرتها با Sync / Resync
۷. ادامه مسیر
در بخش بعدی، فرآیند احراز هویت و دریافت توکن دسترسی بهصورت کامل تشریح شده است.
رفتن به بخش ۲: احراز هویت (OAuth2)