مرجع 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.
يجب ألا يتجاوز محتوى طلب الشراء 8,192 بايت (8 كيلوبايت)، بترميز UTF-8 — ويُرفض Content-Type يذكر charset آخر بالحالة HTTP ‏422 والرمز validation_failed. يُرفض المحتوى الأكبر بالحالة HTTP ‏422 والرمز validation_failed.
الحالة HTTP ‏429 والرمز spending_limit_exceeded: لم يُقدَّم طلب الشراء لأنه سيتجاوز سقف إنفاق التطبيق لهذه النافذة. انتظر إعادة ضبط النافذة بحسب 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` الخاصة بالبطاقة كما عرضها الكتالوج لهذه المحفظة، بصيغة `Money` المشتركة.
`expectedTotal`إلزامي	Money	`expectedUnitPrice` مضروبًا في `quantity` بالضبط — محسوبًا دون أرقام عشرية عائمة (floating point).
`useAllowedDebt`	boolean	اجعله `true` فقط إن كنت تأذن باستخدام الدين المسموح للحساب. قيمته الافتراضية `false` ولا يُفعَّل نيابةً عنك أبدًا.

الردود

الحالة	المعنى	المحتوى
200	نجاح.	Order
201	اكتمل طلب الشراء.	Order
202	قُبل — لا نتيجة بعد.	Order
400	مرفوض: الاستدعاء الموقّع غير سليم البنية.	مشكلة
401	مرفوض: لم تتم المصادقة.	مشكلة
402	مرفوض: يلزم الإذن باستخدام الدين المسموح.	مشكلة
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
العملة غير مدعومة	`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
بُلغ سقف الإنفاق	`spending_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` الخاصة بالبطاقة كما عرضها الكتالوج لهذه المحفظة، بصيغة `Money` المشتركة.
`expectedTotal`إلزامي	Money	`expectedUnitPrice` مضروبًا في `quantity` بالضبط — محسوبًا دون أرقام عشرية عائمة (floating point).
`useAllowedDebt`	boolean	اجعله `true` فقط إن كنت تأذن باستخدام الدين المسموح للحساب. قيمته الافتراضية `false` ولا يُفعَّل نيابةً عنك أبدًا.

Money

الحقل	النوع	ملاحظات
`amount`إلزامي	string	نص عشري، وليس عدد JSON. قد يكون رصيد المحفظة سالبًا عند استخدام الدين المسموح. تتبع الأسعار والإجماليات قواعد المبلغ لكل مسار.
`currency`إلزامي	string	رمز عملة من ثلاثة أحرف كبيرة، مثل `LYD`. اقرأ عملة المحفظة من `balance.currency`.
`asOf`	string (date-time)	وقت قراءة هذا السعر أو الرصيد.

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