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

المقدمة

🎯 ماذا يفعل هذا الموديل؟​

يتيح لك موديل Orders إنشاء وإدارة وتتبع طلبات العملاء - من إنهاء عملية الدفع في عربة التسوق إلى معالجة الدفع وتلبية الطلبات - مع التعامل مع دورة حياة الطلبات الكاملة في التجارة الإلكترونية.

فكر في الأمر كنظام إدارة الطلبات الخاص بك - يضيف العملاء العناصر إلى العربة، ويقومون بتقديم الطلبات، وإجراء المدفوعات، وأنت تتبع كل شيء من إنشاء الطلب إلى التسليم، كل ذلك ضمن OneEntry.

📖 شرح بسيط​

تحتاج كل تطبيق تجارة إلكترونية إلى إدارة الطلبات:

  • 🛒 عربة التسوق - يقوم المستخدمون بإضافة المنتجات، ثم الانتقال إلى إنهاء الطلب
  • 📋 إنشاء الطلب - تحويل العربة إلى طلب مع تفاصيل العميل
  • 💳 معالجة الدفع - قبول المدفوعات (بطاقة ائتمان، باي بال، إلخ)
  • 📦 تتبع الطلب - تتبع الحالة (معلق، قيد المعالجة، تم الشحن، تم التسليم)
  • 📊 إدارة الطلبات - عرض جميع الطلبات، تصفية حسب الحالة، البحث
  • 🧾 تفاصيل الطلب - عرض العناصر، الإجماليات، معلومات العميل

المشكلات:

  • 🔒 لا يوجد تكامل للدفع - تتبع المدفوعات يدويًا
  • 📊 تتبع ضعيف - من الصعب العثور على الطلبات، تصفية حسب الحالة
  • 🔄 لا توجد أتمتة - تحديثات الحالة يدويًا، لا توجد إشعارات
  • 💸 لا حسابات للضرائب/الشحن - حساب يدوي

حل الطلبات:

الفوائد:

  • 🔒 مدفوعات متكاملة - Stripe، PayPal، بوابات أخرى
  • 📊 تتبع متقدم - تصفية، بحث، تصدير الطلبات
  • 🔄 عمليات تلقائية - تحديثات الحالة، إشعارات
  • 💸 حسابات تلقائية - ضرائب، شحن، خصومات

✨ المفاهيم الأساسية​

ما هو الطلب؟​

الطلب هو معاملة شراء من العميل تحتوي على:

  • عناصر الطلب - المنتجات/الخدمات التي يتم شراؤها (الكمية، السعر)
  • معلومات العميل - الاسم، البريد الإلكتروني، الهاتف
  • عنوان الشحن - موقع التسليم
  • عنوان الفواتير - معلومات فواتير الدفع
  • تفاصيل الدفع - طريقة الدفع، معرف المعاملة
  • إجماليات الطلب - المجموع الفرعي، الضريبة، الشحن، الإجمالي
  • حالة الطلب - الحالة الحالية (معلق، قيد المعالجة، مكتمل)
  • الطوابع الزمنية - تواريخ الإنشاء، التحديث، الاكتمال

هيكل الطلب​

كل طلب له هذا الهيكل:

{
  id: 179,
  storageId: 1,
  createdDate: '2025-07-03T00:43:02.908Z',
  statusIdentifier: 'inProgress',
  formIdentifier: 'orderForm',
  formData: [
    {
      marker: 'order_name',
      type: 'string',
      value: 'Ivan'
    }
  ],
  attributeSetIdentifier: 'order_form',
  totalSum: '300.00',
  currency: 'USD',
  paymentAccountIdentifier: 'cash',
  paymentAccountLocalizeInfos: { title: 'Cash' },
  products: [
    {
      id: 2957,
      title: 'Cosmo',
      sku: null,
      previewImage: null,
      price: 150,
      quantity: 2,
    },
  ],
  isCompleted: true,
}

دورة حياة الطلب​

1. يضيف العميل العناصر إلى العربة
   ↓
2. ينتقل إلى إنهاء الطلب
   ↓
3. يدخل معلومات الشحن/الفواتير
   ↓
4. يختار طريقة الدفع
   ↓
5. يتم إنشاء الطلب (الحالة: معلق)
   ↓
6. تتم معالجة الدفع (الحالة: قيد المعالجة)
   ↓
7. يتم تأكيد الطلب (الحالة: مؤكد)
   ↓
8. يتم إعداد العناصر (الحالة: قيد المعالجة)
   ↓
9. يتم شحن الطلب (الحالة: تم الشحن)
   ↓
10. يتم تسليم الطلب (الحالة: مكتمل)

أمثلة على حالات الطلب​

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

العمليات الشائعة للطلب​

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

لماذا تستخدم موديل الطلبات؟​

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

📋 ما تحتاج إلى معرفته​

يتم إنشاء الطلبات من بيانات العربة​

تحتاج إلى تقديم:

  1. معلومات العميل - الاسم، البريد الإلكتروني، الهاتف
  2. عناصر الطلب - المنتجات، الكميات، الأسعار
  3. عنوان الشحن - موقع التسليم
  4. طريقة الدفع - كيف سيدفع العميل

إدارة حالة الطلب​

تتبع تقدم الطلب من خلال الحالات:

