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

المقدمة

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

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

🎯 ماذا تفعل هذه الوحدة؟​

تتيح لك وحدة Orders إنشاء وإدارة وتتبع طلبات العملاء — من الخروج إلى الدفع إلى التنفيذ. تقوم ببناء واجهة المستخدم لعربة التسوق؛ تقوم هذه الوحدة بتحويل العربة إلى طلب، ومعاينة الإجماليات (الخصومات، القسائم، المكافآت)، وتتبع الحالة، ومعالجة طلبات الاسترداد.

تعيش الطلبات داخل تخزين الطلبات (حاويات تقوم بتكوينها في لوحة الإدارة) ويتم الإشارة إليها بواسطة علامة التخزين. يتم تفويض الدفع إلى البوابة المكونة لحساب الدفع المختار — انظر وحدة المدفوعات.

🚀 البدء السريع​

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


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

قم بإنشاء طلب في تخزين وقراءة النتيجة (يتطلب مصادقة):

// Create an order in the "order_storage_1" storage.
const order = await Orders.createOrder("order_storage_1", {
  formIdentifier: "orderForm",
  paymentAccountIdentifier: "cash",
  formData: [],
  products: [{ productId: 2957, quantity: 2 }],
});

console.log(order.id, order.totalSum, order.statusIdentifier);
// 179 "300.00" "inProgress"

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

ما هو الطلب؟​

الطلب هو معاملة شراء من قبل العميل. يحمل كل كائن طلب:

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

هيكل الطلب​

{
  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' },
  paymentUrl: null,
  products: [
    {
      id: 2957,
      title: 'Cosmo',
      sku: null,
      previewImage: null,
      price: 150,
      quantity: 2,
      isGift: false,
    },
  ],
  isCompleted: true,
}

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

تخزين الطلبات هو حاوية تجمع الطلبات ذات الصلة (على سبيل المثال، الطلبات من نموذج أو قناة مبيعات معينة). الطلبات الفردية هي المعاملات الفعلية داخل التخزين. يمكنك الإشارة إلى التخزين بواسطة علامته وطلب داخله بواسطة العلامة + id.

حالات الطلبات​

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

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

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

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

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

ماذا تفعل الوحدة وماذا لا تفعل​

  • ✅ إنشاء طلبات من بيانات العربة، معاينة الإجماليات، تحديث الحالة، إدارة طلبات الاسترداد
  • ✅ تفويض الدفع إلى البوابة عبر جلسة الدفع / paymentUrl
  • ❌ لا توفر واجهة مستخدم عربة التسوق — أنت تبني ذلك
  • ❌ لا تخزن بيانات البطاقة الخام — يتم التعامل مع الدفع بواسطة البوابة

الاستردادات​

تعيش معالجة الاسترداد في وحدة الطلبات: اطلب استردادًا باستخدام createRefundRequest()، وقم بإدراج طلبات استرداد الطلب باستخدام getRefunds()، وألغِ واحدة باستخدام cancelRefundRequest().

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

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

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

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

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

signedPrice — النوع string

يتم الحصول على السعر الموقّع للمنتج مع بيانات المنتج عندما يتم تعيين signPrice.

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

لا تقوم بإنشاء signedPrice بنفسك — إنه يصل داخل بيانات المنتج، ولكن فقط عندما تطلب المنتجات مع تعيين signPrice إلى علامة تخزين الطلب الخاصة بك:

كل منتج تم إرجاعه يحتوي بعد ذلك على سلسلة signedPrice. اقرأ المزيد في قسم إصلاح السعر (signPrice) من وحدة المنتجات.

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

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


const { items } = await Products.getProducts([], "en_US", {
  signPrice: "my-order"
});

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

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

إذا قمت بإغفال signedPrice، يتم إنشاء الطلب بسعر المنتج الحالي في وقت الخروج.

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

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

مرر مصفوفة من كائنات المنتجات في حقل products من جسم الطلب. يحتاج كل عنصر إلى productId و quantity (ويمكن اختيارياً signedPrice). يتم حساب المجموع الكلي تلقائيًا.

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

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

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

اقرأ حقل statusIdentifier للحالة الحالية، واسترجع الحالات المتاحة للتخزين باستخدام getAllStatusesByStorageMarker(). يمكنك أيضًا استخدام وحدة الأحداث للتفاعل مع التغييرات.

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

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

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

قم بتحديث حالة الطلب باستخدام updateOrderByMarkerAndId(). بالنسبة للاستردادات، استخدم طرق استرداد الطلبات: createRefundRequest() لطلب واحد، getRefunds() لإدراج طلبات الطلب، و cancelRefundRequest() لإلغاء واحدة.

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

  • المعاينة قبل الإنشاء — اتصل بـ previewOrder() لعرض الخصومات، القسائم، والمكافآت في ملخص الخروج.
  • استخدم signedPrice عندما تتغذى المنتجات إلى الخروج حتى لا يتغير السعر بين التصفح والطلب.
  • قم بالمصادقة أولاً — تتطلب طرق إنشاء/قراءة/تحديث الطلبات مستخدمًا مصرحًا (انظر AuthProvider).
  • قم بتقسيم قوائم الطلبات ( offset + limit ) — لا تقم بتحميل كل الطلبات دفعة واحدة.
  • قم بالإشارة إلى التخزينات والنماذج بواسطة العلامة، وليس بواسطة الاسم المعروض — العلامات مستقرة.

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