كل المستندات

أفضل الممارسات

أفضل ممارسات التشغيل مع واجهة نيزا: حماية المفاتيح، ومنع تكرار الطلبات، والبدء بالمراجعة قبل تفعيل الحظر على العملاء.

تنزيل Markdown
الأدلةمرجع APIأمثلة الكودأفضل الممارسات

أفضل ممارسات الإنتاج

إرشادات لتكامل آمن وموثوق مع نيزا في بيئات الإنتاج.

الأمان

  • لا تكشف مفاتيح API السرية داخل المتصفح أو تطبيقات الجوال.
  • استخدم رموز Web SDK قصيرة الصلاحية لتكاملات المتصفح.
  • غيّر المفاتيح بشكل دوري، وفورًا عند أي اشتباه بتسرّبها.
  • شفّر signingSecret الخاص بـWebhooks وقيّد الوصول إليه كما تفعل مع كلمة المرور.

سلامة الطلبات

  • استخدم HTTPS دائمًا في الإنتاج، وتحقق من الشهادة واسم المضيف.
  • حدد مهلة (timeout) واضحة لكل طلب صادر.
  • تحقق من بنية الاستجابة وقيمة القرار قبل تنفيذ أي إجراء داخل منتجك.
  • حدد لكل مسار ما يحدث عند تعذّر الوصول إلى الخدمة: السماح بالمتابعة (fail-open) أو الإيقاف (fail-closed)، حسب مستوى المخاطر.

حدود عدد الطلبات والحصص

  • التزم بالحالة 429 وبقيمة Retry-After، ولا تُعِد المحاولة فورًا.
  • راقب X-Quota-Limit وX-Quota-Remaining عندما تكونان متاحتين.
  • استخدم Webhooks للنتائج غير المتزامنة بدلًا من الاستعلام المتكرر على فترات متقاربة (polling).
  • فعّل تنبيهًا قبل نفاد الحصة لتتمكن من تخفيف الحمل دون توقف مفاجئ.

الأخطاء وإعادة المحاولة

  • لا تُعِد المحاولة عند أخطاء 4xx؛ صحّح المفتاح أو الطلب أولًا.
  • أعد المحاولة فقط عند 429 و5xx، بتأخير متزايد (exponential backoff) مع تفاوت عشوائي (jitter) وحد أقصى للمحاولات.
  • أرسل ترويسة Idempotency-Key مع طلبات feedback لمنع تكرار تنفيذها عند إعادة المحاولة.
  • انقل الطلبات التي فشلت نهائيًا إلى طابور الرسائل الفاشلة (dead-letter queue) أو إلى مسار مراجعة واضح.

المراقبة

  • مرّر x-request-id أو x-correlation-id من بوابة تطبيقك (gateway) عند توفرها.
  • احفظ correlationIds من استجابة القرار مع سجلات المنتج.
  • راقب أي ارتفاع في 401 و 429 و 5xx.
  • راجع معدلات REVIEW و BLOCK قبل توسيع الإطلاق ليشمل حركة أكبر.

تقليل البيانات

  • أرسل فقط الحقول اللازمة لاتخاذ قرار الاحتيال أو فحص AML.
  • لا ترسل PAN كاملًا أو CVV أو وثائق حكومية دون أساس تعاقدي وقانوني واضح.
  • استخدم معرّفات خارجية لا تكشف هوية العميل بدلًا من وضع بيانات شخصية في sessionId أو في حقول المرجع.
  • حدد مدة الاحتفاظ بالسجلات (logs) وبيانات الطلبات وصلاحيات الوصول إليها بما يتوافق مع سياسة منشأتك.

الإطلاق

  • ابدأ بوضع المراقبة (shadow mode) في مسار واحد قبل التطبيق الفعلي.
  • وسّع الإطلاق تدريجيًا حسب نسبة من حركة المستخدمين أو حسب المنطقة.
  • جهّز طريقة واضحة للتراجع (rollback) عبر feature flags أو قواعد التوجيه.

تحتاج مساعدة؟

يساعدك فريق نيزا في اختيار طريقة التكامل، وإعداد قواعد الإطلاق، وربط Webhooks.

تواصل مع الدعم