قسائم زد الجماعية: صمّم الحملة قبل توليد الأكواد

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

تتيح واجهة Generate Bulk Coupons الحالية في زد إنشاء عدة أكواد فريدة ضمن إعداد مشترك. ويمكن للطلب الموثق تحديد نوع الخصم وقيمته، وتاريخ البداية والنهاية، وحدود الاستخدام الكلية ولكل عميل، وحدود السلة، والمنتجات أو التصنيفات المشمولة، والشروط، وأعلام القنوات مثل مزيد وPOS وتطبيق الجوال. وتعرض واجهتا قائمة القسائم وتفاصيل القسيمة الحالة والاستخدام وبيانات المبيعات. تكفي هذه الأدوات لبناء مسار حملة مضبوط، لكن بشرط التعامل مع التوليد كتحول حالة، لا زر Fire-and-forget.

هذا مقال معرفي مبني على الوثائق الحالية وليس إعلانًا عن منتج جديد. تحققت من الصفحات الرسمية في 28 سبتمبر 2026. ويجب اختبار الحقول والصلاحيات داخل بيئة التاجر المصرح بها قبل إطلاق حملة فعلية.

ابدأ بمواصفات حملة غير قابلة للتغيير

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

تصبح المواصفات غير قابلة للتغيير بعد الاعتماد. إذا أراد فريق التسويق تعديل الخصم أو تمديد التاريخ، فأنشئ إصدارًا جديدًا وسجل السبب. يمنح ذلك المهندسين Object ثابتًا لمقارنته مع زد بعد التوليد، ويمنح المالية إجابة واضحة عن سؤال: ما الذي تمت الموافقة عليه؟

{
  "campaign_id": "sept-retention-v3",
  "discount_type": "fixed",
  "discount_value": 25,
  "minimum_cart": 150,
  "maximum_discount": 25,
  "uses_per_customer": 1,
  "channels": ["storefront"],
  "starts_at": "2026-09-28",
  "ends_at": "2026-10-05",
  "approval_id": "approval-1842"
}

هذا المثال عقد داخلي للتطبيق وليس Payload حرفية من زد. اربطه عمدًا بالحقول الموثقة مثل `discount_type` و`discount` و`total` و`max_total` و`uses_total` و`uses_customer` و`date_start` و`date_end` و`apply_to` و`apply_to_array` وأعلام القنوات المناسبة. ارفض أي مواصفات لا يكتمل ربطها.

عامل التوليد كأمر Idempotent

تعيد واجهة التوليد الجماعي الموثقة رسالة نجاح على مستوى الحملة، لكن مثال الاستجابة لا يسرد كل كود تم إنشاؤه. لذلك لا تمثل استجابة HTTP الناجحة مخزونًا محليًا كاملًا بعد، كما أن انتهاء مهلة الشبكة يترك نتيجة غامضة. قد تولد إعادة المحاولة العمياء دفعة أخرى.

خزّن أمر توليد قبل استدعاء API. امنحه Business Key فريدًا مثل `campaign_id + batch_number`، وسجل Hash للمواصفات المعتمدة، والكمية المطلوبة، وحالة محاولة الإرسال، ثم اسمح لـWorker واحدة فقط بإرساله. صنّف انقطاع الاتصال بعد الإرسال كـ`unknown` لا `failed`.

بعد استجابة مؤكدة أو غامضة، استخدم واجهة List Coupons لاكتشاف أكواد الحملة ومطابقتها. تدعم القائمة الموثقة Pagination وتعيد الكود والاسم ووقت الإنشاء وإعدادات الخصم وتواريخ الصلاحية وحدود الاستخدام والحالة وأعلام القنوات. طابق وفق نمط تسمية للحملة أو Prefix للكود يملكه نظامك، مع النافذة الزمنية وHash الإعداد المتوقع. لا تفترض أن كل قسيمة أُنشئت في الوقت نفسه تنتمي إلى هذه الحملة.

مسار الحالة الآمن هو:

approved -> dispatching -> generated -> reconciled -> distributable
                       \-> unknown -> reconcile -> generated or review

لا تجعل الأكواد قابلة للتوزيع حتى تؤكد المطابقة العدد والإعداد المتوقعين. إذا اختلفت استجابة المزود عن المجموعة المكتشفة، فأوقف الحملة واطلب مراجعة.

افصل مخزون الأكواد عن إسنادها للعملاء

الكود الفريد استحقاق شبيه بالسر. خزّن معرف القسيمة لدى المزود والكود وإصدار الحملة والحالة الحالية وحالة الإسناد في سجل منفصل. شفّر الأكواد وهي ساكنة عندما يستدعي الخطر التشغيلي ذلك، وقيّد التصدير الجماعي، وسجل كل عملية كشف، ولا تضع مجموعة الأكواد كاملة في Analytics Events أوSupport Logs أوClient-side Source.

