توثيق واجهة سحب عبر الصراف الآلي (ATM Withdrawal) – Genius Link

نبذة سريعة: هذا المستند يغطّي واجهة إنشاء عملية سحب عبر الصراف الآلي ضمن وحدة المعاملات البنكية في نظام Genius Link. يعتمد على ملف OpenAPI المرجعي (Geniuslinksystem.openapi.json). ستجد هنا وصف المسار، مخطط الطلب/الاستجابة، أمثلة فعلية متعددة السيناريوهات (مع/بدون عمولة…)، إضافة إلى قائمة أخطاء تحقق/أعمال محتملة. يفيد مطوري الواجهتين الأمامية والخلفية وفرق الاختبار والتكامل.
الأمان: في ملف المصدر الحالي security: [] (غير مفعل). في بيئة الإنتاج عادة نستخدم Bearer JWT؛ أضف رأس Authorization: Bearer <JWT> حسب سياساتك.

جدول ملخص الEndpoints

المسار	Method	الوصف	الجسم المطلوب	200 Response
`/TenantTransaction/Banking/Withdrawal/atm`	POST	إنشاء عملية سحب عبر الصراف الآلي	`InsertATMWithdrawalTransaction`	`TenantTransactionResult[]`

POST `/TenantTransaction/Banking/Withdrawal/atm`

Tag: TenantTransactionATMWithdrawal
OperationId: TenantTransaction_InsertATMWithdrawal

الوصف

ينشئ عملية سحب عبر الصراف الآلي، تشمل معلومات البطاقة، مُعرّف وموقع جهاز الـATM، ويمكن تضمين عمولة ورسوم خدمة وحد يومي. يتم تسجيل الحساب المدين/الدائن، ومُعرِّفات المُنشئ والجهاز، ومراجع وثائق داعمة.

الرؤوس

Accept: application/json

Content-Type: application/json

(إنتاجيًا): Authorization: Bearer <JWT>

Body — `InsertATMWithdrawalTransaction`

{
  "tenantId": 9,
  "serialNo": "11111111-1111-1111-1111-111111111111",
  "currencyId": "YER",
  "amount": 500000,
  "note": "اختياري",
  "debitAccountId": 13010001,
  "creditAccountId": 11040001,
  "cardNumber": "**** **** **** 1234",
  "atmId": "ATM-SANAA-001",
  "atmLocation": "اختياري: العنوان التفصيلي للـATM",
  "commissionAmount": 2000,
  "commissionAccountId": 4102,
  "dailyLimit": 5000000,
  "transactionReference": null,
  "status": null,
  "createdAt": null,
  "creatorUserId": 9,
  "creatorDeviceId": "e1b3b11d-70d0-5abd-8a45-ce85c27af0d4",
  "documentReferences": "[{\"type\":\"atm_receipt\",\"reference\":\"ATM-REC-001\"}]"
}

ملاحظات المخطط:

أنواع الحقول: serialNo وcreatorDeviceId UUID، المبالغ number (double)، بقية المعرفات int/string حسب الحقل.

حقول مطلوبة شائعة (بحسب أمثلة التحقق): amount موجب، debitAccountId ≠ creditAccountId، الحقول المرتبطة بالـATM (cardNumber, atmId) مطلوبة لسحب ATM.

dailyLimit: للتحقق من عدم تجاوز الحد اليومي.

documentReferences: نص يحتوي JSON مسلسلاً (مثال: قائمة مراجع وثائق كالإيصالات والتحققات).

أمثلة طلب (مطابقة للمصدر)

1) سحب عبر الصراف الآلي مع عمولة

2) سحب بدون رسوم خدمة

3) سحب برسوم خدمة محددة

4) سحب كبير مع وثائق إضافية

200 — `TenantTransactionResult[]` (نجاح)

مخطط مختصر: مصفوفة من كائنات تحتوي تفاصيل العملية (المعرفات، الحالة، الأوصاف، الوقت، سجلات التحويلات/الأرصدة/المنتجات كـJSON نصي…).

مثال استجابة 200

