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

مقدمة

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

يتيح لك موديل 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. Customer adds items to cart
   ↓
2. Proceeds to checkout
   ↓
3. Enters shipping/billing info
   ↓
4. Selects payment method
   ↓
5. Order created (status: pending)
   ↓
6. Payment processed (status: processing)
   ↓
7. Order confirmed (status: confirmed)
   ↓
8. Items prepared (status: processing)
   ↓
9. Order shipped (status: shipped)
   ↓
10. Order delivered (status: completed)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

مسؤوليتك:

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

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

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

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

مهم:

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

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

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

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

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

الأمان​

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

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

دائمًا:

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

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

الطريقةالوصف
createOrder()إنشاء طلب جديد
getAllOrdersByMarker()الحصول على جميع الطلبات (مقسمة)
getOrdersStorageByMarker()الحصول على كائن تخزين طلب واحد بواسطة العلامة.
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"
  }
);

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