مرجع API · البطاقات المملوكة
كشف بطاقة
POST
/v1/wallets/{walletId}/cards/{soldCardId}/revealيعرض رموز بطاقة مشتراة واحدة. لا يرسل أي محتوى.
الصلاحية
cards:revealالمصادقةتغيير موقَّع
حدود الموظفين التي يُحتسب ضمنهاكل الاستدعاءات، الكشف
حزمة SDK لـ .NET
anis.OwnedCards.RevealAsync(walletId, soldCardId)المعاملات
| الاسم | الموضع | النوع | ملاحظات |
|---|---|---|---|
walletIdإلزامي | path | UUID | معرّف UUID بأحرف صغيرة مع الشرطات. |
soldCardIdإلزامي | path | UUID | معرّف UUID بأحرف صغيرة مع الشرطات. |
الاستدعاء
موقَّع بمفتاحك، مع رقم استخدام لمرة واحدة (nonce) وبصمة للمحتوى.
الترويسات: Signature-Input، Signature، Content-Digest، Nonce، X-Anis-Date، Accept-Language (اختياري). تضبطها حزم SDK كلها نيابةً عنك.
المحتوى: لا محتوى إطلاقًا — ولا حتى {}. أي بايت يُرفض بـ validation_failed. ويبقى التوقيع شاملًا بصمة المحتوى الفارغ.
الردود
| الحالة | المعنى | المحتوى |
|---|---|---|
| 200 | نجاح. | RevealedCredential |
| 401 | مرفوض: لم تتم المصادقة. | مشكلة |
| 403 | مرفوض: غير مسموح. | مشكلة |
| 404 | مرفوض: غير موجود، أو ليس لك. | مشكلة |
| 409 | مرفوض: يتعارض مع الحالة الحالية. | مشكلة |
| 422 | مرفوض: الاستدعاء يخالف قاعدة. | مشكلة |
| 429 | مرفوض: بلغتَ حدًا. | مشكلة |
| 503 | لا قرار: خدمة مطلوبة غير متاحة. | مشكلة |
كل ردّ موقَّع من أنيس؛ وتتحقق منه حزم SDK قبل أن يصلك.
حالات الرفض
كل رفض مشكلةٌ موقَّعة. ابنِ منطقك على رمزها code؛ وكلٌّ منها يرتبط بصفحة تشرح معناه وما عليك فعله.
| الخطأ | الرمز | الحالة |
|---|---|---|
| بيانات اعتماد غير صالحة | invalid_credentials | 401 |
| صلاحية غير كافية | 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 |
| البطاقة غير موجودة | card_not_found | 404 |
| فشل التحقق | validation_failed | 422 |
| الكشف غير مسموح | reveal_not_allowed | 409 |
| يلزم اشتراك أعمال | business_subscription_required | 409 |
| المحفظة معطّلة | wallet_disabled | 409 |
| انتهت صلاحية المحفظة | wallet_expired | 409 |
| الخدمة غير متاحة | dependency_unavailable | 503 |
| انتهت مهلة الاستدعاء | request_timeout | 504 |
| خطأ داخلي | internal_error | 500 |
الأنواع
RevealedCredential
| الحقل | النوع | ملاحظات |
|---|---|---|
soldCardIdموجود دائمًا | UUID | البطاقة المبيعة التي تخصها هذه الرموز. |
serialNumber | string | الرقم التسلسلي للبطاقة. سرّ: احفظه حيث تحفظ الأسرار ولا تسجّله في السجلات أبدًا. |
voucher | string | رمز القسيمة للبطاقة. سرّ: احفظه حيث تحفظ الأسرار ولا تسجّله في السجلات أبدًا. |
revealedAt | string (date-time) | وقت كشفها. |