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

متابعة عملية شحن مباشر مطلوبة

GET/v1/direct-recharges/{operationId}

تابع الدفع والتسليم وتصحيح بيانات المستلم والمبالغ المعادة فعلًا لعملية شحن مباشر طلبها تطبيقك.

الصلاحيةdirect_recharges:read

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

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

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

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

كل ردّ معالجة بالحالة 202 يحتوي فقط operationId وoperationType وstatus: "processing"؛ وتكون operationType هي directRecharge. تستخدم القراءة الكاملة الحالة 200.
إذا رُفض الإنشاء وسُجّل رفضًا فلا شحن مباشر نشأ: تعيد القراءة هذا الرفض المسجّل (409 أو 422) مع Idempotency-Replayed: true، ولم يُخصم شيء. وعند القراءة يعني idempotency_conflict أنه لا يوجد شحن مباشر لتطبيقك بهذا المعرّف.

المعاملات

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

الاستدعاء

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

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

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

الردود

الحالة	المعنى	المحتوى
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
غير موجود	`resource_not_found`	404
الرصيد غير كافٍ	`insufficient_balance`	409
تغيّر السعر	`price_changed`	409
منتج الشحن المباشر غير متاح	`direct_recharge_product_unavailable`	409
المبلغ خارج الحدود	`amount_out_of_range`	422
معرّف العملية مستخدم من قبل	`idempotency_conflict`	409

الأنواع

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`