مرجع API · البطاقات المملوكة
كشف فاتورة
POST
/v1/wallets/{walletId}/invoices/{invoiceId}/owned-cards/revealPOST /v1/wallets/{walletId}/invoices/{invoiceId}/owned-cards/reveal — يعرض رموز كل بطاقة في فاتورة — كلها أو لا شيء، حتى 100 بطاقة. لا يرسل أي محتوى.
الصلاحية
cards:revealالمصادقةتغيير موقَّع
ردّ أنيسموقَّع
حدود الموظفين التي يُحتسب ضمنهاكل الاستدعاءات، الكشف
حزمة SDK لـ .NET
anis.OwnedCards.RevealInvoiceAsync(walletId, invoiceId)المعاملات
| الاسم | الموضع | النوع | ملاحظات |
|---|---|---|---|
walletIdإلزامي | path | UUID | معرّف UUID بأحرف صغيرة مع الشرطات. |
invoiceIdإلزامي | path | UUID | معرّف UUID بأحرف صغيرة مع الشرطات. |
الاستدعاء
موقَّع بمفتاحك، مع رقم استخدام لمرة واحدة (nonce) وبصمة للمحتوى.
الترويسات: Signature-Input، Signature، Content-Digest، Nonce، X-Anis-Date، Accept-Language (اختياري). تضبطها حزم SDK كلها نيابةً عنك.
المحتوى: لا محتوى إطلاقًا — ولا حتى {}. أي بايت يُرفض بـ validation_failed. ويبقى التوقيع شاملًا بصمة المحتوى الفارغ.
الردود
| الحالة | المعنى | المحتوى |
|---|---|---|
| 200 | نجاح. | RevealedCredentialCollection |
| 400 | مرفوض: الاستدعاء الموقّع غير سليم البنية. | مشكلة |
| 401 | مرفوض: لم تتم المصادقة. | مشكلة |
| 403 | مرفوض: غير مسموح. | مشكلة |
| 404 | مرفوض: غير موجود، أو ليس لك. | مشكلة |
| 409 | مرفوض: يتعارض مع الحالة الحالية. | مشكلة |
| 422 | مرفوض: الاستدعاء يخالف قاعدة. | مشكلة |
| 429 | مرفوض: بلغتَ حدًا. | مشكلة |
| 503 | لا قرار: خدمة مطلوبة غير متاحة. | مشكلة |
كل ردّ على هذا الاستدعاء موقَّع من أنيس — النجاح وكل رفض. اشترط وجود التوقيع وتحقّق منه قبل أن تتصرف بناءً على الردّ؛ والردّ بلا توقيع فشل، لا يُعدّ ردًّا (كيف).
حالات الرفض
كل رفض لهذا الاستدعاء مشكلةٌ موقَّعة. ابنِ منطقك على رمزها code؛ وكلٌّ منها يرتبط بصفحة تشرح معناه وما عليك فعله.
| الخطأ | الرمز | الحالة |
|---|---|---|
| بيانات اعتماد غير صالحة | invalid_credentials | 401 |
| استدعاء موقّع غير سليم البنية | malformed_signed_request | 400 |
| صلاحية غير كافية | insufficient_scope | 403 |
| عنوان المصدر غير مسموح | source_ip_not_allowed | 403 |
| تجاوزت حدّ الاستدعاءات | rate_limited | 429 |
| اكتُشف تكرار | replay_detected | 409 |
| الحساب غير مخوَّل | binding_not_authorized | 403 |
| الحساب غير فعّال | account_inactive | 403 |
| المحفظة غير ممنوحة | wallet_not_granted | 404 |
| غير موجود | resource_not_found | 404 |
| فشل التحقق | validation_failed | 422 |
| الكشف غير مسموح | reveal_not_allowed | 409 |
| الفاتورة أكبر من أن تُكشف | invoice_reveal_limit_exceeded | 409 |
| يلزم اشتراك أعمال | business_subscription_required | 409 |
| المحفظة معطّلة | wallet_disabled | 409 |
| انتهت صلاحية المحفظة | wallet_expired | 409 |
| الخدمة غير متاحة | dependency_unavailable | 503 |
| انتهت مهلة الاستدعاء | request_timeout | 504 |
| خطأ داخلي | internal_error | 500 |
الأنواع
RevealedCredentialCollection
| الحقل | النوع | ملاحظات |
|---|---|---|
itemsموجود دائمًا | list of RevealedCredential | كل بطاقة في الفاتورة مع رموزها — كلها أو لا شيء، 100 بطاقة على الأكثر. |
RevealedCredential
| الحقل | النوع | ملاحظات |
|---|---|---|
soldCardIdموجود دائمًا | UUID | البطاقة المبيعة التي تخصها هذه الرموز. |
serialNumber | string | الرقم التسلسلي للبطاقة. سرّ: احفظه حيث تحفظ الأسرار ولا تسجّله في السجلات أبدًا. |
voucher | string | رمز القسيمة للبطاقة. سرّ: احفظه حيث تحفظ الأسرار ولا تسجّله في السجلات أبدًا. |
revealedAt | string (date-time) | وقت كشفها. |
expiryDate | string (date) | آخر يوم يمكن فيه استخدام البطاقة، بصيغة yyyy-MM-dd. أبلغ به عميلك النهائي. غير موجود حين لا يكون للبطاقة تاريخ انتهاء. |
invoiceId | any | الفاتورة التي عليها البطاقة. يظهر أيضًا داخل soldCards في طلب الشراء. |
card | CardSummary | بطاقة الكتالوج التي بيعت، لتعرف لأي بطاقة هذه الرموز. تظهر أيضًا داخل soldCards في طلب الشراء. |
purchasedAt | string (date-time) | وقت شراء البطاقة. يظهر أيضًا داخل soldCards في طلب الشراء. |
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 | النص الإنجليزي؛ يُحذف حين يكون فارغًا. |