دليل Shopify checkout عبر WebMCP: من قراءة الطلب إلى إتمامه بأمان

ما المقصود فعلاً بـ Shopify checkout عبر WebMCP؟

Checkout WebMCP هو مجموعة أدوات تُسجَّل داخل علامة تبويب الدفع النشطة لدى المشتري. يمكن تشبيهه بمسار دفع يعمل فيه موظف: يحمل الوكيل السلة، ويقرأ النموذج، ويملأ الحقول المدعومة، بينما يظل التحقق من الهوية أو تحديات الدفع والموافقة النهائية بيد المشتري.

وهو امتداد لأدوات واجهة المتجر التي قدمتها Shopify سابقاً. يستطيع وكيل متصفح متوافق البحث في الكتالوج، وفحص المنتجات، وتحديث السلة، واستدعاء proceed_to_checkout. وعند الوصول إلى عملية دفع مؤهلة، تتغير قائمة الأدوات وتتاح أربع أدوات للدفع:

• تقرأ get_checkout عملية الدفع الحالية، أو إيصال الطلب في صفحة الشكر.
• تستبدل update_checkout حالة بيانات الاتصال والتنفيذ والخصومات والحقول المعلنة والدفع المدعومة، من دون تنفيذ الطلب.
• تحاول complete_checkout تنفيذ الطلب، أو تفتح خطوة للمراجعة، بعد تأكيد المشتري.
• تعيد navigate_to_storefront علامة التبويب نفسها إلى واجهة المتجر إذا كانت متاحة.

يعتمد تنفيذ الدفع على كائن UCP الخاص بالدفع وحالاته ورسائله. يمثّل UCP عقد البيانات المشترك الذي يقوم عليه التدفق، بينما يمثّل WebMCP الوسيلة التي يتيح بها المتصفح ذلك العقد للوكيل. أما الوكيل العامل على الخادم، فعليه استخدام Checkout MCP من Shopify.

لا يوجد مفتاح إعداد جديد لدى التاجر، ولا واجهة API مستقلة للدفع ينبغي تثبيتها. وهذا يسهّل التبنّي على التجار، لكنه لا يلغي العمل المطلوب من مطوّر الوكيل. فما زلت بحاجة إلى دعم المتصفح، وWeb Bot Auth، وإدارة دقيقة للحالة، وحدٍّ واضح للموافقة.

ابدأ بعملية دفع مؤهلة

اختبارك الأول هو اكتشاف الأدوات. لا تفترض أن Shopify checkout تتيح Checkout WebMCP لمجرد أن واجهة المتجر أتاحت WebMCP.

لا تسجّل Shopify أدوات الدفع في الحالات الآتية:

• عملية الدفع القياسية ذات الصفحات الثلاث، ما لم يدفع المشتري عبر Shop Pay
• الدفع في معاملات B2B
• الدفع المضمّن أو مسارات حزمة SDK للدفع عبر الجوال
• عملية دفع تتضمن بضائع من متجر آخر
• مسودات الطلبات، أو تعديل الطلبات، أو تحصيل المدفوعات
• التفاعلات التي توفرها إضافات واجهة مستخدم الدفع

في هذه المسارات، سلّم التحكم إلى المشتري على الصفحة. ولا توجد أيضاً أداة cancel_checkout داخل المتصفح. فغياب الأداة لا يمنح الوكيل إذناً بالتلاعب بعناصر التحكم في الصفحة.

تقول Shopify إن WebMCP في واجهة المتجر يعتمد حالياً على دعم الوكلاء في المتصفحات المبنية على Chromium. استخدم متصفحاً مدعوماً وعملية دفع تسيطر عليها للاختبار. وإذا غابت أدوات الدفع، فتعامل مع ذلك بوصفه نتيجة متوقعة لشروط الأهلية، لا مبرراً للعودة إلى نقرات هشة على الواجهة.

1. وثّق وكيل المتصفح، ثم اكتشف الأدوات

