دليل التكامل مع Shopify

يربط Tajo بين Shopify وBrevo في موضعين. يحوّل تطبيق Tajo لـ Shopify أحداث Shopify webhook إلى عمليات كتابة في Brevo فور وصولها. وتنقل قواعد المزامنة، التي يبنيها وكيل ويوافق عليها شخص، السجلات إلى Brevo وفق جدول زمني. تشرح هذه الصفحة الاثنين، ثم أدوات Shopify التي يقدّمها Tajo عبر MCP.

المتطلّبات المسبقة

قبل بدء التكامل، تأكّد من توفّر ما يلي:

• متجر Shopify على أي خطة (Basic أو Shopify أو Advanced أو Plus)
• حساب Tajo (Tajo في مرحلة الوصول المبكر)
• حساب Brevo، وهو وجهة المزامنة
• صلاحية المسؤول على متجرك في Shopify

الخطوة 1: اربط متجرك على Shopify

Tajo في مرحلة الوصول المبكر. تطبيق Shopify غير مدرج في Shopify App Store، ولا يوجد رابط تثبيت ذاتي. تواصل مع الفريق لإعداد حسابك. بعد أن تصبح مساحة عملك في Tajo جاهزة:

1. في Tajo، افتح Connections.
2. أدخل نطاق متجرك على myshopify.com واختر Connect Shopify. يعرض Shopify النطاقات التي يطلبها Tajo، ويعيدك إلى Tajo عند الموافقة عليها.
3. راجع الغرض من كل نطاق، وما يكتبه Tajo في Shopify، في شرح أذونات Shopify.

الخطوة 2: ما يرسله تطبيق Tajo لـ Shopify إلى Brevo

يتحقق التطبيق من كل Shopify webhook، ويخزّنه، ويضعه في قائمة الانتظار ويعالجه فورًا. تنتظر مواضيع العملاء والمنتجات نحو أربع ثوانٍ أولًا. لا توجد نافذة دفعات. وتُعاد محاولة المهمة الفاشلة مع تراجع تدريجي.

مواضيع Webhook

يشترك تطبيق Tajo لـ Shopify في مواضيع Shopify webhook التالية:

