متجر مخصص

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

قبل أن تبدأ

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

أنشئ الربط

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

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

STORE_EVENTS_URL=ADDRESS_FOR_YOUR_STORE
STORE_EVENTS_SECRET=YOUR_SIGNING_SECRET

وقّع كل طلب

أرسل POST بجسم JSON وترويستين:

BODY هو البايتات نفسها التي ترسلها. الطلب الذي يبتعد وقته أكثر من 5 دقائق عن ساعة الخادم يُرفض، فأبقِ ساعة خادمك مضبوطة.

$body = json_encode(['event' => $event, $key => $document], JSON_THROW_ON_ERROR);
$time = (string) time();
$signature = 'sha256='.hash_hmac('sha256', $time.'.'.$body, getenv('STORE_EVENTS_SECRET'));
// POST $body to STORE_EVENTS_URL with Content-Type: application/json,
// X-CRM-Timestamp: $time and X-CRM-Signature: $signature

أرسل من مهمة في الخلفية بعد حفظ الطلب، حتى لا يؤخر الرد البطيء أي عملية شراء. وأعد المحاولة عند رد 5xx أو انتهاء المهلة فقط.

الأحداث

حقول الطلب وطلب العرض

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

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

الحالات

paid وprocessing وcompleted وdelivered تُحسب مبيعات، وأول واحدة منها تحوّل العميل المحتمل إلى عميل. أي حالة أخرى تُحفظ كما هي ولا تُحسب. استخدم cancelled أو refunded لإخراج طلب من المبيعات.

حقول المنتج

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

id وname مطلوبان. يُطابق المنتج بـid ثم بـsku. و"active": false يؤرشفه. لا يُحفظ السعر إلا مع عملة. والتحديث الأقدم مما حُفظ يُتجاهل.

الردود

يستطيع كل خادم مرسل إرسال 600 طلب في الدقيقة على الأكثر.

اختبر الربط

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

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

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