💰 توثيق أنظمة السحب في الوكالات (Agency Withdrawal Systems)

يوفر هذا المستند دليلاً شاملاً لنقاط نهاية API الخاصة بأنظمة السحب والتحويل المالي المتاحة للوكلاء والمضيفين.

وكيل الشحن (gold_agent)

طلب تحويل دولارات إلى ماسات عبر وكيل شحن خارجي يتم دفعه يدوياً.

وكيل التسوية (cash)

صرف دولارات كاش عبر تحويل بنكي أو وسيلة كاش بواسطة وكيل التسوية.

المنصة (فوري)

تحويل فوري من دولارات التارجت إلى ماسات للمستفيد مباشرةً داخل التطبيق.

محافظ الرصيد وطريقة الحساب

يتم الاعتماد بالكامل على الحقول التراكمية المباشرة في جدول المستخدمين (users) لضمان الدقة والمزامنة:

  • عمولة الوكيل (agent_benefit = true): تخصم وتدار عبر حقل wallet_agent_dollars_count في جدول المستخدمين.
  • دولارات المضيف/التارجت (agent_benefit = false / افتراضي): تخصم وتدار عبر حقل wallet_dollars_count في جدول المستخدمين.
⚠️ تنبيه هام: لحساب الرصيد المتاح للسحب بدقة، يتم خصم قيمة الطلبات المعلقة (status = pending) فقط من الرصيد الحالي للمحفظة، بينما الطلبات المقبولة (approved) تخصم مباشرةً وبشكل فوري عند التحديث.

1. وكيل الشحن — gold_agent

المضيف يطلب تحويل دولاراته إلى ماسات عبر وكيل شحن خارجي يقوم بالدفع للمستفيد يدوياً (خارج التطبيق).

POST /api/v1/agency/target-withdraw-requests/request

البارامترات المطلوبة (Request Body):

الحقل النوع حالة الوجوب الوصف
type string ✅ إجباري يجب أن تكون القيمة: gold_agent
target_user_id integer ✅ إجباري ID وكيل الشحن المختار.
beneficiary_user_id integer ✅ إجباري ID المستخدم الذي سيستقبل الماسات.
amount_in_dollars numeric ✅ إجباري المبلغ المراد سحبه بالدولار (الحد الأدنى: 1$).
country_id integer ✅ إجباري ID الدولة.
agent_benefit boolean ⬜ اختياري true لخصم المبلغ من محفظة الوكيل بدلاً من محفظة المضيف.

مثال الطلب:

{
  "type": "gold_agent",
  "target_user_id": 123,
  "beneficiary_user_id": 456,
  "amount_in_dollars": 10,
  "country_id": 1,
  "agent_benefit": false,
  "user_notice": "تحويل لوكيل شحن"
}

2. وكيل التسوية — cash

المضيف يطلب صرف دولاراته كاش عبر تحويل بنكي أو وسيلة استلام بواسطة وكيل التسوية (Business Manager).

POST /api/v1/agency/target-withdraw-requests/request

البارامترات المطلوبة (Request Body):

الحقل النوع حالة الوجوب الوصف
type string ✅ إجباري يجب أن تكون القيمة: cash
business_manager_id integer ✅ إجباري ID وكيل التسوية المالي.
amount_in_dollars numeric ✅ إجباري المبلغ بالدولار (الحد الأدنى: 1$).
country_id integer ✅ إجباري ID الدولة.
bank_details object ✅ إجباري كائن يحتوي على بيانات البنك: bank_name, account_name, account_number.

مثال الطلب:

{
  "type": "cash",
  "business_manager_id": 2,
  "amount_in_dollars": 50,
  "country_id": 1,
  "bank_details": {
    "bank_name": "بنك مصر",
    "account_name": "محمد أحمد علي",
    "account_number": "EG12345678901234567890123"
  },
  "payment_method": "تحويل بنكي"
}

3. المنصة (ذهب فوري) — Platform

تحويل فوري ومباشر. يتم خصم الرصيد من محفظة المضيف أو الوكيل مباشرة وتتم الموافقة الفورية وإرسال الماسات مباشرة إلى محفظة المستخدم المستهدف.

POST /api/v1/agency/target-transaction-requests/request

البارامترات المطلوبة (Request Body):

الحقل النوع حالة الوجوب الوصف
dollars numeric ✅ إجباري المبلغ بالدولار المراد تحويله (الحد الأدنى: 1$).
user_id integer ✅ إجباري ID المستخدم المستلم للماسات.
agent_benefit boolean ⬜ اختياري يُرسل 1 أو true لخصمه من عمولة الوكيل (محفظة الوكيل).

مثال الطلب:

{
  "dollars": 10,
  "user_id": 456,
  "agent_benefit": false
}

4. سجل الطلبات والاستعلام (Queries)

أ. جلب وكلاء الشحن النشطين والمتاحين لاستقبال السحوبات:

GET /api/v1/agency/target-withdraw-requests/charging-agents

يجلب فقط المستخدمين المتاحين كوكلاء شحن نشطين (charging_agent = 1 و allow_receive_withdraw_requests = 1) متضمنة بيانات الدول الخاصة بهم وأسعار التحويل المتاحة.

ب. استعلام سجل طلبات السحب (وكيل الشحن / الكاش):

GET /api/v1/agency/target-withdraw-requests

البارامترات المقبولة (Query Parameters):

  • type: cash (سجل الكاش) أو gold_agent (سجل وكيل الشحن).
  • status: اختياري (pending, approved, rejected, transferred).
  • agent_benefit: 1 لجلب طلبات الوكيل.
💡 ملاحظة هامة جداً: عمليات تحويل المنصة الفورية لها سجل منفصل تماماً ولا تظهر مع طلبات السحب أعلاه. يمكنك جلبها عن طريق المسار التالي:
GET /api/v1/agency/target-transaction-requests
البارامتر status في هذا الطلب اختياري (nullable) - إذا لم يتم إرساله، سيقوم السيرفر بإرجاع كافة المعاملات بغض النظر عن حالتها.

5. ملاحظات تقنية وهامة

  • تحديث الأرصدة التلقائي: يتم تحديث ومزامنة محافظ المضيف والوكيل بشكل تراكمي (increment) عند تشغيل أوامر إيداع الرواتب شهرياً أو دورياً.
  • حالة الـ default للوكيل: عند إنشاء وكيل شحن جديد، لا يمكن استقبال طلبات السحب حتى يتم تفعيل خيار allow_receive_withdraw_requests يدوياً من لوحة التحكم.
  • تخفيض حد السحب: تم تخفيض الحد الأدنى للسحب التجريبي إلى 1 دولار لتسهيل الاختبارات.
  • سعر التحويل الفوري: يتم حساب 10,000 ماسة (Diamonds) لكل 1 دولار في عمليات المنصة الفورية للمستخدم العادي، و 13,000 للوكيل للشحن.