مرجع API · الشحن المباشر

طلب الشحن المباشر

POST/v1/wallets/{walletId}/direct-recharges

ادفع من هذه المحفظة ليتولى موظفو أنيس تسليم المبلغ للمستلم. احتفظ بمعرّف العملية نفسه إذا ضاع الردّ. منتجات الفواتير (billing) غير متاحة بعد.

الصلاحيةdirect_recharges:create

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

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

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

حزمة SDK لـ ‎.NETanis.DirectRecharges.CreateAsync(walletId, operationId, request)

كل ردّ معالجة بالحالة 202 يحتوي فقط operationId وoperationType وstatus: "processing"؛ وتكون operationType هي directRecharge. تستخدم القراءة الكاملة الحالة 200.
عدم ظهور العملية في القراءة لا يثبت غيابها. أعد المحتوى المحفوظ نفسه بمعرّف العملية نفسه وتوقيع جديد. يبقى الردّ على العملية المكررة 202 أثناء تأخر ظهورها. لا تُغلق العملية بالرمز idempotency_conflict والحالة 409 إلا إذا كشفت هذه المحاولة تكرار العملية بعد مرور 60 ثانية أو أكثر منذ قبولها الأول، ثم لم تجدها قراءة لاحقة خاصة بتطبيقك. غياب القراءة أو انتهاء المهلة وحده لا يثبت التعارض. ولا يثبت هذا الرمز أن شيئًا لم يُخصم: فقد يكون الطلب الأول قُبل بالفعل، فاقرأ العملية قبل أي محاولة جديدة.
تُحتسب عملية الشراء ضمن حدّ orders الحالي وسقف الإنفاق اليومي نفسه للتطبيق مع طلبات البطاقات والمشتريات الأخرى.

المعاملات

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

الاستدعاء

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

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

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

الحقل	النوع	ملاحظات
`productId`إلزامي	UUID	معرّف منتج الشحن المباشر المختار.
`payoutAmount`إلزامي	string	نص مبلغ التسليم المطلوب من عرض السعر.
`expectedTotal`إلزامي	any	الإجمالي الذي أكّدته من الباقة أو عرض السعر، بصيغة Money وعملة LYD. فحص الرصيد دقيق حتى `999,999.999 LYD`.
`recipient`إلزامي	list of DirectRechargeRecipientInput	قيم المستلم بمفاتيحها، ويُتحقق منها وفق هذا المنتج.
`note`	string	ملاحظتك الاختيارية لعملية الشحن المباشر هذه.
`externalReference`	string	مرجعك الخاص؛ يظهر إن أرسلته.

الردود

الحالة	المعنى	المحتوى
200	نجاح.	DirectRecharge
202	قُبل — لا نتيجة بعد.	DirectRechargeAccepted
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
فشل التحقق	`validation_failed`	422
الخدمة غير متاحة	`dependency_unavailable`	503
انتهت مهلة الاستدعاء	`request_timeout`	504
خطأ داخلي	`internal_error`	500
الحساب غير مخوَّل	`binding_not_authorized`	403
الحساب غير فعّال	`account_inactive`	403
المحفظة غير ممنوحة	`wallet_not_granted`	404
غير موجود	`resource_not_found`	404
العملة غير مدعومة	`currency_not_supported`	422
المحفظة معطّلة	`wallet_disabled`	409
انتهت صلاحية المحفظة	`wallet_expired`	409
يلزم اشتراك أعمال	`business_subscription_required`	409
اكتُشف تكرار	`replay_detected`	409
معرّف العملية مستخدم من قبل	`idempotency_conflict`	409
تغيّر السعر	`price_changed`	409
الرصيد غير كافٍ	`insufficient_balance`	409
بُلغ سقف الإنفاق	`spending_limit_exceeded`	429
منتج الشحن المباشر غير متاح	`direct_recharge_product_unavailable`	409
المبلغ خارج الحدود	`amount_out_of_range`	422
الشراء غير مسموح	`purchase_not_allowed`	403

الأنواع

CreateDirectRechargeRequest

الحقل	النوع	ملاحظات
`productId`إلزامي	UUID	معرّف منتج الشحن المباشر المختار.
`payoutAmount`إلزامي	string	نص مبلغ التسليم المطلوب من عرض السعر.
`expectedTotal`إلزامي	any	الإجمالي الذي أكّدته من الباقة أو عرض السعر، بصيغة Money وعملة LYD. فحص الرصيد دقيق حتى `999,999.999 LYD`.
`recipient`إلزامي	list of DirectRechargeRecipientInput	قيم المستلم بمفاتيحها، ويُتحقق منها وفق هذا المنتج.
`note`	string	ملاحظتك الاختيارية لعملية الشحن المباشر هذه.
`externalReference`	string	مرجعك الخاص؛ يظهر إن أرسلته.

DirectRechargeRecipientInput

