نسخة Markdown

AI-translated from English; not yet reviewed by a fluent editor.

# كيفية ربط وكيل تسوق بـ Shop MCP من Shopify

> يربط Shop MCP الجديد من Shopify بين البحث في الكتالوج وسلال التجار وإتمام الشراء. يشرح هذا الدليل المستند إلى الوثائق الإعداد وخطوة موافقة المشتري وحدود التحقق من الطلب.

By BIG CHANGE Editorial

Published: 2026-10-14T12:58:17.853Z
Updated: 2026-10-14T12:58:17.853Z
Canonical: https://bigchange.ai/blog/connect-shopping-agent-shopify-shop-mcp

![Conceptual charcoal illustration of a product shelf, a shopping basket holding one cup, and a blank checkout terminal; a shopper's hand pauses short of the terminal.](https://bigchange.ai/api/media/file/shop-mcp-catalog-to-checkout-hero-v1.png)
AI-generated conceptual illustration by BIG CHANGE; no actual Shop MCP interface, agent test or purchase is depicted.

أطلقت Shopify [Shop MCP في 13 أكتوبر](https://shopify.dev/changelog/posts/add-shopping-and-shop-pay-checkout-to-any-agent-with-shop-mcp)، لتوفر للمطورين اتصالاً مستضافاً واحداً للبحث عن المنتجات والسلال وإتمام الشراء. الخدمة متاحة على `https://mcp.shop.com/`. ويمكن لأدواتها الـ17 العثور على منتجات في Shopify Catalog وفتح صفحة إتمام الشراء لدى التاجر الذي يبيع السلعة. لا يحتاج البحث في الكتالوج إلى مفتاح API. ولا تزال أي عملية شراء فعلية تتطلب موافقة المشتري.

هذا الدليل مخصص للمطورين الذين يهيئون مساعداً متوافقاً مع MCP. وتتبع الخطوات أدناه وثائق Shopify التي راجعناها في 14 أكتوبر. لم تربط BIG CHANGE وكيلاً ولم تنشئ سلة ولم تنفذ عملية شراء. لذلك يصف الدليل النتائج المتوقعة لا الأداء المرصود.

## التغيير الأبرز

- **ما الذي تغير:** تقدم Shopify الآن اتصال MCP مستضافاً يمتد من البحث في الكتالوج إلى سلة التاجر وإتمام الشراء. كما توثق إكمال الدفع عبر Shop Pay لمشترٍ سجّل الدخول بعد تأكيد صريح.
- **من يمكنه الاستخدام:** مطورو عملاء MCP التي تدعم إصدار البروتوكول `2026-07-28`، أو الشيفرة التي تنفذ طلبات HTTP الموثقة. ولا يمكن لعميل قديم لا يستخدم سوى مصافحة `initialize` الاتصال مباشرة.
- **ما الذي يجب التحقق منه:** إتمام الشراء معاملة لدى تاجر واحد. ولا يؤكد الشراء إلا `completed` مع `order`؛ أما السلة أو رابط الدفع أو الدفع قيد المعالجة فلا يكفي أي منها.

## قبل الاتصال

يلزم عميل MCP يدعم خوادم HTTP البعيدة ويتبع [طريقة الاتصال التي توثقها Shopify](https://shop.dev/docs/connect)، أو تطبيق يستدعي الخادم عبر HTTP. استخدم عنوان URL الجذر `https://mcp.shop.com/`؛ تؤدي إضافة `/mcp` إلى خطأ 404. تعمل أدوات البحث والسلة دون حساب Shop. وبعد تسجيل الدخول يمكن للمساعد استخدام التفضيلات والعناوين المحفوظة والعثور على الطلبات وعرض Shop Pay إذا كان التاجر يدعمه. وبالنسبة إلى مساعد يستخدم شيفرة HTTP خاصة به، توثق Shopify تدفق OAuth للأجهزة الذي يوافق عليه المشتري على موقع Shop.

اختر استعلام المنتج وبلد الوجهة والعملة قبل البحث. وافصل متطلبات المشتري المعلنة عن سياق البحث: يساعد البلد أو العملة على توطين النتائج؛ أما حد السعر أو المقاس أو وجهة الشحن فهي عوامل تصفية. تعرض API الأسعار بوحدات العملة الصغرى. ينبغي أن يقرأ تطبيقك الحقل `messages` في الاستجابة قبل الادعاء بأن النتيجة تطابق عامل تصفية، إذ قد تفيد الخدمة بأن العامل المطلوب لم يُطبق كما طُلب. يشرح [دليل البحث من Shopify](https://shop.dev/docs/search) هذا الفرق وحد النتائج من 1 إلى 50 في الصفحة.

## مسار موثق من البحث إلى الطلب

1. **الاتصال والتحقق من البحث.** هيئ العميل باستخدام `https://mcp.shop.com/` وحمّل [Shop skill](https://shop.dev/docs/connect) من Shopify إذا كان العميل يدعمه. وتقترح Shopify اختبار الاتصال بطلب العثور على ثلاثة مصابيح مكتبية دون إنشاء سلة. ويعيد البحث العامل منتجات تتضمن البائع والسعر بعملة محددة ورابط التاجر. ويمكن للمطورين الذين يستخدمون HTTP اتباع [البدء السريع JSON-RPC](https://shop.dev/docs/quickstart) من Shopify، بما فيه عناوين البروتوكول المطلوبة وطلب `search_catalog`. هذا فحص للقراءة فقط ولا يتطلب تسجيل الدخول.
2. **اختيار السلعة المطابقة.** شغّل `search_catalog` باستخدام استعلام المشتري ومتطلباته. يعيد البحث خياراً مميزاً؛ استخدم `get_product` إذا أراد المشتري مقاساً أو لوناً آخر. وقارن `product.selected` وما يعيده `variant.options` بكل مقاس ولون وخيار آخر حدده المشتري قبل عرضه أو شرائه. تقول Shopify إن الاختيار قد يُخفف دون تحذير. وعندما يختار المشتري منتجاً أو يغير خياراً، استدعِ `get_product` مجدداً للتحقق من التوفر والسعر الحاليين. احتفظ بمعرّف الخيار ونطاق البائع كما أُعيدا تماماً. ولا تفترض أن التاجر سيبقي سعراً سبق عرضه. اعرض أي تحذير بجوار المنتج المعني. توثق هذه الفحوص في [العثور على المنتجات](https://shop.dev/docs/search).
3. **إنشاء سلة عند الطلب.** بناءً على طلب المشتري جمع السلع، استدعِ `create_cart` للتاجر والخيار المحددين. تحفظ السلة السلع ولا تنشئ طلباً. ضع سلع البائعين المختلفين في سلال منفصلة: تقول Shopify إن كل سلة وكل عملية إتمام شراء تخص تاجراً واحداً. وينبغي أن تتضمن النتيجة معرّف السلة وبنودها. وإذا أراد المشتري التصفح فقط، فتوقف بعد البحث؛ إذ يوضح [دليل السلال من Shopify](https://shop.dev/docs/checkout) أن الاهتمام بمنتج وحده لا يمنح إذناً بإنشاء سلة.
4. **فتح إتمام الشراء ومراجعته.** عندما يطلب المشتري السعر الإجمالي أو يصبح مستعداً للشراء، استدعِ `create_checkout` باستخدام معرّف السلة أو معرّف الخيار ونطاق البائع المطابقين تماماً من نتائج البحث. ينبغي أن يعيد مستند إتمام الشراء معرّفاً وحالة وبنوداً وعملة وإجماليات وطرق دفع و`messages` وسياسة التاجر `links` و`continue_url` لصفحة التاجر. وقبل المتابعة، اعرض للمشتري الإجماليات الحالية بعناوينها، بما فيها التوصيل والضرائب، وجميع التحذيرات وروابط السياسات. وضع الإيضاحات بجوار السلعة أو الحقل المعني. وقدّم للمشتري `continue_url` دون تغيير، بما في ذلك معلمات الاستعلام، مع السلع التي يغطيها حتى إن استطاع الوكيل إكمال الدفع. وقد تكون حالة الدفع `incomplete` عند الحاجة إلى عنوان، أو `requires_escalation` إذا كان على المشتري إكماله في صفحة التاجر. تقول Shopify إن صلاحية إتمام الشراء تنتهي افتراضياً بعد ست ساعات.
5. **اترك الدفع للمشتري.** إذا سجّل المشتري الدخول فقد يعرض إتمام الشراء عناوين محفوظة وShop Pay. وقبل استدعاء `complete_checkout`، اقرأ أحدث حالة لإتمام الشراء وتأكد أنها `ready_for_complete`، واعرض التاجر والسلع والكميات والإجمالي والطرق المتاحة، ثم دع المشتري يختار طريقة الدفع. لا تختر نيابة عنه. وأبقِ `continue_url` الخاص بالتاجر دون تغيير متاحاً للمشتري حتى لو استطاع الوكيل إكمال الدفع؛ وإذا لم تتوفر أداة دفع فعلى المشتري استخدام ذلك الرابط. وتقول [تعليمات Shopify لإتمام الشراء](https://shop.dev/docs/checkout) أرسل `complete_checkout` مرة واحدة بعد الموافقة ثم افحص الحالة المعادة. أما [مسار الموافقة المنفصل للمتاجر خارج Shopify](https://shop.dev/docs/approvals) فيطلب من المشتري الموافقة على الدفع في Shop وتقديم بطاقة لإتمام الشراء الخاص بذلك المتجر؛ وهو ليس مسار متجر Shopify في الخطوتين 3 و4.
6. **التحقق من النتيجة.** لا يؤكد أن التاجر أنشأ طلباً إلا `status: completed` مع `order`. وإذا كان الدفع لا يزال قيد المعالجة، فاستخدم `get_checkout` لقراءة الحالة مجدداً. وتقول Shopify إنه لا توجد webhooks عند الإطلاق، لذا يجب على التكامل الاستعلام دورياً عن `get_checkout` للحصول على التحديثات. وإذا انتهت مهلة استدعاء الإكمال أو كان الرد غير واضح، فلا ترسله مرة أخرى ولا تفتح عملية دفع بديلة. اقرأ عملية الدفع الحالية؛ وإذا لم تعرض كلاً من `completed` و`order`، فأخبر المشتري أن الشراء غير مؤكد وقدّم له `continue_url`.

## الحدود والاستعادة

تقول Shopify إن البحث يعمل بلا بيانات اعتماد. وتوجه [ملاحظة الإطلاق](https://shopify.dev/changelog/posts/add-shopping-and-shop-pay-checkout-to-any-agent-with-shop-mcp) المطورين الذين يحتاجون إلى حدود معدل أعلى إلى مفتاح API في Shopify Dev Dashboard، لكنها لا تذكر سعراً عاماً أو جدول حدود لذلك المفتاح. تأتي أسعار سلع التاجر والشحن والضرائب من عملية الدفع الحالية؛ وينبغي للمشتري مراجعتها قبل الدفع. وقد يتحمل الوكيل أيضاً تكاليف استضافة أو نموذج خاصة إذا استخدمها مطوره. ولا تحدد الإعلانات هذه التكاليف.

يمكن إعادة القراءة الفاشلة بعد مهلة `retry_after` المحددة. وبالنسبة إلى إنشاء السلال وعمليات الدفع أو تحديثها، يوصي [دليل الأخطاء من Shopify](https://shop.dev/docs/errors) باستخدام مفتاح idempotency وقراءة المورد الحالي قبل إعادة كتابة غير مؤكدة النتيجة. وإذا فشل إنشاء أُرسل بلا مفتاح قبل إعادة معرّف، فالنتيجة مجهولة؛ لا تخمّن بإنشاء آخر. أما `complete_checkout` فقاعدته أشد: لا تكرره أبداً بعد رد غير مؤكد. وتبقى صفحة التاجر مسار المشتري عندما يمنع `requires_escalation` أو نقص معلومات الدفع الوكيل من الإكمال.

تعامل مع معرّفات الدفع وروابطه ورموز الوصول وأدوات الدفع على أنها بيانات حساسة. تقول Shopify إن معرّف الدفع و `continue_url` يتضمنان مفاتيح وصول؛ فلا تضعهما في السجلات أو التحليلات ولا تشارك الرابط إلا مع المشتري. وتقول [مرجعية المصادقة](https://shop.dev/docs/authentication) أرسل رمز Shop فقط في ترويسة التفويض إلى `https://mcp.shop.com/`. وقد تتضمن أداة الدفع بيانات اعتماد؛ لا تطبعها ولا تسجلها.

سبق أن غطت BIG CHANGE [أدوات إتمام الشراء لوكلاء المتصفح](https://bigchange.ai/blog/shopify-webmcp-browser-agent-checkout) من Shopify. ويصف إصدار MCP المستضاف هذا مساراً منفصلاً يبدأ باكتشاف الكتالوج. توضح ملاحظة الإصدار وأدلة Shopify ما يمكن للمطورين استدعاؤه والردود التي عليهم فحصها؛ لكنها لا تثبت زيادة التحويل أو الاعتمادية تحت الضغط أو نجاح عملية شراء أجرتها BIG CHANGE.

## المصادر ومزيد من القراءة

- [سجل تغييرات مطوري Shopify، «إضافة التسوق وإتمام Shop Pay إلى أي وكيل عبر Shop MCP»، 13 أكتوبر 2026](https://shopify.dev/changelog/posts/add-shopping-and-shop-pay-checkout-to-any-agent-with-shop-mcp). نطاق الإطلاق، نقطة النهاية المستضافة، 17 أداة، الوصول إلى البحث، مسارات إتمام الشراء وحالة webhooks عند الإطلاق.
- [نظرة عامة على Shop MCP ودليل الاتصال](https://shop.dev/docs/). البروتوكول الحالي ومتطلبات العميل وتسجيل الدخول.
- [Shopify، العثور على المنتجات](https://shop.dev/docs/search). حقول البحث واختيار الخيارات ووحدات السعر وتحذيرات عوامل التصفية.
- [Shopify، السلال وإتمام الشراء](https://shop.dev/docs/checkout). نطاق التاجر ومعاني الحالات وإكمال الدفع والتعامل مع النتائج غير المؤكدة.
- [Shopify، الأخطاء وإعادة المحاولة](https://shop.dev/docs/errors). قواعد استعادة القراءة والكتابة.
- [Shopify، المصادقة](https://shop.dev/docs/authentication). الوصول إلى حساب Shop والتعامل مع الرموز.

## Sources

- [سجل تغييرات مطوري Shopify، إضافة التسوق وإتمام Shop Pay إلى أي وكيل عبر Shop MCP](https://shopify.dev/changelog/posts/add-shopping-and-shop-pay-checkout-to-any-agent-with-shop-mcp) — تاريخ الإطلاق ونقطة النهاية المباشرة و17 أداة والبحث في الكتالوج دون مفتاح ومسارات Shop وخارج Shopify وغياب webhooks عند الإطلاق ومفتاح Dev Dashboard لحدود أعلى. هذه ادعاءات Shopify وليست نتائج مستقلة.
- [نظرة عامة على Shop MCP](https://shop.dev/docs/) — نقطة نهاية مستضافة، إصدار MCP بتاريخ 2026-07-28، وإصدار مستند UCP بتاريخ 2026-08-25، تاجر واحد لكل عملية إتمام وتأكيد الطلب المكتمل.
- [Shop MCP، توصيل وكيل](https://shop.dev/docs/connect) — عنوان URL الجذر ومتطلبات البروتوكول ومسارات العميل وتحميل skill وفحص الاتصال للقراءة فقط.
- [Shop MCP، البدء السريع](https://shop.dev/docs/quickstart) — طلب بحث JSON-RPC الموثق والعناوين وشكل الاستجابة ووحدات السعر والأخطاء.
- [Shop MCP، العثور على المنتجات](https://shop.dev/docs/search) — الاستعلام وعوامل التصفية والسياق والخيار المميز والتحذيرات.
- [Shop MCP، السلال وإتمام الشراء](https://shop.dev/docs/checkout) — سلوك أدوات السلة والدفع ونطاق التاجر وحقول الحالة وموافقة الإنسان على الدفع والمعرّفات الحساسة والتعامل مع الإكمال غير المؤكد.
- [Shop MCP، الأخطاء وإعادة المحاولة](https://shop.dev/docs/errors) — استعادة القراءة ومفتاح idempotency لعمليات الكتابة غير المتعلقة بالدفع وعدم تكرار complete_checkout بعد نتيجة غير مؤكدة.
- [Shop MCP، المصادقة](https://shop.dev/docs/authentication) — نطاق رمز Shop وتدفق OAuth للأجهزة وحماية بيانات الاعتماد الخاصة.
- [Shop MCP، الموافقة على شراء خارج Shopify](https://shop.dev/docs/approvals) — مسار منفصل لموافقة المشتري والبطاقة لإتمام الشراء لدى تاجر لا يستخدم Shopify.