إنتقل إلى المحتوى الرئيسي

تكامل Shopify

توفّر Alkax تطبيق Shopify مستضافًا واحدًا على commerce.alkax.io. يبدأ إعداد التكامل في مشروع مطوّري Alkax، وليس في شاشة إعداد تاجر مستقلة.

يشكّل مشروع المطوّرين حدود المستأجر. يمكن للمشروع ربط عدة متاجر Shopify، ويختار كل اتصال متجر بيئة Sandbox أو Production التابعة للمشروع.

ربط متجر​

  1. افتح لوحة المطورين (Developer Console) واختر المشروع الذي ينبغي أن يمتلك متجر Shopify.
  2. افتح التجارة الإلكترونية (E-commerce) ← Shopify.
  3. أدخل نطاق المتجر *.myshopify.com.
  4. اختر Sandbox أو Production.
  5. اختر ربط المتجر (Connect store).
  6. أكمل التثبيت والتفويض في Shopify على commerce.alkax.io.

تنشئ Alkax رمز تسليم اتصال قصير العمر. تستبدله بيئة تشغيل Shopify المشتركة بعد مصادقة Shopify وتربط المتجر بما يلي:

DeveloperProject.Id   -> tenant identity
DeveloperEnvironment  -> Sandbox or Production execution/billing context
Shopify shop domain   -> connected store

لا يمكن أن يرتبط المتجر بأكثر من مشروع Alkax نشط واحد في الوقت نفسه.

ما يُضبط تلقائيًا​

لا ينسخ المطورون مفتاح API من Alkax إلى Shopify. عند نجاح الربط، تصدر Alkax بيانات اعتماد مخصصة للتكامل فقط للمشروع والبيئة المختارين، وتعيدها إلى بيئة تشغيل commerce.alkax.io المشتركة فقط.

لذلك تستخدم استدعاءات تكامل Shopify إسناد المشروع والبيئة والحدود ومسار الفوترة نفسها التي تستخدمها حركة منصة المطورين المعتادة.

تبقى بيانات الاعتماد على الخادم. ولا تُضمّن أبدًا في إضافة إتمام الشراء أو إضافة حساب العميل أو استجابة المتصفح.

الإكمال التلقائي للعنوان​

الإكمال التلقائي للعنوان هو الإمكانية الأساسية في Shopify. تستدعي إضافة إتمام الشراء بيئة التشغيل المشتركة برمز جلسة Shopify. تحدّد البيئة مستأجر المشروع من المتجر وتستدعي:

GET /api/v1/addresses/suggestions?q=<query>&countryCode=<optional>&limit=5
X-Alkax-Key: <managed project/environment credential>

تأتي الاقتراحات من بحث العناوين الخاص بـ Alkax. يظل الإدخال اليدوي للعنوان في Shopify متاحًا إذا تعذّر الوصول إلى Alkax مؤقتًا.

يخضع توفر إضافات عنوان إتمام الشراء لمتطلبات Shopify الحالية الخاصة بخطة إتمام الشراء وبيانات العملاء المحمية والوصول إلى الشبكة.

تتبّع الطلبات الاختياري​

يُفعّل تتبّع الطلبات لكل متجر متصل من لوحة المطورين ← التجارة الإلكترونية ← Shopify.

عندما يختار المطوّر تفعيل التتبّع (Enable tracking):

  1. تسجّل Alkax طلب التتبّع لاتصال المشروع والمتجر.
  2. يفتح المسار تطبيق Shopify المثبّت.
  3. يطلب Shopify من المتجر منح النطاق الاختياري read_orders.
  4. يبلغ commerce.alkax.io تكامل المشروع المرجعي بهذه الموافقة.
  5. يمكن لخطافات الويب الجديدة orders/create إنشاء عمليات توصيل Alkax ضمن نطاق المشروع.
  6. تستطيع إضافة حالة الطلب في حساب العميل عرض حالة توصيل Alkax بعد التحقّق من أن العميل المسجّل دخوله يملك الطلب. يُخفى التتبّع للجلسات المجهولة أو عندما يعجز Shopify عن التحقّق من الملكية.

يسري تعطيل التتبّع في لوحة المطورين على الاتصال المرجعي حتى إذا لم يُلغَ إذن Shopify يدويًا بعد. ويمكن للتطبيق المثبّت أيضًا إلغاء الوصول غير المستخدم إلى الطلبات.

بيئة تشغيل مشتركة متعددة المستأجرين​

Alkax Developer Project
  └── E-commerce
       └── Shopify
            ├── store-a.myshopify.com -> Sandbox
            └── store-b.myshopify.com -> Production
                         |
                         v
                commerce.alkax.io
             shared Shopify runtime
                         |
              tenant = DeveloperProject.Id
                         |
                         v
                  Alkax platform

تمتلك قاعدة بيانات تطبيق Alkax حالة الاتصال والميزات المرجعية. وتمتلك قاعدة بيانات بيئة Shopify حالة Shopify التشغيلية فقط: جلسات OAuth وربط المستأجر المحسوم وإيصالات خطافات الويب والربط بين طلب Shopify وتوصيل Alkax.

تتضمن الصفوف التشغيلية معرّفات المشروع والبيئة ليكون إسناد المستأجر صريحًا وقابلًا للتدقيق.

أمان الاتصال​

ينشئ المشروع رمز تسليم عشوائيًا قصير العمر. لا تخزّن Alkax سوى تجزئته. تحتفظ بيئة Shopify بالرمز مدة تكفي لإكمال تدفق OAuth في Shopify، ثم تستبدله عبر نقطة نهاية Alkax مصادَق عليها بهوية الخدمة.

الاستبدال لمرة واحدة. يمسح التفعيل الناجح رمز التسليم وينشئ تلقائيًا بيانات اعتماد المشروع والبيئة المستخدمة لاتصال ذلك المتجر.

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

هوية التوصيل وإعادة المحاولة​

يُربط كل طلب Shopify بطريقة حتمية باستخدام نطاق المتجر وShopify Order GID. يستخدم التكامل قيمًا ثابتة لعدم تكرار الأثر والتفعيل في Alkax ويخزّن معرّفات خطافات Shopify، لذلك لا تنشئ إعادات المحاولة في Shopify أو Alkax توصيلات مكررة.

عندما لا يوفّر Shopify إحداثيات الوجهة، يستطيع التكامل حل رمز Plus Code من Alkax المضمّن في العنوان المختار. إذا لم توجد إحداثيات ولا رمز Alkax قابل للاستخدام، يُسجّل الطلب بحالة awaiting_address؛ ولا يُنشأ توصيل عند 0,0.

إعدادات القائمين على الصيانة​

يوجد التنفيذ في integrations/shopify/ ويُنشر بصورة منفصلة عن واجهة الويب الرئيسية.

إعدادات التشغيل المطلوبة:

DATABASE_URL=postgresql://...
SHOPIFY_API_KEY=...
SHOPIFY_API_SECRET=...
SHOPIFY_APP_URL=https://commerce.alkax.io
SCOPES=

ALKAX_API_URL=https://<alkax-api-host>
ALKAX_SHOPIFY_SERVICE_KEY=<shared service identity>

يجب ضبط القيم المطابقة في نشر API الخاص بـ Alkax:

ShopifyIntegration:AppUrl=https://commerce.alkax.io
ShopifyIntegration:ServiceKey=<same shared service identity>

التحقّق المحلي:

cd integrations/shopify
npm install
npm run prisma:generate
npm test
npm run typecheck
npm run build

راجع منصة المطورين وDelivery Intelligence لعقود المشروع والحصة والتوصيل الأساسية.