مرجع API · الكتالوج

قائمة البطاقات المعروضة للبيع

GET/v1/wallets/{walletId}/catalog/subcategories/{subcategoryId}/cards

البطاقات المعروضة لهذه المحفظة في فئة فرعية، بالسعر الذي تدفعه هذه المحفظة. قد تُرفض البطاقة المعروضة عند البيع رغم ذلك. مقسّمة إلى صفحات بمؤشر.

الصلاحيةcatalogue:read

المصادقةقراءة موقَّعة

ردّ أنيسغير موقَّع

حدود الموظفين التي يُحتسب ضمنهاكل الاستدعاءات

حزمة SDK لـ ‎.NETanis.Catalogue.ListCardsAsync(walletId, subcategoryId)

أرسل unitPrice الخاص بالبطاقة في expectedUnitPrice لطلب الشراء. أما الأسعار الأخرى فللعرض فقط.
تحقّق من minimumQuantity وmaximumQuantity قبل الطلب: فالكمية quantity خارجهما تُرفض بالرمز quantity_unavailable.

المعاملات

الاسم	الموضع	النوع	ملاحظات
`walletId`إلزامي	`path`	UUID	معرّف UUID بأحرف صغيرة مع الشرطات.
`subcategoryId`إلزامي	`path`	UUID	معرّف UUID بأحرف صغيرة مع الشرطات.
`cursor`اختياري	`query`	string	قيمة `nextCursor` من الصفحة السابقة، تُعاد كما استُلمت بالضبط. اتركها للصفحة الأولى.

الاستدعاء

موقَّعة بمفتاحك. بلا محتوى وبلا رقم استخدام لمرة واحدة (nonce).

الترويسات: Signature-Input، Signature، X-Anis-Date، Accept-Language (اختياري). تضبطها حزم SDK كلها نيابةً عنك.

المحتوى: لا يوجد.

الردود

الحالة	المعنى	المحتوى
200	نجاح.	CatalogueCollection
400	مرفوض: الاستدعاء الموقّع غير سليم البنية.	مشكلة
401	مرفوض: لم تتم المصادقة.	مشكلة
403	مرفوض: غير مسموح.	مشكلة
404	مرفوض: غير موجود، أو ليس لك.	مشكلة
422	مرفوض: الاستدعاء يخالف قاعدة.	مشكلة
429	مرفوض: بلغتَ حدًا.	مشكلة
503	لا قرار: خدمة مطلوبة غير متاحة.	مشكلة

ردود هذا الاستدعاء غير موقَّعة — لا ترويسة Signature ولا Signature-Input، سواء في النجاح أو الرفض. لا شيء تتحقق منه؛ فحماية TLS تكفيها. وتبقى Content-Digest و X-Request-Id موجودتين.

حالات الرفض

رفض هذا الاستدعاء مشكلةٌ بلا توقيع. ابنِ منطقك على رمزها code؛ وكلٌّ منها يرتبط بصفحة تشرح معناه وما عليك فعله.

الخطأ	الرمز	الحالة
بيانات اعتماد غير صالحة	`invalid_credentials`	401
استدعاء موقّع غير سليم البنية	`malformed_signed_request`	400
صلاحية غير كافية	`insufficient_scope`	403
عنوان المصدر غير مسموح	`source_ip_not_allowed`	403
تجاوزت حدّ الاستدعاءات	`rate_limited`	429
الحساب غير مخوَّل	`binding_not_authorized`	403
الحساب غير فعّال	`account_inactive`	403
المحفظة غير ممنوحة	`wallet_not_granted`	404
غير موجود	`resource_not_found`	404
فشل التحقق	`validation_failed`	422
الخدمة غير متاحة	`dependency_unavailable`	503
انتهت مهلة الاستدعاء	`request_timeout`	504
خطأ داخلي	`internal_error`	500

الأنواع

CatalogueCollection

الحقل	النوع	ملاحظات
`items`موجود دائمًا	list of CatalogueObject	الفئات أو الفئات الفرعية أو البطاقات في هذه الصفحة — كل مسار قائمة يُرجع نوعًا واحدًا.
`nextCursor`	string	مرّره في `cursor` للحصول على الصفحة التالية. غير موجود في الصفحة الأخيرة.

CatalogueObject

واحد من: CatalogueCategory, CatalogueSubcategory, CatalogueCard — كل مسار يُرجع نوعًا واحدًا منها بالضبط.

CatalogueCategory

