مرجع API · البطاقات المملوكة

قائمة البطاقات المملوكة

GET/v1/wallets/{walletId}/owned-cards

GET /v1/wallets/{walletId}/owned-cards — البطاقات التي اشترتها محفظة، ورموزها مخفية: يظهر السعر المدفوع وتاريخ الانتهاء ورقم الفاتورة. مقسّمة إلى صفحات بمؤشر.

الصلاحيةcards:read

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

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

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

حزمة SDK لـ ‎.NETanis.OwnedCards.ListAsync(walletId)

المعاملات

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

الاستدعاء

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

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

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

الردود

الحالة	المعنى	المحتوى
200	نجاح.	MaskedCardCollection
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
فشل التحقق	`validation_failed`	422
الخدمة غير متاحة	`dependency_unavailable`	503
انتهت مهلة الاستدعاء	`request_timeout`	504
خطأ داخلي	`internal_error`	500

الأنواع

MaskedCardCollection

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

MaskedCard

الحقل	النوع	ملاحظات
`soldCardId`موجود دائمًا	UUID	معرّف البطاقة المبيعة — وهو ما يأخذه كشف بطاقة واحدة.
`operationId`	UUID	معرّف عملية طلب الشراء الذي اشتراها.
`invoiceId`	any	الفاتورة التي عليها — وهو ما يأخذه كشف فاتورة كاملة.
`invoiceNumber`	integer	الرقم المطبوع على الفاتورة. اذكره حين تكتب إلى الدعم؛ أما المعرّف الذي يُكشف به فهو `invoiceId`.
`card`	CardSummary	بطاقة الكتالوج التي بيعت منها.
`serialNumberMasked`	string	الرقم التسلسلي مخفيًا جزئيًا. الرموز الكاملة لا تأتي إلا من الكشف.
`credentialAvailable`موجود دائمًا	boolean	تساوي `true` فقط حين يعطيك كشف هذه البطاقة رمزًا. والبطاقة المستردّة أو غير الصالحة أو التي لا رمز لها تساوي `false`: لا تعرضها على عميلك النهائي.
`purchasedAt`	string (date-time)	وقت شرائها.
`unitPrice`	any	ما دفعته ثمنًا لهذه البطاقة. الاسترداد اللاحق لا يغيّره.
`expiryDate`	string (date)	آخر يوم يمكن فيه استخدام البطاقة، بصيغة `yyyy-MM-dd`. أبلغ به عميلك النهائي. غير موجود حين لا يكون للبطاقة تاريخ انتهاء.

CardSummary

الحقل	النوع	ملاحظات
`id`	UUID	معرّف بطاقة الكتالوج.
`name`	LocalizedText	اسم البطاقة بالعربية والإنجليزية؛ يُحذف النص المحلي الفارغ.
`faceValue`	string	القيمة المطبوعة الاختيارية؛ تُحذف حين تكون فارغة.
`logo`	string	عنوان URL مطلق واختياري لشعار الفئة الفرعية؛ يُحذف حين يكون فارغًا.
`subcategory`	object	الفئة الفرعية للبطاقة، بمعرّفها واسمها المحلي.
`subcategory.id`	UUID	معرّف الفئة الفرعية.
`subcategory.name`	LocalizedText	اسم الفئة الفرعية بالعربية والإنجليزية.
`category`	object	فئة البطاقة، بمعرّفها واسمها المحلي.
`category.id`	UUID	معرّف الفئة.
`category.name`	LocalizedText	اسم الفئة بالعربية والإنجليزية.

LocalizedText

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