بعد مكالمة الدفع، يراجع المستخدم سلة التسوّق المعدّلة التي تتضمّن الضرائب ورسوم التسليم والخصومات وغيرها من الرسوم التي تردّها. يؤكد المستخدم الطلب ويرسله، ويُرسِل Google طلبًا بتنسيق JSON إلى نقطة نهاية التسليم يحتوي على معلومات الطلب. يجب أن تتلقّى خدمة الويب هذا الطلب وتعالجه، ثم تُبلغ Google بحالة الطلب.
يصف هذا القسم تنسيق رسالة طلب الطلب التي ترسلها Google، ويُشار إليها باسمSubmitOrderRequestMessage، وتنسيق رسالة الردّ التي يجب تقديمها، ويُشار إليها باسم
SubmitOrderResponseMessage.
لمزيد من المعلومات عن دورة عمل معالجة الطلبات، يُرجى الاطّلاع على نظرة عامة على معالجة الطلبات.
تنفيذ توصيل الطلبات
يجب أن تتضمّن خدمة الويب "عملية الطلب الشاملة" التي تنشئها للعمل مع هذه الخدمة
نقطة نهاية عنوان URL لتلقّي رسائل الطلبات من Google. لمعالجة الطلبات، تتلقّى خدمة الويب SubmitOrderRequestMessage بتنسيق JSON
كطلب POST من Google. يحتوي هذا الطلب على طلب عميل، ويشمل الضرائب والرسوم ومعلومات الدفع. عند تلقّي طلب إرسال سفارش
، يجب أن تُجري خدمة الويب ما يلي:
- التحقّق من أهلية المعاملة، مثل إثبات ملكية البطاقة أو رصد عمليات الاحتيال
- أنشئ طلبًا في نظامك.
- عليك تفويض طريقة الدفع واستدعاء واجهة برمجة التطبيقات الخاصة بعملية تحصيل الرسوم من جهة معالجة الدفع، وذلك عند الاقتضاء.
- يُرجى الردّ بحالة الطلب المناسبة:
CREATEDأوCONFIRMEDأوREJECTED.
بعد معالجة الطلب، يجب أن يقدّم رمز التسليم استجابة
بتنسيق رسالة SubmitOrderResponseMessage JSON إلى Google.
لمزيد من المعلومات عن متطلبات تنفيذ خدمة الويب لسلسلة الإمداد من الطلب إلى التسليم، يُرجى الاطّلاع على نظرة عامة على سلسلة الإمداد.
رسالة طلب الطلب
عندما يختار العميل تقديم طلب أثناء عملية الشراء من البداية إلى النهاية،
تُرسِل Google طلبًا إلى خدمة الويب الخاصة بك باستخدام رسالة JSON تُسمى
SubmitOrderRequestMessage تحتوي على البيانات التالية:
- الغرض: يحتوي حقل
inputs[0].intentفي نص كل طلب إرسال طلب شراء على قيمة السلسلةactions.intent.TRANSACTION_DECISION. - الطلب: يحتوي الحقل
inputs[0].arguments[0].transactionDecisionValueفي طلب إرسال الطلبات على عنصرOrderيمثّل طلب العميل الذي سيتم تقديمه، بالإضافة إلى تفاصيل الدفع. - علامة Sandbox: يشير الحقل
isInSandboxفي طلب إرسال الطلب إلى ما إذا كانت المعاملة تستخدم الدفعات في Sandbox.
مثال على طلب الشراء
في ما يلي مثال SubmitOrderRequestMessage:
{ "user": {}, "conversation": { "conversationId": "CTKbKfUlHCyDEdcz_5PBJTtf" }, "inputs": [ { "intent": "actions.intent.TRANSACTION_DECISION", "arguments": [ { "transactionDecisionValue": { "order": { "finalOrder": { "cart": { "merchant": { "id": "restaurant/Restaurant/QWERTY", "name": "Tep Tep Chicken Club" }, "lineItems": [ { "name": "Spicy Fried Chicken", "type": "REGULAR", "id": "299977679", "quantity": 2, "price": { "type": "ESTIMATE", "amount": { "currencyCode": "AUD", "units": "39", "nanos": 600000000 } }, "offerId": "MenuItemOffer/QWERTY/scheduleId/496/itemId/143", "extension": { "@type": "type.googleapis.com/google.actions.v2.orders.FoodItemExtension" } } ], "extension": { "@type": "type.googleapis.com/google.actions.v2.orders.FoodCartExtension", "fulfillmentPreference": { "fulfillmentInfo": { "delivery": { "deliveryTimeIso8601": "P0M" } } }, "location": { "coordinates": { "latitude": -33.8376441, "longitude": 151.0868736 }, "formattedAddress": "Killoola St, 1, Concord West NSW 2138", "zipCode": "2138", "city": "Concord West", "postalAddress": { "regionCode": "AU", "postalCode": "2138", "administrativeArea": "NSW", "locality": "Concord West", "addressLines": [ "Killoola St", "1" ] } }, "contact": { "displayName": "Hab Sy", "email": "hab9878.sy@gmail.com", "phoneNumber": "+61000000000", "firstName": "Hab", "lastName": "Sy" } } }, "otherItems": [ { "name": "Delivery fee", "type": "DELIVERY", "price": { "type": "ESTIMATE", "amount": { "currencyCode": "AUD", "units": "3", "nanos": 500000000 } } }, { "name": "Subtotal", "type": "SUBTOTAL", "price": { "type": "ESTIMATE", "amount": { "currencyCode": "AUD", "units": "39", "nanos": 600000000 } } } ], "totalPrice": { "type": "ESTIMATE", "amount": { "currencyCode": "AUD", "units": "43", "nanos": 100000000 } }, "extension": { "@type": "type.googleapis.com/google.actions.v2.orders.FoodOrderExtension" } }, "googleOrderId": "01412971004192156198", "orderDate": "2020-10-22T09:02:06.173Z", "paymentInfo": { "displayName": "Pay when you get your food", "paymentType": "ON_FULFILLMENT" } } } } ] } ], "directActionOnly": true, "isInSandbox": true }
رسالة ردّ على الطلب
بعد تلقّي طلب، تعالج خدمة الويب Ordering End-to-End
الطلب وتُرسل SubmitOrderResponseMessage يتضمّن
البيانات التالية:
-
OrderUpdate: عنصر يحتوي على حالة الطلب وأي إجراءات متاحة للمستخدم بعد تقديم الطلب، مثل التواصل مع فريق الدعم وعرض تفاصيل الطلب، والتي تحدّدها في حقلfinalResponse.richResponse.items[0].structuredResponse.orderUpdateضمن الاستجابة.
حقل تعديل الطلب
عندما تُرسِل خدمة الويب SubmitOrderResponseMessage، يحتوي على حقل
OrderUpdate يتضمّن الحقول التالية:
-
actionOrderId: رقم التعريف الفريد للطلب، والذي يُستخدَم لتحديد الطلب بشكلٍ فريد في نظامك والإشارة إليه عند إرسال تعديلات لاحقة على الطلب. -
orderState: عنصرOrderStateيمثّل حالة الطلب orderManagementActions: الإجراءات المتاحة للمستخدم بعد تقديم الطلب، مثل التواصل مع فريق دعم العملاء وعرض تفاصيل الطلب-
totalPrice: إجمالي سعر الطلب. هذه خطوة اختيارية. لا ترسِل التعديل إلا إذا تغيّر إجمالي سعر الطلب بعد إرساله.
يمكن أن يكون الطلب في إحدى الحالات التالية:
CREATED: تمت معالجة الطلب بنجاح من خلال نقطة نهاية تسليم الطلبات، ولكن لم يؤكد مقدّم الخدمة الطلب بعد.CONFIRMED: تمت معالجة الطلب بنجاح من خلال نقطة نهاية تسليم الطلبات، وأكّد مقدّم الخدمة الطلب.REJECTED: حدثت مشكلة وتعذّر على نقطة نهاية التسليم إنشاء الطلب أو تأكيده، وقد يشمل ذلك مشاكل في الدفع.
إذا ضبطت طلبًا على حالة REJECTED، حدِّد السبب في حقل
rejectionInfo في OrderUpdate. استخدِم قيم
FoodOrderUpdateExtension.FoodOrderErrors مع
rejectionInfo من النوع UNKNOWN وقدِّم وصفًا.
مثال على استجابة الطلب
في ما يلي مثال SubmitOrderResponseMessage:
{ "finalResponse": { "richResponse": { "items": [ { "structuredResponse": { "orderUpdate": { "actionOrderId": "1603357328160", "orderState": { "state": "CONFIRMED", "label": "Pending" }, "updateTime": "2020-10-22T02:02:08-07:00", "orderManagementActions": [ { "type": "CUSTOMER_SERVICE", "button": { "title": "Call customer service", "openUrlAction": { "url": "tel:+61234561000" } } }, { "type": "VIEW_DETAILS", "button": { "title": "View order details", "openUrlAction": { "url": "https://partner.com/view/orderstatus" } } } ], "receipt": { "userVisibleOrderId": "BXZ-1603357328" } } } } ] } } }
طلب غير ناجح
إذا تعذّر إرسال طلب، على SubmitOrderResponseMessage ضبط قيمة OrderState.state على REJECTED. يجب أن يتضمّن الردّ أيضًا
RejectionInfo الذي يحتوي على عنصرRejectionType
لوصف نوع الخطأ.
مثال على استجابة غير ناجحة
{ "expectUserResponse": false, "finalResponse": { "richResponse": { "items": [ { "structuredResponse": { "orderUpdate": { "actionOrderId": "sample_action_order_id", "orderState": { "state": "REJECTED", "label": "Order rejected" }, "updateTime": "2017-05-10T02:30:00.000Z", "rejectionInfo": { "type": "PAYMENT_DECLINED", "reason": "Insufficient funds" }, "orderManagementActions": [ { "type": "CUSTOMER_SERVICE", "button": { "title": "Contact customer service", "openUrlAction": { "url": "mailto:support@example.com" } } }, { "type": "EMAIL", "button": { "title": "Email restaurant", "openUrlAction": { "url": "mailto:person@example.com" } } }, { "type": "CALL", "button": { "title": "Call restaurant", "openUrlAction": { "url": "tel:+16505554679" } } }, { "type": "VIEW_DETAILS", "button": { "title": "View order", "openUrlAction": { "url": "https://orderview.partner.com?orderid=sample_action_order_id" } } } ] } } } ] } } }
إرسال طلب التنفيذ
يجب اتّباع الخطوات التالية عند تنفيذ واجهة برمجة التطبيقات submit order API.
التحقّق من الصحة
- نفِّذ عمليات التحقّق من الخدمة وسلة التسوّق والعرض الترويجي كما هو موضّح في مقالة إعداد ميزة Checkout.
- أعِد RejectionInfo مع أحد الأنواع التالية إذا لزم الأمر:
| RejectionInfoType | حالة الاستخدام |
|---|---|
UNAVAILABLE_SLOT |
لم يعُد وقت التسليم صالحًا. |
PROMO_USER_INELIGIBLE |
استخدِم البريد الإلكتروني في عنصر جهة الاتصال في الطلب للتحقّق من أهلية المستخدم للاستفادة من العرض الترويجي. اطّلِع على المثال في تنفيذ إرسال الطلب مع العروض الترويجية. |
INELIGIBLE |
|
PAYMENT_DECLINED |
تعذّرت معالجة الدفعة. على سبيل المثال، قد يرجع ذلك إلى عدم توفّر رصيد كافٍ. |
UNKNOWN |
في حال حدوث أي خطأ آخر في التحقّق من الصحة |
اضبط OrderState.state على REJECTED في حال حدوث أخطاء في التحقّق. يمكنك اختياريًا تقديم سبب رفض محدّد
باستخدام FoodOrderUpdateExtension.foodOrderErrors. يمكنك الاطّلاع على أمثلة في
إرسال عملية التحقّق من الطلب.
معالجة الدفع
- احتسِب
totalPriceمن خلال إضافة سعر سلة التسوّق والرسوم والخصم والضرائب والرسوم المضافة. يجب أن يكونtotalPriceمطابقًا لـtotalPriceالذي تم إرجاعه في CheckoutResponseMessage بالإضافة إلى التغيير في مبلغ البقشيش إذا كان بإمكان المستخدم تعديله. اطّلِع على تغيُّرات السعر أثناء إرسال الطلب للحصول على مزيد من التفاصيل. - يمكنك معالجة الطلب والدفع إذا تلقّينا ردًا يشير إلى حالة الطلب
CREATEDأوCONFIRMED. - تأكَّد من عرض تنسيق ردّ صالح باستخدام أنواع تم إنشاؤها من المخطّط كما هو موضّح في إنشاء مكتبات العميل.
- استخدِم GoogleProvidedPaymentInstrument.
instrumentTokenلمعالجة الدفعة. أعِد RejectionInfo بالنوعPAYMENT_DECLINEDإذا تعذّرت معالجة الدفعة. يُرجى الاطّلاع على معالجة الدفعات للحصول على مزيد من التفاصيل. - إشعار المستخدم فورًا بعد معالجة الطلب من خلال البريد الإلكتروني و/أو الرسائل القصيرة
عرض الردّ
- اضبط OrderState.
stateعلىCREATEDأوCONFIRMEDفي حال عدم حدوث أي أخطاء. - اضبط OrderState.
stateعلىREJECTEDفي حال حدوث أخطاء وتضمين عنصر RejectionInfo مع RejectionInfoType المقابل. - اضبط OrderUpdate.
orderManagementActions.