تدفقات الحالة الشائعة:

  • المنتجات الرقمية: معلق → قيد المعالجة → مكتمل
  • المنتجات المادية: معلق → قيد المعالجة → تم الشحن → تم التسليم → مكتمل
  • ملغى: أي حالة → ملغى
  • مسترد: مكتمل → مسترد

معالجة الدفع​

تتكامل الطلبات مع بوابات الدفع

💡 ملاحظات مهمة​

يتم إنشاء الطلبات في OneEntry​

يتعامل موديل الطلبات مع دورة حياة الطلب الكاملة:

  • ✅ إنشاء الطلبات من بيانات العربة
  • ✅ معالجة المدفوعات
  • ✅ تحديث حالة الطلب
  • ✅ تتبع الشحن
  • ❌ لا يتعامل مع واجهة عربة التسوق (أنت تبني ذلك)

مسؤوليتك:

  • بناء واجهة عربة التسوق
  • جمع معلومات العميل
  • عرض تأكيد الطلب

معالجة الدفع​

تتكامل الطلبات مع بوابات الدفع:

  • Stripe (موصى به)
  • PayPal
  • بوابات مخصصة

مهم:

  • لا تخزن تفاصيل بطاقة الائتمان مباشرة
  • استخدم التوكن (Stripe.js، PayPal SDK)
  • يتعامل OneEntry مع معالجة الدفع بشكل آمن

إدارة المخزون​

تقوم الطلبات تلقائيًا:

  • ✅ خصم المخزون عند إنشاء الطلب
  • ✅ استعادة المخزون عند الإلغاء
  • ✅ تتبع مستويات المخزون

أفضل ممارسة: تحقق من المخزون قبل إنشاء الطلب

الأمان​

تحتوي الطلبات على بيانات حساسة:

  • معلومات شخصية للعميل
  • تفاصيل الدفع
  • عناوين الشحن

دائمًا:

  • استخدم HTTPS لصفحات إنهاء الطلب
  • تحقق من البيانات قبل إنشاء الطلبات
  • نفذ المصادقة المناسبة
  • اتبع متطلبات PCI DSS للمدفوعات

📊 جدول مرجعي سريع​

الطريقةالوصف
createOrder()إنشاء طلب جديد
getAllOrdersByMarker()الحصول على جميع الطلبات (مقيدة)
getOrderByMarker()الحصول على كائن طلب تخزين واحد بواسطة العلامة.
getAllOrdersStorage()الحصول على جميع كائنات تخزين الطلبات.
getOrderByMarkerAndId()الحصول على طلب واحد بواسطة العلامة والمعرف من كائن تخزين الطلب الذي أنشأه المستخدم.
updateOrderByMarkerAndId()تحديث طلب واحد بواسطة العلامة والمعرف من كائن تخزين الطلب الذي أنشأه المستخدم.

❓ الأسئلة الشائعة (FAQ)​

كيف يمكنني إنشاء طلب مع عدة منتجات؟​

مرر مصفوفة من كائنات المنتجات في بيانات الطلب. يجب أن يتضمن كل منتج id، quantity، و price. يتم حساب المجموع الكلي تلقائيًا بناءً على كميات وأسعار المنتجات.

هل يمكنني تحديث الطلب بعد إنشائه؟​

نعم، استخدم updateOrderByMarkerAndId() لتعديل تفاصيل الطلب مثل الحالة، عنوان الشحن، أو بيانات الطلب. ومع ذلك، بمجرد معالجة الدفع، كن حذرًا عند تعديل عناصر الطلب أو الإجماليات.

كيف يمكنني تتبع تغييرات حالة الطلب؟​

استخدم حقل statusIdentifier لتتبع الحالة الحالية للطلب. يمكنك أيضًا إعداد webhooks أو استخدام موديل الأحداث لتلقي إشعارات عند تغيير حالة الطلب.

ما الفرق بين تخزين الطلبات والطلبات الفردية؟​

تخزين الطلبات هو حاوية تجمع الطلبات ذات الصلة (مثل الطلبات من نموذج أو قناة مبيعات معينة). الطلبات الفردية هي المعاملات الفعلية للشراء ضمن ذلك التخزين. استخدم العلامات لتحديد وتنظيم تخزين الطلبات المختلفة.

كيف يمكنني التعامل مع إلغاء الطلبات والاستردادات؟​

قم بتحديث حالة الطلب إلى "ملغى" باستخدام updateOrderByMarkerAndId(). للاستردادات، استخدم موديل المدفوعات لمعالجة معاملة الاسترداد، ثم قم بتحديث حالة الطلب إلى "مسترد".

هل يمكنني استرداد تاريخ طلبات العميل؟​

نعم، استخدم getAllOrdersByMarker() مع الفلاتر المناسبة لجلب جميع الطلبات لعميل معين. يمكنك تصفية حسب معرف المستخدم، نطاق التاريخ، أو معايير أخرى.

🎓 أفضل الممارسات​

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

مزيد من المعلومات حول واجهة المستخدم للموديل https://doc.oneentry.cloud/docs/category/orders

تعريف موديل الطلبات​


const { Orders } = defineOneEntry(
  "your-project-url", {
    "token": "your-app-token"
  }
);

🔗 الوثائق ذات الصلة​