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

يربط هذا الدليل متجرًا على WooCommerce بـ Tajo. ويتكوّن التكامل من شقّين يعملان معًا:

• إضافة Tajo for WooCommerce: تلتقط أحداث التفاعل في الوقت الفعلي (الطلبات والسلات والمبالغ المستردة والمراجعات وإرسال النماذج) داخل WordPress وتسلّمها إلى Tajo عبر صندوق صادر دائم وموقَّع.
• اتصال WooCommerce REST: يقرأ Tajo عملاء متجرك وطلباته ومنتجاته وقسائمه ومبالغه المستردة ومراجعاته من أجل الاستيراد التاريخي والمزامنة المستمرة. راجع مرجع موصّل WooCommerce للإعداد المعتمد على REST وحده.

أما أتمتة التسويق نفسها (البريد الإلكتروني وSMS وواتساب عبر Brevo وغيره من مزودي التفاعل) فتُضبط داخل Tajo، لا داخل الإضافة. ومهمة الإضافة هي إخراج أحداث جديرة بالثقة من WordPress.

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

• WordPress 6.3+ مع صلاحية مسؤول
• PHP 7.4+
• WooCommerce 7.0+ (تعمل الإضافة أيضًا على مواقع WordPress من دون WooCommerce، وتبقى محوّلات التجارة غير نشطة ببساطة)
• حساب Tajo مع اتصال WordPress مُنشأ
• HTTPS على نقطة نهاية Tajo (متوفر دائمًا في Tajo المستضاف)

الخطوة 1: ثبّت إضافة Tajo for WooCommerce

التثبيت اليدوي

# Download the plugin
cd wp-content/plugins
wget https://tajo.io/downloads/woocommerce/tajo-woocommerce-latest.zip

# Verify and unzip
unzip tajo-woocommerce-latest.zip

ثم فعّلها من لوحة تحكم WordPress:

1. انتقل إلى Plugins ← Installed Plugins
2. ابحث عن “Tajo for WooCommerce”
3. انقر على Activate

يمكنك أيضًا رفع ملف zip مباشرة عبر Plugins ← Add New ← Upload Plugin. ويُنشر مع كل إصدار مجموع تحقق SHA-256 على tajo.io/downloads/woocommerce/. الإضافة غير مدرجة بعد في دليل WordPress.org؛ والتثبيت اليدوي هو المسار المدعوم اليوم.

الخطوة 2: اضبط الاتصال

انتقل إلى WooCommerce ← Tajo (في المواقع التي لا تستخدم WooCommerce: Settings ← Tajo) وأدخل القيم الثلاث من اتصال WordPress في Tajo:

لا توجد ثوابت مفاتيح API تُضاف إلى wp-config.php. وتبقى الأحداث في طابور آمن داخل صندوق الصادر المحلي إلى أن تُحفظ القيم الثلاث.

ثم تحقق من المسار من طرف إلى طرف:

1. انقر على Queue test event، ثم Process now.
2. يجب أن يُظهر جدول صندوق صادر التسليم الحدث بحالة مُسلَّم.
3. في Tajo، تأكد من وصول حدث connection.test على اتصال WordPress.

ما الذي ترسله الإضافة

كل حدث هو مغلّف مضغوط ومُقلَّص حفاظًا على الخصوصية، موقَّع بـ HMAC-SHA256. ولا يغادر WordPress سوى حقول هوية التفاعل (البريد الإلكتروني والهاتف والمعرّفات المحلية) إضافة إلى بيانات وصفية محدودة للحدث، ولا تغادره أبدًا الأسماء ولا العناوين البريدية ولا عناوين IP ولا وكلاء المستخدم ولا نصوص التعليقات ولا حقول النماذج الاعتباطية ولا ملاحظات الطلبات ولا تفاصيل الدفع.

أحداث WooCommerce

تحمل أحداث الطلبات رقم الطلب وحالته وعملته وإجمالياته وبنوده وعناوين URL جاهزة للمراجعة أو إعادة الطلب، وهذا يكفي لأتمتة ما بعد الشراء واستعادة العملاء دون طلب API إضافي.

أحداث WordPress

• contact.created / contact.updated / contact.deleted لحسابات المستخدمين
• content.published / content.updated / content.unpublished للمحتوى العام
• comment.created / comment.status_changed لتعليقات الزوار ومراجعات المنتجات (أما ملاحظات طلبات WooCommerce الداخلية والـ pingbacks والـ trackbacks فلا تُرسل أبدًا)
• form.submitted لعمليات الإرسال الناجحة عبر Contact Form 7 وWPForms وGravity Forms وFluent Forms، ولا تُستخرج سوى حقول هوية البريد الإلكتروني والهاتف المُصنَّفة والبيانات الوصفية للنموذج؛ أما الحقول المُرسلة الاعتباطية فتُهمل

