این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

چرخه عمر سفارش (پس از خرید)

پس از تکمیل فرآیند پرداخت و ثبت سفارش، باید با استفاده از وب‌هوک سفارش، به‌روزرسانی‌های وضعیت را به گوگل ارسال کنید. ارسال این رویدادها تضمین می‌کند که ردیابی سفارش، ارسال و بازگشت وجه به طور دقیق در صفحه سفارشات من (My orders) مشتری منعکس شود.

نقطه پایانی وب‌هوک

برای ارسال به‌روزرسانی‌های سفارش، یک درخواست POST حاوی کل محتوای موجودیت سفارش را به نقطه پایانی زیر ارسال کنید:

POST https://shoppingdataintegration.googleapis.com/v1/webhooks/partners/PARTNER_ID/events/order?key=API_KEY

گوگل در طول فرآیند ثبت‌نام، یک PARTNER_ID و API_KEY خاص را با شما به اشتراک می‌گذارد. کلید API را به یکی از دو روش زیر ارائه دهید:

به عنوان پارامتر کوئری URL: ?key=API_KEY
استفاده از هدر HTTP: X-Goog-Api-Key: API_KEY

رویدادهای به‌روزرسانی اجباری سفارش

شما باید تغییرات وضعیت سفارش زیر را گزارش دهید:

سفارش ایجاد شد: بلافاصله پس از تأیید سفارش ( status: processing ) فعال می‌شود.
سفارش ارسال شد: زمانی فعال می‌شود که اقلام سفارش از انبار خارج شوند. tracking_number و tracking_url نیاز دارد.
سفارش تحویل داده شد: زمانی فعال می‌شود که اقلام به گیرنده تحویل داده شوند.

رویدادهای به‌روزرسانی سفارش توصیه‌شده

برای ارائه بهترین تجربه کاربری، توصیه می‌کنیم به‌روزرسانی‌ها را برای رویدادهای زیر نیز ارسال کنید:

رویدادهای تعدیل:
- dispute : زمانی که مشتری نسبت به هزینه اختلاف نظر دارد.
رویدادهای تحقق:
- canceled : وقتی یک اجرا لغو می‌شود (درون آرایه fulfillment.events ارسال می‌شود).

منطق سفارش و نگاشت وضعیت

برای رندر صحیح صفحه «سفارش‌های من»، گوگل به نگاشت منطقی خاصی در محتوای شما متکی است.

الزامات مربوط به هر ردیف کالا

موارد سطری نباید خالی باشند و باید شامل اطلاعات item باشند.
وضعیت یک قلم کالا باید به طور دقیق، total و مقادیر fulfilled (که در آن fulfilled نشان دهنده اقلام تحویل داده شده است) را طبق مشخصات UCP منعکس کند:
- processing : وقتی fulfilled ، 0 و total > 0 است (برای مثال، total: 2 ، fulfilled: 0 ).
- partial : وقتی fulfilled بزرگتر از ۰ اما کوچکتر از total است (برای مثال، total: 2 ، fulfilled: 1 ).
- fulfilled : وقتی که fulfilled برابر total و total > 0 باشد (برای مثال، total: 2 ، fulfilled: 2 ).
- removed : وقتی total برابر با 0 باشد (برای مثال، total: 0 ، fulfilled: 0 ).

رویدادهای تعدیل

هرگونه رویدادی که شامل جابجایی پول باشد باید به عنوان بخشی از آرایه adjustments ارسال شود.

cancellation : زمانی که کل سفارش یا اقلام خاصی از آن قبل از تکمیل لغو می‌شوند.
return : زمانی که اقلام سفارش پس از تکمیل توسط مشتری بازگردانده می‌شوند.
refund : زمانی که وجه یک سفارش یا اقلام خاص بازپرداخت می‌شود.

سفارش‌های چند قلمی

بخش‌های بعدی نحوه گروه‌بندی و پیگیری سفارشات و بسته‌های چند قلمی را توضیح می‌دهند.

گروه‌بندی بسته‌های چند قلمی

اقلام موجود در صفحه "سفارش‌های من" بر اساس بسته‌ها (که دارای tracking_url یکسان هستند) گروه‌بندی می‌شوند. اگر بخشی از یک بسته بازگردانده شود، اقلام بازگردانده شده در صفحه "سفارش‌های من" به یک بخش جداگانه تقسیم می‌شوند.

وضعیت بسته

وضعیت‌های نشان داده شده برای بسته یکی از موارد زیر است: سفارش داده شده، ارسال شده، تحویل داده شده، برگشت داده شده، بازپرداخت شده، لغو شده. وضعیت‌های بسته از ویژگی type رویدادهای fulfillment و اشیاء adjustments گرفته می‌شوند.

نحوه تعیین وضعیت بسته

اگر یک رویداد تنظیم با status: completed وجود داشته باشد، بسته، وضعیت مناسب «برگشتی»، «بازپرداخت‌شده» یا «لغوشده» را بر اساس نوع رویداد تنظیم نمایش می‌دهد.

ویژگی‌های رویداد تنظیم	وضعیت بسته
`type: return` ، `status: completed`	برگردانده شد
`type: refund` ، `status: completed`	بازپرداخت شد
`type: cancellation` ، `status: completed`	لغو شد

اگر هیچ تنظیمی تکمیل نشده باشد، وضعیت بر اساس نوع رویداد تکمیل سفارش خواهد بود:

ویژگی‌های رویداد تکمیل سفارش	وضعیت بسته
`type: shipped`	ارسال شده (تاریخ مورد انتظار <تاریخ>)
`type: delivered`	تحویل داده شد
بدون رویداد تکمیل سفارش	سفارش داده شده

قوانین اعتبارسنجی فنی

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

علل رد سفارش

گوگل، داده‌های وب‌هوک ورودی را اعتبارسنجی می‌کند و در صورت برآورده شدن هر یک از شرایط زیر، به‌روزرسانی‌ها را رد می‌کند:

بدنه درخواست شامل موجودیت سفارش (order entity) نیست.
این payload فاقد checkout_id یا id ( شناسه تأیید سفارش ) است.
این بدافزار حاوی یک مهر زمانی قدیمی‌تر از آخرین به‌روزرسانی ثبت‌شده است.
یک رویداد تعدیل با نوعی غیر از refund ، return ، credit ، price_adjustment ، dispute یا cancellation ارسال می‌شود.
هر توضیحی برای ارسال کالا بیش از ۲۰۰ کاراکتر دارد.

قیمت‌گذاری شامل مالیات

اگر در بازارهایی فعالیت می‌کنید که مالیات در جمع جزئی لحاظ می‌شود، موجودیت سفارش باید موارد زیر را در آرایه totals در تمام رویدادهای وب‌هوک منعکس کند:

جمع جزئی: تمام مالیات‌های مربوطه را در مبلغ subtotal لحاظ کنید و display_text روی "Subtotal (including taxes)" تنظیم کنید.
تکمیل سفارش: برای هزینه‌های ارسال یا تکمیل سفارش، یک ورودی display_text در نظر بگیرید (برای مثال، "Shipping" ).
مالیات: ورودی‌های جداگانه‌ی "tax" را از آرایه‌ی totals حذف کنید.

مراحل بعدی

برای مشاهده نمونه‌های بار داده JSON مختص هر نسخه، هدرهای وب‌هوک و دستورالعمل‌های امضای درخواست، به راهنمای پیاده‌سازی نسخه UCP مورد نظر خود مراجعه کنید: