۲. احراز هویت (OAuth2)

۲.۱ مقدمه

تمامی درخواست‌های API از سمت سیستم‌های POS به سامانه اسنپ! مارکت باید دارای Access Token معتبر باشند.

احراز هویت از طریق سرویس متمرکز auth-proxy.snapp.express و بر اساس استاندارد OAuth2 انجام می‌شود.

دید عملیاتی: Token یکی از اجزای حیاتی پایداری فروشگاه است. مدیریت نادرست آن مستقیماً منجر به Reject سفارش و بسته شدن فروشگاه می‌شود.

۲.۲ دریافت Access Token (Password Grant)

این روش معمولاً فقط در یکی از شرایط زیر استفاده می‌شود:

Endpoint

POST https://auth-proxy.snapp.express/token
Content-Type: application/x-www-form-urlencoded

Request Body

grant_type=password
scope=automation
client_id=YOUR_CLIENT_ID
client_secret=YOUR_CLIENT_SECRET
username=STORE_USERNAME
password=STORE_PASSWORD

نمونه cURL

curl -X POST "https://auth-proxy.snapp.express/token" \
 -H "Content-Type: application/x-www-form-urlencoded" \
 -d "grant_type=password&scope=automation&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&username=STORE_USERNAME&password=STORE_PASSWORD"

Response نمونه

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 7200,
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

۲.۳ نوسازی Access Token (Refresh Token Grant)

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

Endpoint

POST https://auth-proxy.snapp.express/token
Content-Type: application/x-www-form-urlencoded

Request Body

grant_type=refresh_token
scope=automation
client_id=YOUR_CLIENT_ID
client_secret=YOUR_CLIENT_SECRET
refresh_token=YOUR_REFRESH_TOKEN
Best Practice: نوسازی توکن را ۵ دقیقه قبل از expires_in انجام دهید و هرگز منتظر خطای 401 نمانید.

۲.۴ خطاها و سناریوهای رایج

سناریو کد خطا اقدام پیشنهادی
Access Token منقضی شده 401 / 3003 Refresh Token
Refresh Token نامعتبر 3004 Password Grant مجدد
Client Secret اشتباه 3002 بررسی تنظیمات محیطی
قطع دسترسی فروشگاه 503 تماس با تیم عملیات
هشدار: Retry کورکورانه در Password Grant می‌تواند منجر به Block امنیتی شود.

۲.۵ پیشنهاد معماری برای POS

۲.۶ ادامه مسیر

پس از احراز هویت موفق، POS می‌تواند وارد مرحله همگام‌سازی محصولات، قیمت و موجودی شود.

رفتن به بخش ۳: محصولات و موجودی