تتم أيضًا معالجة webhooks الخصوصية الإلزامية في Shopify (طلب بيانات العميل، وحذف بيانات العميل، وحذف بيانات المتجر). ولا يشترك التطبيق في carts/*. وتأتي السلات المتروكة من مواضيع checkouts/*.

ما يصل إلى Brevo:

لا يضيف التطبيق زر “Notify me” إلى قالب متجرك. يجب أن يأتي طلب الإشعار بعودة المنتج إلى المخزون من واجهة متجرك، مثلًا من زر تضيفه أنت.

البيانات الموجودة

عند التثبيت، يستورد التطبيق عملاءك الحاليين كجهات اتصال في Brevo. وتبدأ المزامنة التاريخية الكاملة من صفحة المزامنة في التطبيق. وفي الخطط المدفوعة تستورد أيضًا المنتجات والمجموعات والشركات والطلبات.

الخطوة 3: ابنِ قاعدة مزامنة مع الوكيل

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

1. في Tajo، افتح Agents واطلب المزامنة من Brevo Integration Architect بلغة عادية. مثلًا: “أرسل عملاء Shopify الذين وافقوا على التسويق عبر البريد الإلكتروني إلى Brevo كجهات اتصال.”
2. يفحص الوكيل موصّل Shopify. تُرجع عيّنته أسماء الحقول وأنواعها، ولا تُرجع قيم العملاء أبدًا.
3. يقترح قاعدة تتضمن خريطة حقول ومرشّحًا، ثم يتحقق من خريطة الحقول مقابل إجراء Brevo ويجري تشغيلًا تجريبيًا جافًا للمسودة. لا تقرأ أي من الخطوتين سجلات العملاء.
4. يحفظ القاعدة كمسودة. يمكنك أيضًا البدء من قالب ضمن Connections > Syncs and mappings > New sync from template.
5. يشغّل Request publish approval معاينة على متجرك. تقرأ 10 سجلات على الأكثر، ولا تكتب شيئًا في Brevo ولا تحرّك المؤشر. وتسجّل الأعداد فقط: السجلات المسحوبة، والمؤهلة، والمطابَقة، والمرفوضة من المرشّح، إضافة إلى أخطاء المطابقة. إذا فشلت المعاينة، لا يُنشأ أي طلب موافقة.
6. يوافق شخص على الطلب في صفحة Approvals، مع مبرّر مكتوب. ترتبط الموافقة بملخّص SHA-256 للقاعدة وتنتهي صلاحيتها بعد 30 دقيقة. ثم تعرض صفحة القاعدة Publish approved version.

تعديل قاعدة منشورة يعيدها إلى مسودة. وتمر مجددًا بالمعاينة والموافقة قبل أن تعمل مرة أخرى.

قاعدة حقيقية

هذا هو قالب Shopify customers -> Brevo contacts كما يعرّفه Tajo:

sourceSlug: "shopify",
sourceResource: "customers",
destinationSlug: "brevo",
destinationAction: "upsert_contact",
fieldMap: [
  { source: "email", destination: "email", transform: "toLowerCase" },
  { source: "first_name", destination: "attributes.FIRSTNAME" },
  { source: "last_name", destination: "attributes.LASTNAME" },
  { source: "phone", destination: "attributes.PHONE" },
  { source: "total_spent", destination: "attributes.TOTAL_SPENT", transform: "toNumber" },
  { source: "orders_count", destination: "attributes.ORDERS_COUNT", transform: "toNumber" },
  { source: "tajo_email_marketing_consent", destination: "attributes.OPT_IN", transform: "toBoolean" },
  { source: "tags", destination: "attributes.SHOPIFY_TAGS" },
  { source: "id", destination: "attributes.SHOPIFY_ID", transform: "toString" },
  { source: "created_at", destination: "attributes.SHOPIFY_CREATED_AT" },
  { source: "updated_at", destination: "attributes.SHOPIFY_UPDATED_AT" },
],
filterExpression:
  "($json.tajo_email_marketing_consent === true) && ($json.tajo_email_suppressed === false)",

المرشّح هو فحص الموافقة. يستخرج Tajo القيمتين من email_marketing_consent.state في Shopify، أو من العلامة الأقدم accepts_marketing. ولا يمكن نشر قاعدة تكتب جهات اتصال في Brevo بدونه. أما قالب Shopify الآخر، Shopify orders → Brevo orders، فيسجّل الطلبات في Brevo للمشترين الذين وافقوا على التسويق عند الدفع.

متى تعمل القاعدة

• تعمل قواعد مزامنة جهات الاتصال كل 15 دقيقة افتراضيًا. يبدأ كل تشغيل من مؤشر القاعدة.
• تحتوي صفحة القاعدة النشطة على زر Test run (1 batch).
• تعمل قاعدة Shopify orders → Brevo orders النشطة والمنشورة أيضًا كل 15 دقيقة. يبدأ أول تشغيل مجدول لها قبل تلك اللحظة ببضع دقائق ولا يرسل أي طلبات أقدم. ويرسل كل تشغيل لاحق الطلبات التي حُدّثت منذ التشغيل السابق.
• لا تصل الطلبات السابقة إلى Brevo إلا عندما تشغّل القاعدة بنفسك: باستخدام Test run (1 batch)، أو بأن تطلب من وكيل Sync Operator تشغيلها.
• لا تعمل قاعدة الطلبات وفق الجدول إلا مع مرشّح موافقة المشتري على التسويق الموجود في القالب. أما القاعدة التي عُدّل مرشّحها فلا تعمل إلا عندما تبدأ تشغيلها بنفسك.
• بعد خمس عمليات تشغيل فاشلة متتالية، توقف القاعدة نفسها مؤقتًا وتعرض صفحتها آخر خطأ. أصلح السبب، ثم انشرها مجددًا.

يُدرج كل تشغيل في سجل تشغيلات القاعدة مع عدد السجلات المقروءة والمكتوبة والفاشلة، ومدته.

ما يقرؤه موصّل Shopify وما يكتبه

لا تكتب قواعد المزامنة إلا في الوجهة، وهي هنا Brevo. ولا تكتب في Shopify أبدًا.

يطلب تطبيق Tajo لـ Shopify 12 نطاقًا وينفّذ قائمة قصيرة من عمليات الكتابة في Shopify، مثل إلغاءات الموافقة ووسوم الولاء. تسرد صفحة شرح أذونات Shopify كل نطاق وكل عملية كتابة، مع ما يُطلقها.

تصل الوكلاء ومضيفات MCP إلى المتجر عبر موصّل Shopify:

يصرّح الموصّل أيضًا بتعديل للمخزون. ويحتاج ذلك إلى النطاق write_inventory، الذي لا يطلبه تطبيق Tajo لـ Shopify.

الخطوة 4: استخدم أدوات Shopify عبر MCP

يقدّم Tajo موصّل Shopify كخادم MCP على https://alto.tajo.io/mcp/connectors/shopify. أضفه إلى Claude Code:

claude mcp add --transport http tajo-shopify https://alto.tajo.io/mcp/connectors/shopify

يكتشف المضيف خادم OAuth الخاص بـ Tajo ويفتح صفحة تسجيل الدخول إلى Tajo. الوصول مقتصر على حسابات الوصول المبكر. يوفّر الخادم 12 أداة:

استكشاف الأخطاء وإصلاحها

• جهات الاتصال لا تظهر في Brevo: راجع جهات اتصال مفقودة في Brevo.
• قاعدة لا تعمل، أو أوقفت نفسها مؤقتًا: راجع البيانات لا تتم مزامنتها.

الخطوات التالية

• فهم مزامنة البيانات، كيف تتصرف قواعد المزامنة
• شرح أذونات Shopify، كل نطاق وكل عملية كتابة
• Shopify + Brevo، دليل التكامل
• تواصل مع الفريق لإعداد حسابك