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

Orders

إنشاء طلبات العملاء وتتبعها عبر دورة حياة الشراء والدفع والتنفيذ بالكامل.

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

تحوّل وحدة Orders السلة إلى طلب، وتعاين المجاميع (الخصومات، والقسائم، والمكافآت)، وتتتبّع حالة الطلب، وتعالج طلبات الاسترداد. أما واجهة السلة فبناؤها متروك لك.

تُحفظ الطلبات في مخازن الطلبات: حاويات تُهيّئها في لوحة الإدارة وتشير إليها بالعلامة. يتم الدفع عبر البوابة المُهيّأة لحساب الدفع المختار؛ انظر وحدة المدفوعات.

بدء سريع​

قم بتهيئة الوحدة من defineOneEntry:


const {  } = defineOneEntry(
  , {
    
  }
);

أنشئ طلبًا في مخزن واقرأ النتيجة (يستخدم هذا المثال مستخدمًا مسجّل الدخول):

// Create an order in the "my_order" storage.
const order = await Orders.createOrder("my_order", {
  formIdentifier: "orderForm",
  paymentAccountIdentifier: "cash",
  formData: [],
  products: [{ productId: 2957, quantity: 2 }],
});
if ('statusCode' in order) throw new Error(order.message);

console.log(order.id, order.totalSum, order.statusIdentifier);
// 179 285 "inProgress-payment"

كائن الطلب​

تُعيد طرق القراءة (getOrderByMarkerAndId() وgetOrderById() وgetAllOrdersByMarker()) الطلبات بهذا الشكل (IOrderByMarkerEntity). أما createOrder() وupdateOrderByMarkerAndId() فتُعيدان IBaseOrdersEntity أقصر.

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

الحقول التي ستستخدمها أكثر من غيرها:

  • id: معرّف الطلب
  • storageId: مخزن الطلبات الذي ينتمي إليه الطلب
  • formIdentifier / formData: نموذج الطلب والبيانات التي أرسلها العميل
  • products: بنود الطلب (id، title، quantity، price، …)
  • totalSum / currency: إجمالي الطلب والعملة
  • paymentAccountIdentifier: حساب الدفع المختار
  • paymentUrl: رابط الدفع في البوابة، أو null
  • statusIdentifier / isCompleted: الحالة الحالية
  • createdDate: الطابع الزمني

المخازن والحالات​

يجمّع مخزن الطلبات الطلبات المرتبطة ببعضها، مثل الطلبات الواردة من نموذج معين أو قناة مبيعات معينة. تشير إلى المخزن بعلامته، وإلى الطلب داخله بالعلامة وid. العلامات ثابتة، لذا أشِر إلى المخازن والنماذج بالعلامة بدلًا من اسم العرض.

يحدد كل مخزن مجموعة حالاته الخاصة، والحالة الحالية للطلب موجودة في statusIdentifier. احصل على الحالات المتاحة في مخزن باستخدام getAllStatusesByStorageMarker()، وغيّر حالة الطلب باستخدام updateOrderByMarkerAndId(). للاستجابة لتغيّرات الحالة، استخدم وحدة الأحداث.

إنشاء طلب​

تقدّم أنت بيانات النموذج وبنود الطلب؛ ويحسب OneEntry الإجمالي. لإنشاء طلب، مرّر:

  1. formIdentifier: نموذج الطلب
  2. formData: الحقول التي أرسلها العميل
  3. products: مصفوفة من بنود الطلب، لكل منها productId وquantity وsignedPrice اختياري
  4. paymentAccountIdentifier: طريقة دفع العميل

استدعِ previewOrder() أولًا لعرض الخصومات والقسائم والمكافآت في ملخص الدفع. تتطلب طرق القراءة والتحديث مستخدمًا مصادَقًا عليه (راجع AuthProvider). تعمل createOrder() أيضًا للضيوف إذا كانت لمجموعة مستخدمي الضيوف الصلاحية. قسّم قوائم الطلبات إلى صفحات باستخدام offset وlimit بدلًا من تحميل كل الطلبات دفعة واحدة.

لا تخزّن الوحدة بيانات البطاقات الخام: تتولى بوابة الدفع معالجة الدفع، عبر جلسة الدفع أو paymentUrl.

يمكنك تغيير الطلب بعد إنشائه باستخدام updateOrderByMarkerAndId(): حالته أو بيانات نموذجه أو منتجاته. كن حذرًا عند تغيير البنود أو المجاميع بعد بدء عملية الدفع.

الإلغاء والاسترداد​

لإلغاء طلب، حدّث حالته باستخدام updateOrderByMarkerAndId(). تُعالج عمليات الاسترداد في هذه الوحدة: اطلب استردادًا باستخدام createRefundRequest()، واعرض طلبات الاسترداد لطلب ما باستخدام getRefunds()، وألغِ أحدها باستخدام cancelRefundRequest().

الطرق​

الطريقةالوصف
createOrder()إنشاء طلب جديد
getAllOrdersByMarker() 🔐الحصول على جميع الطلبات في مخزن (مع التقسيم إلى صفحات)
getOrdersStorageByMarker() 🔐الحصول على مخزن طلبات بواسطة العلامة
getAllOrdersStorage() 🔐الحصول على جميع مخازن الطلبات
getOrderByMarkerAndId() 🔐الحصول على أحد طلبات المستخدم بواسطة علامة المخزن والمعرّف
getOrderById() 🔐الحصول على أحد طلبات المستخدم بواسطة المعرّف، دون علامة المخزن
updateOrderByMarkerAndId() 🔐تحديث أحد طلبات المستخدم بواسطة علامة المخزن والمعرّف
previewOrder()معاينة إجماليات الطلب والخصومات والقسائم قبل إنشاء الطلب
getAllStatusesByStorageMarker() 🔐الحصول على جميع حالات الطلبات في مخزن
getRefunds() 🔐الحصول على جميع طلبات الاسترداد لطلب
createRefundRequest() 🔐إنشاء طلب استرداد لطلب
cancelRefundRequest() 🔐إلغاء طلب استرداد لطلب
getOrdersByVectorSearch() 🔐بحث دلالي (متجهي) في طلبات المستخدم المصادَق عليه

🔐 = يتطلب تفويضًا

سعر المنتج الثابت (signedPrice)​

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

من أين تحصل عليه​

لا تُنشئ signedPrice بنفسك. فهو يأتي ضمن بيانات المنتج، ولكن فقط إذا طلبت المنتجات مع تعيين المعلمة signPrice إلى علامة مخزن الطلبات الخاص بك:

  • وحدة المنتجات: مرّر signPrice في userQuery (getProducts، getProductsByPageUrl، …).
  • وحدة الكتل: مرّر signPrice كوسيط لطرق التوصيات (getCartSimilar، getRecentlyViewed، …).

يحتوي كل منتج مُعاد عندها على سلسلة signedPrice. راجع تثبيت السعر (signPrice) للتفاصيل.

كيفية استخدامه​

مرّر الرمز مرة أخرى في كل منتج ضمن جسم createOrder()، فيحتفظ الطلب بالسعر الثابت:


const products = await Products.([], "en_US", {
  signPrice: "my_order"
});
if ('statusCode' in products) throw new Error(products.message);
const { items } = products;

const  = {
  formIdentifier: "orderForm",
  paymentAccountIdentifier: "cash",
  formData: [],
  products: [
    {
      productId: items[0].id,
      quantity: 2,
      signedPrice: items[0].
    }
  ]
};

const order = await Orders.createOrder("my_order", body);

بدون signedPrice، يُنشأ الطلب بالسعر الحالي للمنتج وقت الدفع.

ذات صلة​