getBonusHistory
احصل على سجل معاملات المكافآت للمستخدم الحالي. 🔐 تتطلب هذه الطريقة التفويض.
الوصف
يجلب معاملات مكافآت المستخدم المصادَق عليه، مع إمكانية التصفية حسب النوع ونطاق التاريخ والخصم والوحدة وعلامة المسؤول. يُعيد IBonusHistoryResponse، وهو حاوية { items, total } وليس مصفوفة.
تُعيد واجهة API على الأكثر أحدث 30 معاملة، الأحدث أولًا. total هو العدد الكامل للمعاملات المطابقة، لذا قد يكون أكبر من items.length. لا تقبل الطريقة offset أو limit بعد، لذا لا يمكن جلب المعاملات بعد أول 30؛ ضيّق النطاق باستخدام dateFrom/dateTo أو type بدلًا من ذلك.
قبل الإصدار 1.0.168 كانت الطريقة مُعرّفة على أنها تُعيد IBonusTransactionEntity[]، لكن نقطة النهاية كانت تُعيد دائمًا حاوية: الحساب الذي لا يملك معاملات يحصل على {"items":[],"total":0}. الكود المكتوب وفق النوع القديم كان يقرأ .length من كائن فيحصل على undefined. اقرأ المعاملات من result.items والعدد من result.total.
.getBonusHistory(
,
,
,
,
,
,
,
);
مخطط المعلمات
المخطط
type: IBonusTransactionType
نوع المعاملة للتصفية: ACCRUAL أو USAGE أو REDUCE أو REVERSAL_ACCRUAL أو REVERSAL_USAGE أو EXPIRATION.
dateFrom: string
بداية النطاق الزمني. تاريخ-وقت ISO كامل (2026-01-01T00:00:00.000Z)؛ التاريخ المجرد يُجيب بـ 400 dateFrom must be a ISOString.
dateTo: string
نهاية النطاق الزمني. تاريخ-وقت ISO كامل (2026-12-31T00:00:00.000Z)؛ التاريخ المجرد يُجيب بـ 400 dateTo must be a ISOString.
discountId: number
إرجاع معاملات معرّف الخصم هذا فقط.
moduleId: number
إرجاع المعاملات من هذه الوحدة فقط، على سبيل المثال 2 للنماذج أو 12 للطلبات.
isAdmin: boolean
عند true، تُرجَع فقط التعديلات اليدوية التي أجراها المسؤول.
offset: number
عدد المعاملات المراد تخطيها، 0 أو أكثر. الافتراضي: 0.
مثال: 0
limit: number
الحد الأقصى لعدد المعاملات المراد إرجاعها، 1 أو أكثر. الافتراضي: 30.
مثال: 30
أمثلة
مثال بسيط
const response = await Discounts.getBonusHistory();
مثال مع معلمات اختيارية
const response = await Discounts.getBonusHistory(
'ACCRUAL',
'2026-01-01T00:00:00.000Z',
'2026-12-31T23:59:59.000Z'
);
مثال على الاستجابة
{
"items": [],
"total": 0
}
مخطط الاستجابة
المخطط: IBonusHistoryResponse
items: IBonusTransactionEntity[]
حتى 30 من أحدث المعاملات المطابقة، الأحدث أولًا.
items.balanceId: number
معرّف رصيد المكافآت.
items.amount: string
مبلغ المعاملة. يُرجعه API كسلسلة نصية عشرية، مثل "100.00" (رغم أن swagger يعرّفه كرقم) — حلّله قبل إجراء العمليات الحسابية.
items.type: IBonusTransactionType
نوع المعاملة.
items.discountId: number
معرّف الخصم.
items.moduleId: number
معرّف الوحدة التي أنشأت المعاملة، على سبيل المثال 2 للنماذج أو 12 للطلبات.
items.entityIdentifier: string
معرّف الكيان المصدر في وحدته، مثل معرّف طلب أو علامة نموذج.
items.comment: string
تعليق.
items.isAdmin: boolean
ما إذا كان المسؤول قد أجرى المعاملة يدويًا.
items.remainingAmount: string | null
المبلغ المتبقي (للاستخدام/انتهاء الصلاحية بنظام FIFO). سلسلة نصية عشرية مثل "100.00" في الإضافات، وnull في الخصومات.
items.triggerType: 'EVENT' | 'SCHEDULED'
ما أطلق المعاملة: "EVENT" أو "SCHEDULED".
items.expiresAt: string
وقت انتهاء صلاحية المكافأة المستحقة؛ null إذا لم تنتهِ صلاحيتها.
items.createdAt: string
تاريخ الإنشاء.
total: number
عدد المعاملات التي تتطابق مع الفلتر إجمالاً.