أحداث المتجر المخصص

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

قبل أن تبدأ

• ربط المتاجر متاح عندما تشمل باقتك ربط المتاجر. وقد تحدد باقتك أيضًا عدد الروابط النشطة.
• المالكون والمسؤولون وحدهم ينشئون الربط ويوقفونه ويستبدلون سره.
• تحتاج مسارًا واحدًا على الأقل، لأن طلبات عروض الأسعار تفتح فيه فرصًا.
• يجب أن يستطيع متجرك إرسال طلب POST عبر HTTPS من خادمه، ويُفضَّل من مهمة في الخلفية.

إنشاء الربط

1. افتح المنتجات من الشريط الجانبي، ثم ربط المتاجر.
2. تحت ربط متجر اكتب اسم المتجر.
3. اجعل منصة المتجر على منصتنا أو متجر مخصص.
4. اختر المرحلة في تبدأ طلبات عروض الأسعار في، واختر إن شئت شخصًا في إسناد الفرص الجديدة إلى.
5. اترك سر التوقيع من Shopify أو سلة فارغًا.
6. اختر ربط متجر.
7. انسخ سر التوقيع، فهو يظهر مرة واحدة فقط.
8. انسخ العنوان الذي يرسل إليه متجرك من بطاقة الربط.

احفظ القيمتين في إعدادات بيئة متجرك، لا في الكود:

STORE_EVENTS_URL=STORE_ADDRESS
STORE_EVENTS_SECRET=YOUR_STORE_SECRET

الطلب

أرسل كل حدث طلب POST إلى عنوان الربط، مستند JSON في الجسم، ومعه هذه الترويسات:

يجب أن يكون الوقت ضمن 5 دقائق من ساعة الخادم، فأبقِ ساعة متجرك مضبوطة. ويُفحص التوقيع على البايتات الخام التي ترسلها، فوقّع السلسلة نفسها التي تضعها في الجسم.

BODY='{"event":"order.created","order":{"id":"1001","number":"1001","status":"pending","currency":"SAR","total":"1250.50","placed_at":"2026-11-06T10:00:00Z","customer":{"name":"Ali Hassan","email":"ali@example.com"}}}'
TS=$(date +%s)
SIG=$(printf '%s.%s' "$TS" "$BODY" | openssl dgst -sha256 -hmac "YOUR_STORE_SECRET" | sed 's/^.* //')

curl -X POST "STORE_ADDRESS" \
  -H "Content-Type: application/json" \
  -H "X-CRM-Timestamp: $TS" \
  -H "X-CRM-Signature: sha256=$SIG" \
  --data "$BODY"

الأحداث

وأي قيمة أخرى في event تُرفض بـ422.

مستند الطلب

{
  "event": "order.updated",
  "order": {
    "id": "1001",
    "number": "SO-1001",
    "status": "paid",
    "currency": "SAR",
    "total": "1250.50",
    "placed_at": "2026-11-06T10:00:00Z",
    "updated_at": "2026-11-06T10:05:00Z",
    "customer": {
      "name": "Ali Hassan",
      "email": "ali@example.com",
      "phone": "+966500000002",
      "company": "Hassan Cafe"
    },
    "items": [
      {"sku": "ESP-1", "name": "Espresso machine", "quantity": 1, "total": "1250.50"}
    ],
    "attribution": {
      "source": "google",
      "medium": "cpc",
      "campaign": "ramadan-sale"
    }
  }
}

التقط وسوم الحملة (utm_source وutm_medium وutm_campaign) عند دخول الزائر واحفظها مع الطلب، لتحملها attribution.

الحالات

كيف يُطبَّق الطلب

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

مستند عرض السعر

يستخدم quote.requested حقول الطلب نفسها تحت المفتاح quote. وينشئ فرصة واحدة عنوانها رقم العرض واسم العميل، في المرحلة المختارة للربط، وفيها بند لكل عنصر. ومبلغ الفرصة مجموع العناصر، أو total إن لم توجد عناصر. والحدث الثاني بمعرف العرض نفسه يُتجاهل.

مستند المنتج

{
  "event": "product.upserted",
  "product": {
    "id": "P-77",
    "name": "Espresso machine",
    "sku": "ESP-1",
    "price": "1250.50",
    "currency": "SAR",
    "active": true,
    "updated_at": "2026-11-06T09:00:00Z"
  }
}

يُعثر على المنتج بـid، وإلا بـsku، فالمنتج المكتوب يدويًا من قبل يُربط ولا يُكرر.

الردود

الإرسال من متجرك

أرسل من مهمة في الطابور بعد حفظ الطلب، فلا يؤخر ربط بطيء أو متوقف عملية الشراء. وأعد المحاولة عند 5xx و429 وأخطاء الاتصال مع مهلة تطول. ولا تُعد 403 قبل إصلاح الساعة أو السر، ولا تُعد إرسال 422 دون تغيير.

final class StoreEvents
{
    public function send(string $event, string $key, array $document): void
    {
        $body = json_encode(['event' => $event, $key => $document], JSON_THROW_ON_ERROR | JSON_UNESCAPED_UNICODE);
        $time = (string) time();
        $signature = 'sha256=' . hash_hmac('sha256', $time . '.' . $body, getenv('STORE_EVENTS_SECRET'));

        $curl = curl_init(getenv('STORE_EVENTS_URL'));
        curl_setopt_array($curl, [
            CURLOPT_POST => true,
            CURLOPT_POSTFIELDS => $body,
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_TIMEOUT => 5,
            CURLOPT_HTTPHEADER => ['Content-Type: application/json', 'X-CRM-Timestamp: ' . $time, 'X-CRM-Signature: ' . $signature],
        ]);
        curl_exec($curl);
        $status = curl_getinfo($curl, CURLINFO_RESPONSE_CODE);
        curl_close($curl);

        if ($status === 0 || $status === 429 || $status >= 500) {
            throw new RuntimeException('Store event not delivered, retry later.');
        }
    }
}

تجربة الربط

1. أرسل order.created لعميل تجريبي بحالة pending.
2. تأكد أن بطاقة الربط تُظهر آخر حدث مع الوقت، وأن العميل ظهر في جهات الاتصال مع طلبه.
3. أرسل order.updated مع "status": "paid" وupdated_at أحدث. يجب أن يُحسب الطلب الآن مبيعًا.
4. أرسل order.updated مع "status": "cancelled" وupdated_at أحدث. يجب أن يخرج الطلب من أرقام المبيعات.

معلومات مفيدة

• لا تُستورد الطلبات السابقة للمتاجر المخصصة، فلا يصل إلا ما ترسله من الآن.
• استبدال السر ينشئ سرًا جديدًا فورًا. والأحداث الموقعة بالسر القديم تُرفض بـ403 منذ تلك اللحظة، فحدّث متجرك فورًا وأعد إرسال ما رُفض في الأثناء.
• إيقاف يوقف الربط، فترد الأحداث 404 حتى يُعاد تشغيل الربط.
• العميل الممحو يبقى ممحوًا. والأحداث اللاحقة لطلباته تُبقي المجاميع صحيحة ولا تعيد أي بيانات شخصية.

حل المشكلات