الحقل	النوع	ملاحظات
`key`إلزامي	string	مفتاح الحقل كما ورد في تعريف المنتج.
`value`إلزامي	string	قيمة الحقل المرسلة؛ ويستخدم اختيار الموقع معرّفه.

DirectRecharge

الحقل	النوع	ملاحظات
`operationId`موجود دائمًا	UUID	قيمة UUID نفسها المرسلة في `Idempotency-Key` لهذا الشراء.
`status`موجود دائمًا	DirectRechargeStatus	الحالة المدمجة المعروضة للعميل؛ تضيف الإعادة الجزئية مبالغ بدل حالة جديدة.
`number`موجود دائمًا	integer	رقم عملية الشحن المباشر المسجّل.
`walletId`موجود دائمًا	string	المحفظة المستخدمة في هذا الشراء.
`product`موجود دائمًا	DirectRechargeProductReference	معرّف منتج الشحن المباشر المشترى وعنوانه.
`payout`موجود دائمًا	DirectRechargePayout	نص مبلغ التسليم وعملته المسماة؛ وليس بصيغة Money للدينار.
`exchangeRate`موجود دائمًا	string	سعر الصرف المعروض كنص عشري.
`price`موجود دائمًا	Money	السعر بالدينار الليبي مع تعديلات الموقع وشريحة المحفظة المطبّقة.
`commission`موجود دائمًا	Money	العمولة بالدينار الليبي المشمولة في `total`.
`total`موجود دائمًا	Money	إجمالي تكلفة المحفظة بصيغة Money وعملة LYD. فحص الرصيد دقيق حتى `999,999.999 LYD`.
`recipient`موجود دائمًا	list of DirectRechargeRecipientValue	قيم المستلم المحفوظة وتسميات عرضها.
`note`	string	ملاحظتك الاختيارية لعملية الشحن المباشر هذه.
`externalReference`	string	مرجعك الخاص؛ يظهر إن أرسلته.
`requestedAt`موجود دائمًا	string (date-time)	وقت طلب عملية الشحن المباشر بتوقيت UTC.
`completedAt`	string (date-time)	وقت الإكمال إن ورد، بتوقيت UTC.
`proofUrl`	string	عنوان إثبات التسليم المحفوظ إن ورد؛ دون ضمان للوصول أو مدة الصلاحية.
`reason`	string	سبب التعليق أو الرفض في إحدى حالتيه.
`partialRefund`	DirectRechargePartialRefund	مبالغ الإعادة الجزئية المسوّاة والمتبقي؛ لا تحدث إلا إذا فُعّلت الإعادة الجزئية للمنتج.

DirectRechargeStatus

DirectRechargeProductReference

الحقل	النوع	ملاحظات
`id`موجود دائمًا	UUID	معرّف منتج الشحن المباشر المختار.
`title`موجود دائمًا	string	نص منتج الشحن المباشر المعروض.

DirectRechargePayout

الحقل	النوع	ملاحظات
`amount`موجود دائمًا	string	مبلغ التسليم كنص عشري.
`currency`موجود دائمًا	DirectRechargeCurrency	كائن اسم عرض عملة التسليم.

DirectRechargeCurrency

الحقل	النوع	ملاحظات
`name`موجود دائمًا	string	اسم العرض الوارد لهذا العنصر.

Money

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

DirectRechargeRecipientValue

الحقل	النوع	ملاحظات
`key`موجود دائمًا	string	مفتاح الحقل كما ورد في تعريف المنتج.
`name`	LocalizedText	تسميات العرض بالعربية والإنجليزية مع حذف اللغة الفارغة.
`value`موجود دائمًا	string	قيمة الحقل المرسلة؛ ويستخدم اختيار الموقع معرّفه.
`valueName`	string	اسم عرض القيمة المختارة إن ورد.

LocalizedText

الحقل	النوع	ملاحظات
`ar`	string	النص العربي؛ يُحذف حين يكون فارغًا.
`en`	string	النص الإنجليزي؛ يُحذف حين يكون فارغًا.

DirectRechargePartialRefund

الحقل	النوع	ملاحظات
`refundedPayout`موجود دائمًا	string	نص مبلغ التسليم المعاد أو المتبقي بعملة المنتج.
`refundedTotal`موجود دائمًا	Money	مبلغ المحفظة المعاد أو المتبقي بالدينار الليبي.
`remainingPayout`موجود دائمًا	string	نص مبلغ التسليم المعاد أو المتبقي بعملة المنتج.
`remainingTotal`موجود دائمًا	Money	مبلغ المحفظة المعاد أو المتبقي بالدينار الليبي.

DirectRechargeAccepted

الحقل	النوع	ملاحظات
`operationId`موجود دائمًا	UUID	قيمة UUID نفسها المرسلة في `Idempotency-Key` لهذا الشراء.
`operationType`موجود دائمًا	string	تكون دائمًا `directRecharge`. القيم: `directRecharge`
`status`موجود دائمًا	string	تكون دائمًا `processing`؛ النتيجة لم تصبح نهائية. القيم: `processing`