Skip to main content
يرسل كل استدعاء المفتاح في الترويسة Authorization:
يتكون المفتاح من sk_ ثم 8 أحرف ثم شرطة سفلية ثم 64 حرفًا. تخزّن Sahl بصمة SHA-256 للمفتاح فقط، مع بادئة (sk_a1b2c3d4) لقائمة وحدة التحكم. يُعرض السر مرة واحدة عند إنشاء المفتاح أو تبديله، ولا يستطيع أي شخص في Sahl استرجاعه.

​
إنشاء مفتاح

  1. سجّل الدخول إلى وحدة التحكم عبر app.sahlfinancial.com بصفة مدير مساحة العمل أو مدير API، ببريد إلكتروني موثّق.
  2. Settings، ثم API Keys، ثم New key.
  3. امنحه اسمًا، مثل production-backend أو sandbox-test.
  4. حدّد النطاقات. لا تُعرض إلا النطاقات التي يجوز لمساحة عملك امتلاكها.
  5. اربطه اختياريًا بحساب خدمة Google (انظر أدناه).
  6. Create API Key. انسخ السر من الشريط الظاهر. يُعرض مرة واحدة.
إذا ظهرت في النموذج عبارة “This workspace is not enabled for the partner KYC API, so its keys carry no scopes”، فـاطلب الوصول إلى بيئة الاختبار لتفعيل واجهة الشركاء في مساحة عملك (تُفعَّل لكل مساحة عمل من قِبل Sahl). وطلب إنشاء مفتاح بنطاق kyc: في مساحة عمل غير مفعّلة يُرجع 403 kyc_scope_not_allowed. لا يوجد مفتاح منفصل لبيئة الاختبار وآخر للإنتاج. يعمل مفتاح واحد في البيئتين، والحقل environment في كل استدعاء هو الذي يحدد البيئة. إذا أردت مفاتيح مختلفة لأنظمة مختلفة، فسمِّها وحدد نطاقاتها على هذا الأساس.

​
النطاقات

  • هذه النطاقات الثلاثة هي الوحيدة. يُرفض أي نطاق خارج القائمة عند إنشاء المفتاح.
  • لا يحمل المفتاح إلا النطاقات التي صدر بها، لذا لا يمكن استخدام مفتاح تسرّب لغرض ما في غرض آخر.
  • يتطلب كل استدعاء kyc: أيضًا أن تكون مساحة العمل مفعّلة لواجهة الشركاء. والمفتاح الذي يحمل النطاق في مساحة عمل غير مفعّلة يحصل على 403 kyc_scope_not_allowed.
  • امنح كل نظام الحد الأدنى مما يحتاج إليه. الخادم الذي يتحقق من الملفات فقط يحتاج إلى kyc:verify وليس kyc:extract، وهو النطاق الذي يستهلك القراءات.

​
تبديل مفتاح

يُصدر التبديل مفتاحًا جديدًا ويُبقي القديم صالحًا خلال فترة سماح، فتتمكن من النشر دون انقطاع.
  1. Settings, API Keys، ابحث عن المفتاح، ثم انقر Rotate.
  2. اختر المدة التي يبقى فيها المفتاح القديم صالحًا: بلا مدة، أو ساعة واحدة، أو 24 ساعة، أو 3 أيام، أو 7 أيام. تقبل واجهة البرمجة من 0 إلى 168 ساعة، والافتراضي 24.
  3. انسخ السر الجديد وانشره.
  4. عند انتهاء فترة السماح يُرجع المفتاح القديم 401 API key expired.
ما تضمنه الشيفرة:
  • للمفتاح الجديد الاسم والنطاقات وحساب الخدمة المرتبط نفسها للمفتاح القديم. لا يمكن للتبديل توسيع الصلاحيات ولا تضييقها.
  • تبديل مفتاح ما زال في فترة السماح يُرجع 409 key_already_rotated، فلا يؤدي تكرار الطلب إلى وجود عدة مفاتيح فعالة. استخدم المفتاح البديل، أو أنشئ مفتاحًا جديدًا.
  • التبديل منحٌ جديد للنطاقات. ولا تستطيع مساحة عمل خرجت من قائمة الشركاء المسموح لهم إصدار مفاتيح kyc: جديدة عبر التبديل.
  • تعرض قائمة المفاتيح “Grace” مع وقت الانتهاء للمفتاح الذي في فترة السماح.

​
إبطال مفتاح

انقر Revoke في قائمة المفاتيح. يُرجع المفتاح المبطَل 401 Invalid or revoked API key ابتداءً من الاستدعاء التالي. أبطِل أي مفتاح يُحتمل أنه تسرّب، ثم أنشئ مفتاحًا جديدًا. والتبديل بدون فترة سماح يؤدي الغرض نفسه في خطوة واحدة ويمنحك بديلًا.

​
ربط مفتاح بحساب خدمة

إذا كانت خوادمك تعمل على Google Cloud، يمكنك ربط المفتاح بحساب خدمة Google الذي تعمل به. عندئذٍ يجب أن يحمل كل استدعاء رمز هوية موقّعًا من Google لذلك الحساب في X-Partner-Identity، صادرًا للجمهور (audience) الظاهر في نموذج المفتاح. وبذلك لا يفيد المفتاح المسرَّب وحده. لا تستطيع ساحة تجربة API (playground) إرسال هذه الترويسة، فلا تربط مفتاحًا تريد تجربته فيها.

​
الأخطاء

عالج نقص النطاق بإنشاء مفتاح يحمله. يجري فحص النطاق قبل فحص مساحة العمل، لذا يحصل المفتاح الذي لا يحمل النطاق على الصيغة النصية حتى لو كانت مساحة العمل غير مفعّلة.

​
حماية المفاتيح

  • استدعِ واجهة البرمجة من خادمك فقط. لا تضع مفتاحًا أبدًا في متصفح أو تطبيق جوال أو مستودع شيفرة.
  • احتفظ به في مدير أسرار أو في متغير بيئة مثل SAHL_API_KEY.
  • مفتاح واحد لكل نظام، لتتمكن من إبطال أحدها دون إيقاف البقية.
  • راقب Developers, Call log في وحدة التحكم: تُعرض فيه استدعاءات كل مفتاح وحالتها وزمن استجابتها، وتُظهر قائمة المفاتيح وقت آخر استدعاء لكل مفتاح.
  • ترسل ساحة تجربة الوثائق الطلب من متصفحك مباشرة إلى واجهة Sahl. لا يمرّره هذا الموقع عبر وسيط ولا يخزّن مفتاحك. ومع ذلك الصق مفتاحًا أُنشئ للاختبار، وأبطله عند الانتهاء.