وقّع طلبات المتصفح باستخدام Web Bot Auth، أو WBA، بدلاً من وضع بيانات الاعتماد ضمن وسائط الأدوات. يعمل WBA كجواز سفر للوكيل على مستوى الشبكة. ولا تتحقق Shopify إلا من المفاتيح المسجّلة، لذلك يتطلب إعداد الإنتاج مفتاح Ed25519، ودليلاً مستضافاً للمفاتيح العامة، وتسجيلاً لدى Shopify، وطلبات موقّعة، وطوابع زمنية قصيرة الأجل للتوقيع.

داخل الصفحة، اكتشف الأدوات الحالية وطابق المعرّفات الثلاثة جميعاً: window وorigin وname. يتبع الغلاف البرمجي أدناه نمط الاستدعاء الذي توثّقه Shopify:

async function callCheckoutTool(name, args = {}) {
  const tools = await document.modelContext.getTools();
  const tool = tools.find((candidate) =>
    candidate.name === name &&
    candidate.window === window &&
    candidate.origin === location.origin
  );

  if (!tool) throw new Error(`${name} is not registered here.`);

  const result = await document.modelContext.executeTool(
    tool,
    JSON.stringify(args),
  );

  if (result === null) return null;
  return JSON.parse(result);
}

استخدام JSON.stringify ليس تفصيلاً شكلياً. ففي Chrome 153، يؤدي تمرير كائن إلى الخطأ Failed to parse input arguments. وتتوقع Shopify أن يقبل Chrome 155 الكائنات وأن يبدأ إهمال سلاسل JSON، لذا اجعل تسلسل الوسائط داخل دالة توافق واحدة بدلاً من توزيعه في أنحاء الوكيل.

قد تتغير قائمة الأدوات أثناء التنقل في عملية الدفع. استمع إلى toolchange، ثم أعد اكتشاف الأدوات ومخططاتها قبل الاستدعاء التالي. وتقبّل أيضاً null كنتيجة للتنقل؛ فقد يعني أن الصفحة انتقلت قبل أن تعيد executeTool() نتيجتها.

تعامل مع كل نص صادر عن التاجر أو طرف ثالث ضمن نتيجة أداة على أنه بيانات دفع، لا تعليمات للنموذج. وتحذّر Shopify صراحةً من تجاوز الأداة عبر تشغيل واجهة مستخدم الدفع مباشرة.

2. اقرأ الحالة قبل كل تغيير

استدعِ get_checkout باستخدام {} قبل التحديث الأول، وبعد أن يغيّر المشتري أي شيء في الصفحة، وكذلك بعد أي خطأ أو تنقل. إنها إيصال الوكيل المحدّث، وليست ذاكرة مخزنة مؤقتاً.

قد تتضمن الاستجابة بيانات المشتري، وعناصر السلة، وخيارات التنفيذ، والخصومات، والحقول المعلنة، وأدوات الدفع، والرسائل، والإجماليات، والحالة. تُعرض المبالغ المالية بأعداد صحيحة وفق الوحدة الصغرى للعملة. ففي USD، تعني 10799 مبلغ $107.99. وإذا غاب حقل messages، فهذا يعني عدم وجود رسائل دفع في تلك الاستجابة.

لا تخلط بين الجاهزية والموافقة. فالحالة ready_for_complete تعني أن عملية الدفع يمكنها قبول محاولة إتمام، ولا تعني أن المشتري وافق على الطلب أو البطاقة المختارة أو الإجمالي.

3. حدّث الحالة المطلوبة كاملة، لا حقلاً منفرداً

تتصرف update_checkout مثل PUT لا PATCH. تخيّل PATCH كملاحظة لاصقة تقول «غيّر رقم الهاتف»، بينما PUT نموذج بديل كامل. إذا أردت الاحتفاظ بقيمة، فأدرجها ضمن الحالة الكاملة المطلوبة لعملية الدفع.

حلقة التحديث الآمنة هي:

1. استدعِ get_checkout.
2. أعد بناء الحالة القابلة للكتابة من الاستجابة الحديثة ومخطط الأداة الحالي.
3. غيّر فقط القيمة التي وافق عليها المشتري.
4. أرسل المجموعة المطلوبة كاملة من الحقول المدعومة إلى update_checkout.
5. اقرأ عملية الدفع المعادة وافحص حالتها ورسائلها والخصومات المطبقة والإجمالي.

تُمسح معظم القيم المحذوفة من الطلب. وللدفع والحقول المعلنة وبيانات الاتصال المحفوظة قواعد خاصة بها، ما يجعل نشر كائن عام بطريقة آلية غير آمن ما لم تقصره أولاً على الحقول المقبولة في المخطط الحالي.

أكثر التفاصيل المسببة للمشكلات محددة وواضحة:

• يقبل buyer البريد الإلكتروني ورقم هاتف بتنسيق E.164. وقد تظل بعض القيم المحفوظة مقفلة، لذلك تحقّق مما يعود في الاستجابة ودع المشتري يعدّل القيم المقفلة على الصفحة.
• يقبل fulfillment.methods طريقة واحدة كحد أقصى. أعد استخدام معرّفات الوجهة والمجموعة والخيار الحالية. ولا تغيّر نوع التنفيذ أو نقطة انطلاق البحث عن الاستلام في الاستدعاء نفسه الذي يختار وجهة أو خياراً.
• يجب أن تتضمن discounts.codes كل رمز أدخله المشتري ويريد الاحتفاظ به. تزيل المصفوفة الفارغة هذه الرموز، بينما تبقى الخصومات التلقائية. وعودة الرمز لا تثبت تطبيقه، لذا افحص discounts.applied والرسائل.
• يمكن أن تحمل declared_fields قيماً خاصة بعملية الدفع، مثل الرقم الضريبي أو رصيد المتجر. تُرفض المفاتيح غير المعروفة والأنواع الخاطئة والقيم غير الصالحة.
• تقبل payment.instruments عنصراً مدعوماً واحداً كحد أقصى. ولا يستطيع Checkout WebMCP تحصيل رقم بطاقة جديد.

يتطلب Shop Pay عناية إضافية. يستطيع المشتري المسجّل دخوله اختيار بطاقة محفوظة تعيدها get_checkout. ويمكن لمسار الضيف استخدام معرّف موافقة Shop Pay قائم إذا كانت عملية الدفع تقبله. وإذا طبّق الوكيل تلك الموافقة، فإن حذف الدفع من تحديث لاحق يلغي بيانات الاعتماد؛ لذلك أعد إرسال عنصر الموافقة مع كل تحديث حتى تنفيذ الطلب.

قد ينجح التحديث بينما تظل عملية الدفع في الحالة incomplete. وقد يعيد تحديث يستغرق أكثر من 30 ثانية الحالة update_failed رغم تطبيق بعض التغييرات. وفي الحالتين، اقرأ الحالة الحديثة قبل تقرير الخطوة التالية.

4. اجعل المشتري بوابة الإتمام

تسلسل الإتمام الصحيح قصير وصارم:

1. اجلب عملية دفع حديثة.
2. اعرض على المشتري العناصر الحالية وخيار الدفع والإجمالي.
3. اطلب إذناً صريحاً لتنفيذ ذلك الطلب بذلك الإجمالي.
4. إذا تغيّر أي شيء، فاعرض الحالة الجديدة واطلب الإذن مرة أخرى.
5. لا تستدعِ complete_checkout إلا بعد الموافقة.
6. لا تقبل سوى status: completed دليلاً على الشراء.

يثبت WBA هوية الوكيل الذي أرسل الطلب. وتجيز موافقة Shop Pay آلية للدفع. أما ready_for_complete فتصف حالة عملية الدفع. ولا يعني أيٌّ منها أن المشتري أذن بالشراء.

قد يتشعب مسار الإتمام. فإذا أعادت خطوة مراجعة مضبوطة التحكم إلى المشتري، فلا تستدعِ complete_checkout مرة أخرى إلا بعد أن يراجع المشتري عملية الإرسال ويجيزها. أما تحدي الدفع فمختلف: يُكمله المشتري في علامة التبويب نفسها، ولا ينبغي للوكيل أن يعيد الإرسال. استطلع get_checkout حتى تبلغ عملية الدفع الحالة completed أو تحتاج إلى تدخل الوكيل.

