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

قراءة بطاقة من الكتالوج

GET/v1/wallets/{walletId}/catalog/cards/{cardId}

يقرأ GET /v1/wallets/{walletId}/catalog/cards/{cardId} بطاقة CatalogueCard واحدة بسعر هذه المحفظة وشعارها وفئتها. يتطلب catalogue:read؛ وردّه غير موقَّع.

الصلاحيةcatalogue:read

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

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

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

حزمة SDK لـ ‎.NETclient.Catalogue.GetCardAsync(walletId, cardId)

المعاملات

الاسم	الموضع	النوع	ملاحظات
`walletId`إلزامي	`path`	UUID	معرّف UUID بأحرف صغيرة مع الشرطات.
`cardId`إلزامي	`path`	UUID	معرّف UUID بأحرف صغيرة مع الشرطات.

الاستدعاء

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

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

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

الردود

الحالة	المعنى	المحتوى
200	نجاح.	CatalogueCard
400	مرفوض: الاستدعاء الموقّع غير سليم البنية.	مشكلة
401	مرفوض: لم تتم المصادقة.	مشكلة
403	مرفوض: غير مسموح.	مشكلة
404	مرفوض: غير موجود، أو ليس لك.	مشكلة
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
الخدمة غير متاحة	`dependency_unavailable`	503
انتهت مهلة الاستدعاء	`request_timeout`	504
خطأ داخلي	`internal_error`	500

الأنواع

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`

LocalizedText

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

Money

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