الحقل	النوع	ملاحظات
`id`موجود دائمًا	UUID	معرّف الفئة.
`name`	LocalizedText	اسم الفئة، بالعربية والإنجليزية.
`description`	LocalizedText	وصف، بالعربية والإنجليزية.
`logo`	string	عنوان صورة شعار الفئة.
`type`	string	هل الفئة محلية أم دولية. القيم: `local`, `international`
`inStock`موجود دائمًا	boolean	هل يمكن شراء أي شيء فيها الآن.
`displayOrder`موجود دائمًا	integer	ترتيب عرض الفئات — الأصغر أولًا.

LocalizedText

الحقل	النوع	ملاحظات
`ar`	string	النص العربي؛ يُحذف حين يكون فارغًا.
`en`	string	النص الإنجليزي؛ يُحذف حين يكون فارغًا.

CatalogueSubcategory

الحقل	النوع	ملاحظات
`id`موجود دائمًا	UUID	معرّف الفئة الفرعية.
`categoryId`موجود دائمًا	UUID	الفئة التي تتبع لها.
`categoryType`	string	هل الفئة التي تتبع لها محلية أم دولية. لا يظهر إن لم تحدده أنيس. القيم: `local`, `international`
`name`	LocalizedText	اسم الفئة الفرعية، بالعربية والإنجليزية.
`description`	LocalizedText	وصف، بالعربية والإنجليزية.
`disclaimer`	any	ملاحظة أنيس الحالية لمشتري بطاقات هذه الفئة الفرعية، بالعربية والإنجليزية. اعرضها على عميلك النهائي قبل أن يشتري. غير موجودة حين لا توجد ملاحظة.
`logo`	string	عنوان صورة شعار الفئة الفرعية.
`isBestSelling`موجود دائمًا	boolean	علّمتها أنيس بأنها من الأكثر مبيعًا.
`displayOrder`موجود دائمًا	integer	ترتيب عرض الفئات الفرعية — الأصغر أولًا.
`available`موجود دائمًا	boolean	هل يمكن الشراء منها الآن.

CatalogueCard

الحقل	النوع	ملاحظات
`id`موجود دائمًا	UUID	معرّف البطاقة — وهو `cardId` الذي يحمله طلب الشراء.
`subcategoryId`موجود دائمًا	UUID	الفئة الفرعية التي تتبع لها.
`name`	LocalizedText	اسم البطاقة، بالعربية والإنجليزية.
`faceValue`	string	القيمة المطبوعة على البطاقة، إن وُجدت.
`unitPrice`	Money	السعر الذي تدفعه هذه المحفظة. أرسله دون تغيير في `expectedUnitPrice` لطلب الشراء. البطاقة التي لا تملكه لا يمكن بيعها لهذه المحفظة.
`businessPrice`	Money	للعرض فقط. طلب الشراء بهذا السعر قد يُرفض بـ `price_changed`.
`personalPrice`	Money	سعر التجزئة، ويُعرض فقط ما دام أعلى من سعر الأعمال. للعرض فقط.
`hasSpecialOffer`موجود دائمًا	boolean	هل يوجد عرض خاص.
`specialOfferPrice`	Money	سعر العرض، ويُعرض فقط مع العرض الخاص. للعرض فقط.
`available`موجود دائمًا	boolean	هل يمكن شراء البطاقة الآن.
`minimumQuantity`موجود دائمًا	integer	دائمًا 1: الحد الأدنى لطلب الشراء على المنصة.
`maximumQuantity`موجود دائمًا	integer	حدّ طلب الشراء على المنصة: 100. ويُفحص المخزون والإتاحة بصورة مستقلة.
`logo`	string	عنوان URL مطلق لشعار الفئة الفرعية؛ يُحذف حين يكون فارغًا.
`category`	object	الفئة، بمعرّفها واسمها المحلي.
`category.id`	UUID	معرّف الفئة.
`category.name`	LocalizedText	اسم الفئة بالعربية والإنجليزية.
`category.type`	string	هل الفئة محلية أم دولية. لا يظهر إن لم تحدده أنيس. القيم: `local`, `international`

Money

الحقل	النوع	ملاحظات
`amount`موجود دائمًا	string	نص عشري، وليس عدد JSON. قد يكون رصيد المحفظة سالبًا عند استخدام الدين المسموح. تتبع الأسعار والإجماليات قواعد المبلغ لكل مسار.
`currency`موجود دائمًا	string	رمز عملة من ثلاثة أحرف كبيرة، مثل `LYD`. اقرأ عملة المحفظة من `balance.currency`.
`asOf`	string (date-time)	وقت قراءة هذا السعر أو الرصيد.