يحدد رمز الخطأ مسار الاستعادة المناسب:

إعادة المحاولة الخطرة هي محاولة إتمام ثانية لمجرد أن الاستجابة الأولى لم تكن حاسمة. لا يوفر Checkout WebMCP مفتاحاً لضمان عدم تكرار العملية. اقرأ الحالة أولاً؛ فإذا كانت completed، فتوقف.

سبع حالات استخدام مرتبة حسب قيمتها العملية

تكون هذه الحالات أقوى عندما يعمل الوكيل أصلاً داخل متصفح المشتري. فهي ليست عمليات أتمتة لدى التاجر تعمل خفيةً على خادم.

حالة الاستخدام الأولى هي الأقوى. فلدى المشترين المتكررين حالة محفوظة بالفعل، ويمكن لـ WebMCP تقليل الإدخال المتكرر من دون الإيحاء بأن الراحة تعني الموافقة.

ماذا تقول حسابات الجدوى فعلياً؟

لا تطلب Shopify إعداداً جديداً من التاجر لاستخدام أدوات الدفع هذه، لكن ذلك لا يجعل وكيل التسوق المحيط بها مجانياً. فلا يزال الوكيل يحتاج إلى نموذج، وتوزيع عبر المتصفح، وتشغيل WBA، واختبارات، وضوابط للخصوصية، ودعم.

تغطي مساعدات التسوق بالذكاء الاصطناعي المثبتة لدى التجار اليوم نطاقاً واسعاً من الأسعار. تعرض القوائم الرسمية في Shopify App Store خطة شهرية بسعر $9.99 من Easy AI Shopping Assistant، وخططاً من $49 إلى $249 من Carti، وخططاً من iAdvize تبدأ من $290 وتصل إلى $1,330 شهرياً. تجمع هذه المنتجات بين محادثة واجهة المتجر أو التوصيات أو التحليلات أو الدعم، ولذلك ليست بدائل مباشرة لوكيل WebMCP يعمل لدى المشتري.

التغير في الميزانية أضيق نطاقاً وأكثر فائدة: يستطيع فريق وكيل المتصفح تقليل الجهد المبذول في صيانة محددات دفع خاصة بكل متجر، وتوجيه جهد أكبر إلى سلامة الحالة والموافقة ومعالجة الاستثناءات. ولرؤية سياق المنصة الأوسع، تتناول مراجعة Shopify المنتج من جهة التاجر والمفاضلات التشغيلية.

منتجان يستحقان البناء

1. منصة اختبار للجودة والموافقة في Checkout WebMCP

هذه أقوى فرصة. تحتاج وكالات Shopify وفرق وكلاء التسوق إلى معرفة ما إذا كانت عملية الدفع مؤهلة، وما إذا كان الوكيل يتصرف بأمان، قبل أن تأتمنه على طلب.

يحصل أقرب استعلام وظيفي جرى قياسه، shopify checkout customization، على 170 عملية بحث شهرياً في الولايات المتحدة، وقد نما 89% على أساس سنوي، وتبلغ تكلفة النقرة فيه $10.92. الاستعلام أوسع من اختبار WebMCP، لكنه يشير إلى طلب نشط على سلوك الدفع وتنفيذه.

أصغر نسخة قابلة للبيع هي مشغّل Chromium يفتح عملية دفع اختبارية، ويسجل الأدوات بحسب المصدر والنافذة، ويتحقق من الوسائط بصيغة سلاسل JSON، ويرصد toolchange، ويختبر تحديثاً مبنياً على حالة حديثة، ويحاكي نتائج التنقل null ورموز الخطأ الموثقة، وينشئ تقرير موافقة منقّحاً. أبقِ تنفيذ الدفع الحقيقي خلف وضع اختبار يدوي.