[
  {
    "tenantId": 9,
    "serviceId": 10102,
    "id": 98765,
    "serialNo": "11111111-1111-1111-1111-111111111111",
    "currencyId": "YER",
    "amount": 500000,
    "toCurrencyId": null,
    "toAmount": null,
    "description": "{\"type\":\"atm_withdrawal\",\"atmId\":\"ATM-SANAA-001\"}",
    "status": 1,
    "creatorUserId": 9,
    "createdAt": "2025-09-05T22:40:00Z",
    "updatorUserId": 9,
    "updatedAt": "2025-09-05T22:40:00Z",
    "tenantTransactionTransfers": "[{}]",
    "tenantBalances": "[{}]",
    "tenantTransactionProducts": null,
    "tenantRequest": null,
    "tenantLogs": "[{}]",
    "tenantProductStorages": null
  }
]

400 — `CustomErrorResponse` (أمثلة شائعة)

الملخص	code	category	message
المبلغ يجب أن يكون موجبًا	`ERR_INVALID_AMOUNT`	validation	Amount must be positive
الحسابان متطابقان	`ERR_SAME_ACCOUNT`	validation	Debit and credit accounts must be different
الحساب المدين غير صالح	`ERR_INVALID_ACCOUNT`	validation	Debit account must start with 13 or 23
رقم البطاقة مطلوب	`ERR_CARD_NUMBER_REQUIRED`	validation	Card number is required for ATM withdrawal
معرف الـATM مطلوب	`ERR_ATM_ID_REQUIRED`	validation	ATM ID is required for ATM withdrawal
مبلغ العمولة غير صالح	`ERR_INVALID_COMMISSION_AMOUNT`	validation	Commission amount must be positive
تجاوز الحد اليومي	`ERR_DAILY_LIMIT_EXCEEDED`	business_rule	Daily withdrawal limit exceeded
المعاملة موجودة مسبقًا	`ERR_TRANSACTION_EXISTS`	validation	Transaction Exists
المستأجر/الجهاز/المستخدم غير موجود/غير مفعل/محظور	`ERR_TENANT_`, `ERR_DEVICE_`, `ERR_USER_*`	not_found/data_state	حسب الحالة
علاقة المستأجر غير موجودة/غير مفعّلة/محظورة	`ERR_TENANT_RELATIONSHIP_*`	permission/data_state	حسب الحالة
العملة غير موجودة/غير مفعّلة/محظورة	`ERR_CURRENCY_*`	not_found/data_state	حسب الحالة
حساب المستأجر غير موجود/غير مفعّل/محظور	`ERR_TENANT_ACCOUNT_*`	not_found/data_state	حسب الحالة

راجع رسائل الخطأ التفصيلية عند الاستجابة 400 لتتبّع السبب الدقيق (تتضمن serviceId, verbId, tableName, timestamp).

401/403 — Unauthorized/Forbidden

قد تُعاد وفق سياسة الأمان المطبّقة في منصّتك.

ممارسات موصى بها

Idempotency: مرِّر رأس Idempotency-Key للطلبات المالية الحساسة لتجنب التكرار.

Rate Limiting: عرّف سلوك إعادة المحاولة باستخدام Retry-After إن لزم.

Observability: استخدم X-Request-Id وتتبّع serialNo في اللوجز.

Localization: رسائل الأخطاء يمكن تعريبها وفق Accept-Language.

قائمة فحص سريعة

تحقق من أن amount > 0

تأكد أن debitAccountId ≠ creditAccountId

مرّر cardNumber وatmId لعمليات ATM

لا تتجاوز dailyLimit

أرفق المراجع في documentReferences عند الحاجة

التزم بتنسيق التاريخ UTC‑ISO 8601

TenantTransactionATMWithdrawal

توثيق واجهة سحب عبر الصراف الآلي (ATM Withdrawal) – Genius Link#

جدول ملخص الEndpoints#

POST /TenantTransaction/Banking/Withdrawal/atm#

الوصف#

الرؤوس#

Body — InsertATMWithdrawalTransaction#

أمثلة طلب (مطابقة للمصدر)#

1) سحب عبر الصراف الآلي مع عمولة#

2) سحب بدون رسوم خدمة#

3) سحب برسوم خدمة محددة#

4) سحب كبير مع وثائق إضافية#

200 — TenantTransactionResult[] (نجاح)#

400 — CustomErrorResponse (أمثلة شائعة)#

401/403 — Unauthorized/Forbidden#

ممارسات موصى بها#

قائمة فحص سريعة#