سبد خرید، سفارش و پرداخت

این صفحه مسیر کامل خرید در اپ را توضیح می‌دهد: از افزودن محصول به سبد تا ثبت سفارش، پرداخت و نمایش نتیجه. ترتیب مراحل مهم است؛ اگر یک مرحله را جا بیندازید، مرحله بعد داده لازم را ندارد.

---

نمای کلی مسیر

۱. سبد خرید      → افزودن، تغییر تعداد، حذف، کد تخفیف
۲. آدرس          → ثبت آدرس صورتحساب و ارسال
۳. روش ارسال     → انتخاب از میان نرخ‌های محاسبه‌شده
۴. درگاه پرداخت  → انتخاب درگاه
۵. ثبت سفارش     → ساخت سفارش و باز شدن درگاه
۶. نتیجه         → خواندن وضعیت واقعی سفارش از سایت

مراحل ۱ تا ۳ با ووکامرس تنها هم کار می‌کنند. مرحله ۴ برای نمایش نام و توضیح درگاه‌ها به افزونه اختصاصی نیاز دارد.

---

گام ۱: سبد خرید

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

صفحه سبد

1. یک صفحه «سبد خرید» بسازید.
2. یک لیست پویا با نوع داده اقلام سبد خرید (woo.cart) اضافه کنید.
3. یک صفحه الگو برای هر ردیف بسازید و در آن ویجت‌های معمولی متن و عکس را به مسیرهای sys.inPage.cartItem.* متصل کنید؛ بلوک‌های آماده نیز نمونه‌های قابل‌ویرایش دارند.
4. روی هر ردیف، عملکردهای «تغییر تعداد محصول در سبد خرید» با هدف ردیف جاری فهرست سبد و «حذف محصول از سبد خرید» را بگذارید.
5. زیر لیست، بلوک آماده خلاصه سبد خرید را اضافه کنید یا مقادیر sys.woocommerce.cartTotals را در ویجت‌های متن نمایش دهید.

حالت خالی

با شرط خالی بودن سبد خرید، پیام «سبد شما خالی است» و دکمه بازگشت به فروشگاه را نمایش دهید و دکمه ادامه خرید را پنهان کنید.

قفل کردن دکمه‌ها هنگام تغییر

هر تغییر سبد یک درخواست به سایت است. با شرط مقدار متغیر روی sys.woocommerce.cart.loading دکمه‌ها را در حین درخواست غیرفعال کنید تا کاربر پشت‌سرهم کلیک نکند و تعداد اشتباه ثبت نشود.

کد تخفیف

یک فیلد متن بگذارید، مقدارش را در متغیری مثل cart.coupon بریزید و عملکرد «اعمال کد تخفیف ووکامرس» را با همان «متغیر کد تخفیف» اجرا کنید. نتیجه در sys.wordpress.lastError یا مبالغ به‌روزشده سبد دیده می‌شود.

---

گام ۲: آدرس

1. صفحه «آدرس» را بسازید و فیلدهای فرم را به checkout.payload.billing_address.* وصل کنید.
2. اگر کاربر وارد شده باشد، این فیلدها از قبل با آدرس ذخیره‌شده او پر می‌شوند.
3. برای انتخاب کشور، استان و شهر می‌توانید از سرویس‌های app.countries، app.states و app.cities استفاده کنید.
4. روی دکمه «ادامه»، عملکرد ثبت آدرس و دریافت نرخ‌های ارسال را بگذارید و «متغیر آدرس صورتحساب» را checkout.payload.billing_address قرار دهید.
5. اگر آدرس ارسال جداست، گزینه «آدرس ارسال همان آدرس صورتحساب است» را خاموش و «متغیر آدرس ارسال» را معرفی کنید.

فیلدهای آدرس: first_name، last_name، company، country، state، city، address_1، address_2، postcode، phone، email.

پس از اجرای موفق این عملکرد، سه اتفاق می‌افتد:

• ووکامرس هزینه ارسال و مالیات را حساب می‌کند و مبالغ سبد به‌روز می‌شود.
• روش‌های ارسال در sys.woocommerce.shippingRates قرار می‌گیرند و ارزان‌ترین یا پیشنهادی ووکامرس خودکار انتخاب می‌شود.
• فهرست درگاه‌های پرداخت هم گرفته می‌شود و یک درگاه پیش‌فرض انتخاب می‌شود.

یادداشت

country باید کد دو حرفی باشد، مانند IR. اگر کشور معتبر نباشد، ووکامرس نرخ ارسال محاسبه نمی‌کند و فهرست روش‌های ارسال خالی می‌ماند.

---

گام ۳: روش ارسال

اگر می‌خواهید کاربر خودش روش ارسال را انتخاب کند:

1. یک لیست پویا با نوع داده روش‌های ارسال سبد خرید (woo.shipping_rates) اضافه کنید.
2. در الگوی هر ردیف، عنوان و قیمت را نمایش دهید.
3. روی ردیف، عملکرد انتخاب روش ارسال را با گزینه «استفاده از روش ارسال ردیف جاری فهرست» بگذارید.

روش انتخاب‌شده در sys.woocommerce.selectedShippingRate قرار می‌گیرد و مبالغ سبد به‌روز می‌شود.