التحدي هو التغطية. فتوافر الأدوات يعتمد على نوع الدفع ودعم المتصفح، كما أن تنسيق الوسائط في Chrome آخذ في التغير، ولا يستطيع تجهيز اختباري إثبات نجاح تسليم دفعة حقيقية. ينجح المنتج عندما يكشف هذه الحدود، لا عندما يدّعي أتمتة شاملة.

2. مساعد تسوق بالذكاء الاصطناعي لدى المشتري

يمكن لإضافة متصفح أن تنقل المتسوق من البحث عن المنتج إلى عملية دفع مؤهلة عبر متاجر Shopify، مع شاشة تأكيد قابلة لإعادة الاستخدام وقواعد صارمة لحالة الدفع المحفوظة.

يحصل الاستعلام shopify ai shopping assistant على 30 عملية بحث شهرياً في الولايات المتحدة، بقصد تجاري وتكلفة نقرة تبلغ $19.43. ويعرض المنافسون العاملون لدى التجار خططاً من $9.99 إلى $1,330 شهرياً، ما يدل على أن المشترين يدفعون بالفعل مقابل برمجيات التسوق الموجّه، حتى وإن كان هذا المنتج سيعمل لدى المشتري.

تحتاج النسخة الأولية إلى أدوات للبحث في واجهة المتجر والسلة، واكتشاف أدوات الدفع، وWBA، وحلقة القراءة والتحديث ثم القراءة، وملخص طلب يتحكم فيه المشتري، وتسليم تحديات الدفع. ابدأ بطلبات من متجر واحد ومسارات Shop Pay التي تستخدم بيانات محفوظة.

أما التحدي فهو التوزيع. لا يفعّل التجار Checkout WebMCP، لكن المشترين يظلون بحاجة إلى وكيل متصفح متوافق. وتبقى معاملات B2B، والدفع المضمّن، وحزمة SDK للجوال، والطلبات العابرة للمتاجر، والدفع العادي ذي الصفحات الثلاث من دون Shop Pay خارج هذا المسار.

حدود التقنية هي حدود المنتج

Checkout WebMCP واجهة أكثر أماناً للدفع المؤهل داخل المتصفح، وليست واجهة شراء API شاملة.

لا يمكنها إضافة عناصر أو إزالتها أثناء الدفع، أو تحصيل رقم بطاقة جديد، أو إلغاء عملية الدفع، أو تشغيل واجهة إضافات يعرّفها تطبيق، أو إجبار عملية دفع مستبعدة على تسجيل الأدوات. كما أنها لا تلغي تسجيل الدخول إلى Shop Pay، أو 3D Secure، أو خطوات المراجعة، أو غيرها من إجراءات المشتري. ولا تجعل نص التاجر تعليمات موثوقة للنموذج.

قاعدة التصميم الصادقة بسيطة: استخدم الأدوات ما دامت مسجّلة، واعتمد الحالة الحديثة مصدراً للحقيقة، وأعد الصفحة إلى المشتري كلما نص العقد على أن يتدخل بنفسه.

خطوة يوم الاثنين

يوم الاثنين، أضف غلاف دفع واحداً إلى وكيلك بدلاً من توزيع الاستدعاءات في أنحاء الشفرة. ضع فيه التسلسل، ومطابقة الأدوات، وtoolchange، والتنقل الذي يعيد قيمة null، وتصنيف الأخطاء، وقراءات الحالة الحديثة. شغّل حالات التجهيز المحلي الثماني، ثم اسرد document.modelContext.getTools() في عملية دفع اختبارية مؤهلة تسيطر عليها. اختبر تحديثاً واحداً مبنياً على حالة حديثة. ولا تُتم إلا طلب اختبار مدعوماً بعد تأكيد صريح؛ وإذا لم يكن لديك طلب اختبار آمن تملكه، فتوقف عند ready_for_complete وتعامل مع الإتمام على أنه موثّق بالمصدر، لا مجرّباً شخصياً.

إذا أردت وكيل تجارة يضع الموافقة أولاً ومصمماً لأعمالك، فتعرّف إلى خدمة تطوير وكلاء الذكاء الاصطناعي.