أسند الكود إلى عميل داخل Transaction تقفل سجلًا واحدًا غير مسند. سجل القناة ومحاولة الرسالة، لكن لا تضع الكود في حالة Delivered قبل أن يؤكد مزود الإرسال ما يستطيع تأكيده. إذا فشلت الرسالة، فقرر هل يمكن إعادة إرسال الكود نفسه بأمان؛ ولا تخصص كودًا جديدًا مع كل محاولة اتصال. يمنع هذا الفصل عطلًا عابرًا في البريد أوSMS من استنزاف المخزون.

يمثل حقلا `uses_customer` و`uses_total` الموثقان ضوابط تنفيذ على مستوى القسيمة، لكنهما لا يستبدلان ضوابط الإسناد في نظام حملتك. حد الاستخدام مرة لكل عميل لا يمنع إرسال الكود غير المسند نفسه إلى أشخاص كثيرين بالخطأ، كما أن تفرد الكود لا يثبت وصوله إلى العميل المقصود.

عامل القنوات كقائمة سماح

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

يحتاج حقلا `apply_to` و`apply_to_array` أيضًا إلى Mapping صريحة. حل معرفات المنتجات والتصنيفات قبل الاعتماد، وخذ Snapshot منها، وتحقق من بقائها قبل التوليد. وإذا استخدمت الحملة شحنًا مجانيًا، فتذكر الوثائق أن `max_weight` يخص هذا النوع ولا يؤثر في قسائم الخصم العادي أو المبلغ الثابت. قبول API للحقل لا يعني أنه يغيّر كل نوع من القسائم.

تضيف إعدادات الخصم Progressive وحقل `conditions` قوة أكبر، لكنها تضيف حالات اختبار أكثر. فضّل عددًا صغيرًا من قوالب الحملات المسماة التي يغطيها Contract Testing. ولا تعرض كل حقول المزود الخام لكل مشغل.

تحقق بسلة حقيقية لا بحساب محلي

يمكن لتطبيقك عرض Preview للخصم المتوقع، لكن يجب أن تكون زد صاحبة قرار صلاحية الكود للسلة الحالية. تتحقق واجهة Check Coupon Validity من دون تطبيق، بينما تطبق واجهة Apply Coupon الكود وتعيد حساب إجماليات السلة والقواعد. استخدم التحقق لتقديم Feedback سريع، ثم عامل السلة بعد التطبيق كمصدر الحقيقة.

لا تعِد بناء محرك القواعد كاملًا في JavaScript. قد تتغير أهلية المنتجات والتواريخ والحدود والإجماليات بين Preview والتطبيق. يجب أن تتعامل الواجهة مع 422 من التحقق أو التطبيق كرفض تجاري، وتعرض رسالة مناسبة، وتحافظ على السلة. ولا تعيد الكود غير الصالح كما لو أن الخدمة تعاني عطلًا عابرًا.

قبل الإطلاق، نفذ مصفوفة اختبار في Staging أو سياق تاجر مضبوط: أقل وأعلى بقليل من حد السلة، منتجات مؤهلة وغير مؤهلة، أول استخدام وRepeated Use للعميل، حدود البداية والنهاية، كل قناة مفعلة، وحالة شحن مجاني تتجاوز `max_weight` عند استخدام هذه القاعدة. سجل إجماليات السلة المتوقعة، لا مجرد نجاح Endpoint.

طابق الاستخدام وأوقف الحملة بأمان

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

لم تتحقق هذه المراجعة من Webhook خاص بالقسائم يبلغ عن كل تغيير في الاستخدام أو الإعداد. تسرد صفحة Webhooks في زد الأحداث المدعومة وتنصح الشركاء بطلب الحدث عند غيابه؛ لذلك لا تخترع حدثًا للقسائم. قد تساعد Order Events في التحليلات عندما تتضمن Payload الموثقة بيانات القسيمة المطلوبة، لكن قراءات القسائم الدورية تظل مسار التحقق الموثوق الموصوف هنا.

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

تشمل مؤشرات المراقبة المفيدة أوامر التوليد في `unknown`، والعدد المتوقع مقابل المكتشف، والمخزون المسند وغير المسند، ومحاولات الإرسال لكل كود، وأسباب رفض التحقق، وعدد الاستخدام والمبيعات وتكلفة الخصم، وانحراف الإعداد، والوقت منذ آخر مطابقة. أنشئ Alerts على Invariants لا أخطاء HTTP فقط.

المبدأ الأساسي بسيط: ولّد من Snapshot معتمدة فقط، ووزع من مخزون مضبوط، ودع زد تتحقق من السلة الحية، وطابق ما أنشأته المنصة واستخدمته فعليًا. عندها يصبح التوليد الجماعي قدرة تشغيلية آمنة بدل أن يكون طريقة أسرع لمضاعفة خطأ في الحملة.

إعداد: Noor Yasser