اگر سفارش نیاز به ارسال نداشته باشد (همه محصولات مجازی)، sys.woocommerce.needsShipping برابر false است؛ کل این مرحله را با شرط مقدار متغیر پنهان کنید.

---

گام ۴: درگاه پرداخت

1. یک لیست پویا با نوع داده درگاه‌های پرداخت (app.payment_methods) اضافه کنید، یا داده را از sys.woocommerce.paymentMethods بخوانید.
2. روی ردیف، عملکرد انتخاب درگاه پرداخت جاری را بگذارید.

این عملکرد شناسه درگاه را در checkout.payload.payment_method و عنوان آن را در checkout.payload.payment_method_title می‌نویسد.

یادداشت

بدون افزونه اختصاصی، شناسه درگاه‌ها در دسترس است ولی نام و توضیح فارسی آن‌ها نه؛ فهرست با شناسه‌های خام مانند cod نمایش داده می‌شود. اگر فقط یک روش پرداخت دارید، می‌توانید این مرحله را حذف کنید و شناسه را مستقیم در checkout.payload.payment_method بگذارید.

---

گام ۵: ثبت سفارش

روی دکمه «ثبت سفارش»، عملکرد ثبت سفارش و شروع پرداخت را بگذارید و «متغیر اطلاعات پرداخت» را checkout.payload قرار دهید.

مهم

نام متغیر باید دقیقاً checkout.payload باشد. عملکرد انتخاب درگاه و مقداردهی خودکار آدرس‌ها روی همین مسیر کار می‌کنند.

ساختار نهایی این متغیر:

{
  "billing_address": {
    "first_name": "علی",
    "last_name": "رضایی",
    "address_1": "خیابان ...",
    "city": "تهران",
    "state": "THR",
    "postcode": "1234567890",
    "country": "IR",
    "email": "ali@example.com",
    "phone": "09120000000"
  },
  "shipping_address": { "...": "..." },
  "payment_method": "cod",
  "customer_note": "لطفاً عصر تحویل دهید"
}

اگر shipping_address را ندهید، همان آدرس صورتحساب استفاده می‌شود.

پس از ثبت موفق:

• sys.woocommerce.lastOrderId و sys.woocommerce.lastOrderKey پر می‌شوند.
• سبد خرید خالی می‌شود؛ همان‌طور که در خود ووکامرس اتفاق می‌افتد.
• اگر درگاه نیاز به هدایت داشته باشد، صفحه پرداخت داخل اپ باز می‌شود.

---

گام ۶: بازگشت از درگاه و نتیجه

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

مهم

بسته شدن صفحه پرداخت به معنی موفق بودن پرداخت نیست. همیشه نتیجه را از sys.woocommerce.lastOrderPaid و sys.woocommerce.lastOrderStatus بخوانید، نه از رفتار مرورگر.

صفحه نتیجه را این‌طور بسازید:

حالت	شرط	نمایش
موفق	sys.woocommerce.lastOrderPaid برابر true	پیام تشکر و شماره سفارش
در انتظار	lastOrderPaid نادرست و lastOrderStatus برابر pending	پیام «در انتظار پرداخت» و دکمه پیگیری
ناموفق	سایر حالت‌ها	پیام خطا و دکمه تلاش مجدد

برای درگاه‌های آفلاین مانند «پرداخت در محل»، سفارش بدون باز شدن صفحه پرداخت ثبت می‌شود و وضعیت بلافاصله خوانده می‌شود.

الگوی نشانی بازگشت

فیلد «الگوی نشانی بازگشت» را در حالت عادی خالی بگذارید. اپ خودش نشانی‌های استاندارد ووکامرس مانند order-received را تشخیص می‌دهد. فقط اگر درگاه شما کاربر را به نشانی غیراستانداردی برمی‌گرداند، الگوی آن را اینجا بنویسید.

---

پس از سفارش

با افزونه اختصاصی و ورود کاربر، این صفحه‌ها را هم می‌توانید بسازید:

صفحه	سرویس
سفارش‌های من	app.orders
اقلام هر سفارش	منبع خودکار با مسیر فیلد items
فایل‌های خریداری‌شده	app.downloads
اشتراک‌های من	app.subscriptions
رزروهای من	app.bookings

و روی هر سفارش، عملکردهای لغو سفارش و درخواست بازپرداخت یا مرجوعی را بگذارید.

---

چک‌لیست تست قبل از انتشار

• افزودن، تغییر تعداد و حذف محصول ساده و محصول متغیر
• رعایت حداقل، حداکثر و گام تعداد
• کد تخفیف معتبر و نامعتبر
• سبد خالی و پیام مربوطه
• آدرس ناقص و پیام خطا
• سفارشی که نیاز به ارسال ندارد
• یک سفارش واقعی با درگاه آنلاین، تا انتها
• یک سفارش با پرداخت در محل
• بستن صفحه پرداخت با دکمه بازگشت، وسط کار
• قطع اینترنت وسط ثبت سفارش

---

مطالب مرتبط

• عملکردهای وردپرس و ووکامرس
• متغیرهای وردپرس و ووکامرس
• آموزش ساخت اپ فروشگاهی با ووکامرس