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

تقديم طلب شراء

POST/v1/wallets/{walletId}/orders

يشتري بطاقات من محفظة، بمعرّف عملية تختاره أنت وتحفظه. إرسال المعرّف نفسه مجددًا لا يشتري مرتين أبدًا: بل يستأنف طلب الشراء نفسه.

الصلاحيةorders:create

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

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

حزمة SDK لـ ‎.NETanis.Orders.CreateAsync(walletId, operationId, order) / ResumeAsync(...)

201: اكتمل طلب الشراء، وهذا الرد يحمل رموز البطاقات. احفظها أولًا.
200: الرد الذي يتلقاه الاستئناف حين ضاع الرد الأول. إن كان يحمل رموز البطاقات فهذه أول مرة تراها — احفظها.
الرد الموسوم بـ Idempotency-Replayed: true يكرّر طلب شراء أُرسلت نتيجته من قبل: يحمل الطلب لا الرموز. وإن لم يصلك ذلك الرد الأول قط — بانتهاء المهلة — فالرموز كانت فيه: اكشفها بمعرّف فاتورة طلب الشراء، وهذا يحتاج cards:reveal.
202: قُبل ولا نتيجة بعد. أرسل طلب الشراء نفسه مجددًا بعد Retry-After.

المعاملات

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

الاستدعاء

موقَّع بمفتاحك، مع رقم استخدام لمرة واحدة (nonce) وبصمة للمحتوى ومعرّف العملية في Idempotency-Key.

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

المحتوى: CreateOrderRequest، بصيغة JSON.

الحقل	النوع	ملاحظات
`externalReference`	string	مرجعك الخاص، من 1 إلى 100 حرف: حروف لاتينية وأرقام ومسافة و `- _ . : / #`.
`cardId`إلزامي	UUID	بطاقة الكتالوج المراد شراؤها.
`quantity`إلزامي	integer	1 على الأقل وحتى الحد الأعلى للطلب الواحد (100 افتراضيًا)، وضمن الحد الأدنى والأعلى الخاص بالبطاقة.
`expectedUnitPrice`إلزامي	Money	`unitPrice` الخاص بالبطاقة تمامًا كما عرضه الكتالوج لهذه المحفظة.
`expectedTotal`إلزامي	Money	`expectedUnitPrice` مضروبًا في `quantity` بالضبط — محسوبًا دون أرقام عشرية عائمة (floating point).
`useAllowedDebt`	boolean	اجعله `true` فقط إن كنت تأذن باستخدام الدين المسموح للحساب. قيمته الافتراضية `false` ولا يُفعَّل نيابةً عنك أبدًا.

الردود

الحالة	المعنى	المحتوى
200	نجاح.	Order
201	اكتمل طلب الشراء.	Order
202	قُبل — لا نتيجة بعد.	Order
401	مرفوض: لم تتم المصادقة.	مشكلة
402	مرفوض: يلزم الإذن باستخدام الدين المسموح.	مشكلة
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
غير موجود	`resource_not_found`	404
فشل التحقق	`validation_failed`	422
العملة غير مدعومة	`currency_not_supported`	422
معرّف العملية مستخدم من قبل	`idempotency_conflict`	409
يلزم الإذن باستخدام الدين المسموح	`allowed_debt_consent_required`	402
الرصيد غير كافٍ	`insufficient_balance`	409
الشراء غير مسموح	`purchase_not_allowed`	403
رُفض طلب الشراء	`purchase_not_allowed`	409
يلزم اشتراك أعمال	`business_subscription_required`	409
المحفظة معطّلة	`wallet_disabled`	409
انتهت صلاحية المحفظة	`wallet_expired`	409
البطاقة غير متاحة	`card_unavailable`	409
الكمية غير متاحة	`quantity_unavailable`	409
تغيّر السعر	`price_changed`	409
استُنفد حدّ الإنفاق	`owner_limit_exceeded`	409
بُلغ الحدّ اليومي	`daily_limit_exceeded`	429
الخدمة غير متاحة	`dependency_unavailable`	503
انتهت مهلة الاستدعاء	`request_timeout`	504
خطأ داخلي	`internal_error`	500

الأنواع

CreateOrderRequest

الحقل	النوع	ملاحظات
`externalReference`	string	مرجعك الخاص، من 1 إلى 100 حرف: حروف لاتينية وأرقام ومسافة و `- _ . : / #`.
`cardId`إلزامي	UUID	بطاقة الكتالوج المراد شراؤها.
`quantity`إلزامي	integer	1 على الأقل وحتى الحد الأعلى للطلب الواحد (100 افتراضيًا)، وضمن الحد الأدنى والأعلى الخاص بالبطاقة.
`expectedUnitPrice`إلزامي	Money	`unitPrice` الخاص بالبطاقة تمامًا كما عرضه الكتالوج لهذه المحفظة.
`expectedTotal`إلزامي	Money	`expectedUnitPrice` مضروبًا في `quantity` بالضبط — محسوبًا دون أرقام عشرية عائمة (floating point).
`useAllowedDebt`	boolean	اجعله `true` فقط إن كنت تأذن باستخدام الدين المسموح للحساب. قيمته الافتراضية `false` ولا يُفعَّل نيابةً عنك أبدًا.

Money

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

Order

الحقل	النوع	ملاحظات
`operationId`موجود دائمًا	UUID	معرّف العملية الذي اخترته وأرسلته في `Idempotency-Key`.
`status`موجود دائمًا	string	`processing`: قُبل ولا نتيجة بعد. `completed`: تمّ الشراء. `failed`: رفضته قاعدة عمل، ولم يُشترَ شيء. `recoveryExhausted`: لم تتمكن أنيس بعد من معرفة النتيجة — ربما اكتمل؛ واصل الاستئناف ببطء وأبلغ أنيس. القيم: `processing`, `recoveryExhausted`, `completed`, `failed`
`invoiceId`	UUID	الفاتورة التي عليها البطاقات. استخدمه لكشفها مجددًا لاحقًا.
`walletId`	UUID	المحفظة التي دُفع منها طلب الشراء.
`cardId`	UUID	بطاقة الكتالوج التي اشتُريت.
`quantity`	integer	عدد البطاقات.
`total`	Money	تكلفة طلب الشراء.
`soldCards`	list of RevealedCredential	رموز البطاقات. موجودة فقط في الرد الذي يعلن اكتمال طلب الشراء أول مرة — احفظها قبل أي شيء آخر.
`completedAt`	string (date-time)	وقت اكتمال طلب الشراء.

RevealedCredential

الحقل	النوع	ملاحظات
`soldCardId`موجود دائمًا	UUID	البطاقة المبيعة التي تخصها هذه الرموز.
`serialNumber`	string	الرقم التسلسلي للبطاقة. سرّ: احفظه حيث تحفظ الأسرار ولا تسجّله في السجلات أبدًا.
`voucher`	string	رمز القسيمة للبطاقة. سرّ: احفظه حيث تحفظ الأسرار ولا تسجّله في السجلات أبدًا.
`revealedAt`	string (date-time)	وقت كشفها.