أنماط بناء SDK

عميل مركزي

أنشئ Client واحدًا مسؤولًا عن Base URL وAuthorization وRequest ID والمهلات وتحليل الأخطاء. لا تنفذ fetch أو cURL بشكل متكرر في كل شاشة. يولد المرجع أمثلة بأربع لغات، لكنها أمثلة لبناء مكتبتك وليست SDK رسميًا منشورًا بعد.

أنواع البيانات

ولّد Types من OpenAPI أو عرّفها مركزيًا. تعامل مع بعض الحقول كـnullable، وتجاهل الخصائص الإضافية. استخدم Decimal مناسبًا أو وحدات صغرى إذا اتفقت مع LuxPay، ولا تعتمد على Float في محاسبة نظامك حتى لو نقل JSON رقمًا عشريًا.

Middleware العميل

أضف ترويسة Request ID تلقائيًا، وAuthorization من مزود أسرار، وIdempotency-Key للعمليات التي تحتاجها. طبق Retry policy بحسب الطريقة والحالة، ولا تعد POST ماليًا إلا إذا كان مفتاح منع التكرار مثبتًا.

النتيجة الموحدة

حوّل أخطاء النقل وHTTP والتحقق إلى نوع نتيجة واضح يحتوي status وcode وrequestId وretryable. احتفظ بجسم الاستجابة المنقح للتشخيص، ولا تسجل Secret أو بيانات شخصية.

الاختبارات

استخدم Mock Server مشتقًا من OpenAPI لاختبارات الواجهة، ثم Contract Tests ضد Sandbox. اختبر حقلًا إضافيًا غير معروف، وEnvelope بنمط status وآخر بنمط success، وTimeout بعد إرسال العملية، واستجابة Duplicate ناجحة. راجع الأخطاء ومنع التكرار.