۴. سفارش‌ها، وب‌هوک و MQTT

۴.۱ مقدمه

فرآیند سفارش، حساس‌ترین نقطه‌ی اتصال بین POS فروشگاه و سامانه فروش آنلاین اسنپ! مارکت است. هر اختلال در دریافت، تأیید یا پردازش سفارش می‌تواند مستقیماً به NFC، تماس مرکز تماس یا نارضایتی مشتری منجر شود.

دریافت سفارش از دو مسیر انجام می‌شود:

• Webhook: مسیر اصلی و الزامی برای دریافت جزئیات کامل سفارش
• MQTT: اعلان بلادرنگ برای اطلاع از ایجاد یا تغییر وضعیت سفارش

۴.۲ دریافت سفارش از طریق Webhook (مسیر اصلی)

هنگام ثبت یا ویرایش سفارش، سامانه اسنپ! مارکت یک درخواست POST به آدرس Webhook معرفی‌شده توسط فروشگاه ارسال می‌کند.

بدنه درخواست از نوع application/x-www-form-urlencoded بوده و شامل تمام اطلاعات موردنیاز برای ثبت سفارش در POS است.

هدرهای مهم

• Content-Type: application/x-www-form-urlencoded
• User-Agent: شامل عبارت Snapp
• Authorization: امضای HMAC

نمونه درخواست واقعی (Production)

POST https://YOUR_WEBHOOK_URL
Content-Type: application/x-www-form-urlencoded
Authorization: HMAC snappfood:{timestamp}:{signature}

code=xd4yd22w
&statusCode=56
&vendorCode=p5qole
&orderDate=1765286349
&price=115900
&packingPrice=7900
&deliveryTime=15
&preparationTime=20
&expeditionType=PICKUP
&orderPaymentTypeCode=ONLINE
&products[0][barcode]=6260415738200
&products[0][quantity]=3
&products[0][price]=36000
&products[0][discount]=12000
&products[0][title]=...

پاسخ مورد انتظار فروشگاه

HTTP/1.1 200 OK

۴.۳ دریافت اعلان از طریق MQTT

MQTT برای اعلان بلادرنگ استفاده می‌شود و جایگزین Webhook نیست.

Topic:
neuron/vendor/{vendorCode}

پس از دریافت پیام MQTT، فروشگاه باید منتظر Webhook بماند و پردازش سفارش را فقط بر اساس Webhook انجام دهد.

۴.۴ پاسخ‌دهی به سفارش‌ها (API)

۴.۴.۱ تأیید دریافت سفارش (ACK)

اولین اقدام فروشگاه پس از دریافت Webhook، ارسال ACK است.

POST /va/v1/order/{orderCode}/ack
Authorization: Bearer <access_token>

۴.۴.۲ پذیرش سفارش (ACCEPT)

POST /va/v1/order/{orderCode}/accept
Authorization: Bearer <access_token>

{
  "packingPrice": 7900,
  "delta": 0,
  "deliveryTime": 15,
  "riderPickupTime": 10
}

۴.۴.۳ رد سفارش (REJECT)

POST /va/v1/order/{orderCode}/reject
Authorization: Bearer <access_token>

{
  "reason": "Out of stock"
}

۴.۵ وضعیت‌های سفارش (StatusCode)

۴.۶ خطاهای رایج

۴.۷ نکات پایداری

• Webhook تنها مرجع پردازش سفارش است
• MQTT فقط اعلان است
• ACK را با تأخیر ارسال نکنید
• Retry فقط برای خطاهای موقتی

۴.۸ ادامه مسیر