مرجع API · طلبات الشراء

قراءة طلب شراء

GET/v1/orders/{operationId}

أين وصل طلب الشراء، وأي طلب هو: مرجعك والبطاقة والكمية — والإجمالي بعد أن يكتمل. لا يحمل رموز البطاقات أبدًا ولا يدفع الطلب إلى الأمام — لاستئناف طلب شراء أرسله مجددًا.

الصلاحيةorders:read

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

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

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

حزمة SDK لـ ‎.NETanis.Orders.GetAsync(operationId)

مسموح بصلاحية orders:read، أو بصلاحية orders:create لطلباتك أنت.
في طلب شراء فشل، يقول failureCode السبب.

المعاملات

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

الاستدعاء

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

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

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

الردود

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

كل ردّ على هذا الاستدعاء موقَّع من أنيس — النجاح وكل رفض. اشترط وجود التوقيع وتحقّق منه قبل أن تتصرف بناءً على الردّ؛ والردّ بلا توقيع فشل، لا يُعدّ ردًّا (كيف).

حالات الرفض

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

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

الأنواع

Order

الحقل	النوع	ملاحظات
`operationId`موجود دائمًا	UUID	معرّف العملية الذي اخترته وأرسلته في `Idempotency-Key`.
`status`موجود دائمًا	string	`processing`: قُبل ولا نتيجة بعد. `completed`: تمّ الشراء. `failed`: رفضته قاعدة عمل، ولم يُشترَ شيء. `recoveryExhausted`: لم تتمكن أنيس بعد من معرفة النتيجة — ربما اكتمل؛ واصل الاستئناف ببطء واكتب إلى support@anis.ly واذكر معرّف العملية. القيم: `processing`, `recoveryExhausted`, `completed`, `failed`
`invoiceId`	UUID	الفاتورة التي عليها البطاقات. استخدمه لكشفها مجددًا لاحقًا.
`walletId`	UUID	المحفظة التي دُفع منها طلب الشراء.
`cardId`	any	بطاقة الكتالوج المطلوبة. موجودة في كل ردّ على طلب الشراء — الأول وتكراره والقراءة.
`quantity`	integer	عدد البطاقات المطلوبة. موجود في كل ردّ على طلب الشراء، بما فيه التكرار والقراءة.
`total`	any	تكلفة طلب الشراء. موجودة في كل ردّ تكون فيه `status` مساوية لـ `completed`، بما فيه التكرار والقراءة؛ وغير موجودة ما دام `processing` أو بعد أن `failed`.
`externalReference`	string	مرجعك الخاص كما أرسلته تمامًا. موجود في كل ردّ على طلب الشراء، بما فيه التكرار والقراءة — ويخبرك أي عملية بيع لديك هذه. غير موجود حين لا يحمل الطلب مرجعًا.
`failureCode`	string	سبب فشل طلب الشراء: رمز الرفض الذي سجّلته أنيس، وهو أحد رموز الأخطاء. يظهر فقط في قراءة طلب شراء قيمة `status` فيه `failed`. غير موجود حين لا يكون لذلك الرفض رمز علني.
`codesWithheld`	boolean	تساوي `true` فقط في الرد الذي يعلن أول مرة طلب شراء مدفوعًا ومكتملًا تعذّر إصدار رموزه. لا تشترِه مرة أخرى، واكتب إلى support@anis.ly واذكر معرّف العملية. لا تساوي `false` أبدًا: في كل رد آخر هي غير موجودة، وفي التكرار أو القراءة يعني غيابها «غير مذكور».
`soldCards`	list of RevealedCredential	رموز البطاقات. موجودة فقط في الرد الذي يعلن اكتمال طلب الشراء أول مرة — احفظها قبل أي شيء آخر.
`completedAt`	string (date-time)	وقت اكتمال طلب الشراء.

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	النص الإنجليزي؛ يُحذف حين يكون فارغًا.