بعد مكالمة الدفع، يراجع المستخدم سلة التسوق المحدّثة والضرائب ورسوم التسليم والخصومات والرسوم الأخرى التي ترجعها. يؤكد المستخدم الطلب ويرسله، وترسل 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
يمثّل طلب العميل لتقديم الطلب، إلى جانب تفاصيل الدفع. - علامة وضع الحماية: يشير الحقل
isInSandbox
لطلب إرسال الطلب إلى ما إذا كانت المعاملة تستخدم عمليات الدفع في وضع الحماية.
مثال على طلب الطلب
فيما يلي مثال على SubmitOrderRequestMessage
:
JSON
{ "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 }
رسالة الرد على الطلب
بعد تلقّي الطلب، تعالج خدمة الويب الشاملة للطلب الطلب وتعيد إرسال 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
:
JSON
{ "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
لوصف نوع الخطأ.
مثال على ردّ غير ناجح
JSON
{ "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" } } } ] } } } ] } } }
إرسال تنفيذ الطلب
يجب اتّخاذ الخطوات التالية عند تنفيذ واجهة برمجة تطبيقات الإرسال للطلب.
التحقّق من الصحة
- نفِّذ عمليات التحقق من الخدمة وسلة التسوق والعروض الترويجية كما هو الحال في إعداد الدفع.
- اعرض RejectionInfo مع أحد الأنواع التالية إذا لزم الأمر:
RejectionInfoType | حالة الاستخدام |
---|---|
UNAVAILABLE_SLOT |
لم يعُد وقت تنفيذ الطلب صالحًا. |
PROMO_USER_INELIGIBLE |
استخدِم البريد الإلكتروني في عنصر Contact (جهة الاتصال) في الطلب للتحقّق من أهلية المستخدم للعرض الترويجي. اطّلِع على المثال في مقالة تنفيذ طلب الإرسال مع العروض الترويجية. |
INELIGIBLE |
|
PAYMENT_DECLINED |
لا يمكن معالجة عملية الدفع. على سبيل المثال، قد يرجع السبب في ذلك إلى عدم توفّر أموال كافية. |
UNKNOWN |
بالنسبة إلى أي خطأ آخر في عملية التحقّق |
اضبط OrderState.state
على REJECTED
في حال حدوث أخطاء في التحقق من الصحة. يمكنك أيضًا تقديم سبب رفض محدّد باستخدام FoodOrderUpdateExtensionfoodOrderErrors
. اطّلِع على الأمثلة في القسم
إرسال طلب التحقّق من صحة الطلب.
معالجة الدفع
- احسب
totalPrice
عن طريق إضافة سعر سلة التسوق والرسوم والخصم والضرائب والإكرامية. يجب أن تكون قيمةtotalPrice
هي نفسهاtotalPrice
التي تم إرجاعها في CheckoutResponseMessage بالإضافة إلى التغيير في مبلغ الإكرامية إذا كان بإمكان المستخدم تعديل مبلغ الإكرامية. راجع تغييرات الأسعار أثناء تقديم الطلب للاطّلاع على مزيد من التفاصيل. - يمكنك معالجة الطلب والدفع في حال إرجاع رد يحتوي على حالة الطلب
CREATED
أوCONFIRMED
. - تأكَّد من عرض تنسيق استجابة صالح باستخدام أنواع تم إنشاؤها من المخطط كما هو موضّح في إنشاء مكتبات العميل.
- استخدِم
GoogleProvidedPaymentInstrument.
instrumentToken
لمعالجة الدفعة. يُرجى إرجاع RejectionInfo بالنوعPAYMENT_DECLINED
إذا تعذّرت معالجة عملية الدفع. راجع معالجة الدفعات للاطّلاع على مزيد من التفاصيل. - قم بإبلاغ المستخدم مباشرة بعد أن تتم معالجة الطلب عن طريق البريد الإلكتروني وأو الرسائل القصيرة SMS.
عرض الرد
- اضبط OrderState.
state
علىCREATED
أوCONFIRMED
في حال لم تكن هناك أخطاء. - اضبط OrderState.
state
على "REJECTED
" في حال حدوث أخطاء، وضمِّن الكائن RejectionInfo مع العنصر RejectionInfoType المقابل - اضبط OrderUpdate.
orderManagementActions
.