الموثوقية: صندوق صادر التسليم

لا تطلق الإضافة الأحداث نحو Tajo مباشرة أثناء تحميل الصفحة. فكل حدث يُكتب أولًا في جدول صندوق صادر محلي، ثم يُسلَّم عبر WP-Cron مع:

• تراجع أسّي محدود (حتى 8 محاولات، مع احترام Retry-After)
• رسائل ميتة مع Replay dead letters بنقرة واحدة في لوحة الإدارة
• حدود احتفاظ تمنع أي نقطة نهاية غير متاحة من تكديس البيانات الشخصية (المُسلَّم: 7 أيام؛ في الطابور: 30 يومًا؛ الرسائل الميتة: 30 يومًا بعد آخر تحديث)
• معرّفات أحداث مُعادة الاستخدام بأمان، فلا تُنتج إعادات المحاولة والإعادات أي تكرار في الوجهة

إذا عطّلت استضافتك WP-Cron (DISABLE_WP_CRON)، فاستدعِ wp-cron.php من مجدول حقيقي مرة واحدة على الأقل كل دقيقة.

القبول لا يُستنتج أبدًا

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

do_action(
    'tajo_engagement_emit',
    'consent.updated',
    array( 'email' => $email ),
    array( 'policyVersion' => '2026-07' ),
    array(
        array(
            'channel'  => 'email',
            'status'   => 'opt_in',        // or 'opt_out'
            'purpose'  => 'marketing',
            'source'   => 'newsletter_checkbox',
            'evidence' => array( 'formId' => 'newsletter-footer', 'field' => 'marketing_email' ),
        ),
    ),
    gmdate( 'c' )
);

ويتيح الخطاف نفسه لأي إضافة أو قالب إرسال أحداث مخصصة؛ فكل شيء يمر عبر المنقّي وصندوق الصادر والتوقيع ذاتها.

الخطوة 3: الاستيراد التاريخي

تغطي الأحداث في الوقت الفعلي كل ما يجري بدءًا من التثبيت. أما التاريخ السابق للإضافة فيستورده اتصال WooCommerce REST في Tajo: العملاء والطلبات والمنتجات والقسائم والمبالغ المستردة والمراجعات الموجودة، ويُضبط بالكامل من جهة Tajo بمفتاح WooCommerce REST API (WooCommerce ← Settings ← Advanced ← REST API، بصلاحية القراءة). راجع مرجع موصّل WooCommerce للتفاصيل.

الخصوصية وGDPR

• تُسجَّل الإضافة لدى Tools ← Export Personal Data وTools ← Erase Personal Data في WordPress؛ وتُصدَّر أحداث صندوق الصادر المحتفظ بها لبريد إلكتروني مطابق أو تُمحى محليًا.
• يتشارك المحو والتسليم قفلًا يفشل مغلقًا، فلا يمكن لعملية محو أن تُبلغ عن اكتمالها بينما حمولة ما في منتصف الإرسال.
• يغطي المحو المحلي صندوق صادر WordPress وحده، فقدّم الطلب المقابل في Tajo من أجل البيانات في الوجهة.
• يوقف إلغاء التفعيل التسليم مؤقتًا لكنه يبقي الإعدادات والأحداث في الطابور؛ أما حذف الإضافة فيزيل صندوق الصادر والإعدادات والسر والجداول الزمنية نهائيًا.

التوافق

• HPOS: تعلن الإضافة توافقها مع WooCommerce High-Performance Order Storage ولا تستخدم سوى كائنات CRUD والخطافات العامة.
• WooCommerce Subscriptions: تُلتقط تغيّرات حالة الاشتراك عندما تكون التوسعة نشطة.
• Multisite: يُنظّف إلغاء التثبيت كل موقع في الشبكة.

مرجع التشغيل

يتاح للمسؤولين اكتشاف الخادم إلى خادم والتحكم في صندوق الصادر عبر مصادقة Application Password:

استكشاف الأخطاء

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

• مرجع موصّل WooCommerce: مزامنة REST، وتفاصيل توقيع webhook، ومفاتيح الإعداد
• مزامنة العملاء: تعيين عملاء WooCommerce داخل نظام السجل لديك
• اضبط أتمتة السلات المتروكة وما بعد الشراء واستعادة العملاء في Tajo باستخدام أحداث cart.updated وorder.placed وorder.fulfilled