مفاتيح API

أنشئ مفاتيح API منشورة وسرّية ومقيّدة، حدّد نطاقها بمحدّد الصلاحيات، وبدّلها لما تحتاج.

مفاتيح API هي الطريقة اللي بيتكلم بيها كودك مع XPay. لوحة التحكم بتدير نوعين: زوج ثابت من المفاتيح القياسية (منشور + سرّي) للوصول الكامل، وأي عدد من المفاتيح المقيّدة بنطاق صلاحيات مخصّص. وضع الاختبار والحساب الفعلي ليهم مفاتيح منفصلة، فالمفتاح بتاع وضع عمره ما هيشتغل في التاني.

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

اللي تقدر تعمله

استخدم الزوج القياسي

كل حساب عنده مفتاح منشور واحد (آمن للمتصفّح) ومفتاح سرّي واحد (للسيرفر بس) لكل وضع.

ضيّق النطاق بمفاتيح مقيّدة

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

بدّل المفاتيح وقت الحاجة

دوّر مفتاح متسرّب بضغطة واحدة. القيمة القديمة بتبطّل تشتغل على طول والقيمة الجديدة بتتنسخ على الحافظة.

بدّل بين الاختبار والفعلي بنظافة

وضع الاختبار والحساب الفعلي ليهم مفاتيح مستقلة. لوحة التحكم بتعرض المجموعة الصح على حسب مفتاح الوضع.

افتح صفحة مفاتيح API

اضغط المطورين في القائمة الجانبية للوحة التحكم. صفحة المطورين فيها تلات تبويبات: نظرة عامة، ومفاتيح API، وWebhooks. اختار مفاتيح API.

التبويب متقسّم لقسمين: المفاتيح القياسية فوق (دايمًا صفّين)، والمفاتيح المقيدة تحت (أي عدد، مع زرار إنشاء مفتاح مقيد على اليمين).

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

المفاتيح القياسية

كل تاجر عنده زوج ثابت من المفاتيح القياسية لكل وضع:

المفتاح	بيستخدم في إيه	تستخدمه فين
المفتاح المنشور	آمن للتضمين في كود المتصفّح. بيعرّف حسابك بس ما يقدرش يقرا أو يعدّل بيانات خاصة.	الـ JavaScript SDK بتاع XPay، ومكوّنات الدفع على الويب، وعملاء الموبايل.
المفتاح السرّي	وصول كامل للـ API من جهة السيرفر. عامله زي كلمة السر.	الـ backend بتاعك، ومهام السيرفر للسيرفر، والسكربتات.

المفتاحين القياسيين موجودين افتراضيًا. ما ينفعش يتحذفوا؛ ينفع يتبدّلوا (يتدوّروا) بس.

وصف لوحة التحكم على القسم بيقول: "مفتاح بيفتح وصول كامل للـ API، وبيتيح تفاعل واسع مع حسابك." ده بينطبق على المفتاح السرّي. المفتاح المنشور بيحمل نفس بادئة المعرّف بس من غير أي وصول كتابة أو قراءة للموارد الخاصة، فهو آمن للشحن للعميل.

المفاتيح المقيدة

المفاتيح المقيدة هي النمط المُوصى بيه لما تحب تحدّ من نطاق الضرر. كل مفتاح مقيّد عنده:

اسم بتظبّطه (من 3 لـ 255 حرف).
نطاق صلاحيات بتختاره لكل نوع مورد، بتلات مستويات: لا شيء، أو قراءة، أو كتابة. اختيار كتابة بيتضمّن قراءة تلقائيًا.

تقدر تنشئ أي عدد تحبه من المفاتيح المقيّدة. بيتسردوا تحت المفاتيح القياسية بشارة عدّاد صلاحيات؛ مرّر فوقها علشان تشوف أنهي موارد خدت وصول قراءة مقابل قراءة وكتابة.

أنماط شائعة:

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

أنشئ مفتاح مقيّد

اضغط إنشاء مفتاح مقيد

في قسم المفاتيح المقيدة، اضغط إنشاء مفتاح مقيد فوق على اليمين. هيفتح لوح جانبي عنوانه إنشاء مفتاح API مقيد.

سمّي المفتاح

دخّل اسم المفتاح ما بين 3 و255 حرف. اختار حاجة بتسمّي الدمج أو حالة الاستخدام ("تحليلات"، "موقع Webflow"، "تنظيف المتعاقد"). الاسم بيظهر في لوحة التحكم بس عمره ما بيظهر في الـ API ولا للعملاء.

اختار الصلاحيات

محدّد الصلاحيات عبارة عن جدول من عمودين. العمود الشمال بيسرد أنواع الموارد اللي تقدر تحدّد نطاق المفتاح عليها؛ والعمود اليمين فيه مفتاح لا شيء / قراءة / كتابة لكل صف.

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

الكتابة بتتضمّن القراءة لنفس نوع المورد. اختيار كتابة بيبعت للـ API قدرتي القراءة والكتابة، فمش محتاج تظبّط الاتنين يدويًا.

لازم تكون فيه صلاحية واحدة على الأقل متظبّطة (قراءة أو كتابة على صف واحد على الأقل)، وإلا المفتاح ما يقدرش يتعمل.

اضغط إنشاء المفتاح

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

احفظ القيمة في مكان آمن. XPay هتوريك البادئة بس على لوحة التحكم من النقطة دي وبعدها؛ القيمة الكاملة عمرها ما هتتعرض تاني. علشان ترجّع قيمة مفتاح شغّالة، اضغط على صف المفتاح علشان تكشفها (شوف تحت).

اقرا مفتاح

عمود الرمز بيوريك بادئة كل مفتاح متبوعة بـ ••••••••. اضغط أي صف علشان تكشف القيمة الكاملة:

المفاتيح المنشورة بتتكشف وتتنسخ على طول لما تضغط. هي آمنة للكشف.
المفاتيح السرّية والمقيّدة بتحتاج تأكيد بخطوتين في الحساب الفعلي قبل ما القيمة تتكشف وتتنسخ. في وضع الاختبار، الضغط بيكشف على طول.

بمجرد ما تتكشف، القيمة بتفضل ظاهرة على الصف ده لحد ما تخرج من الصفحة. وبيظهر إشعار "تم النسخ للحافظة" بيأكّد النسخ كل مرة تضغط فيها.

بدّل مفتاح

تبديل المفتاح بيبطّل القيمة القديمة وبيعمل قيمة جديدة مكانها. استخدم التبديل لما:

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

افتح قائمة الإجراءات على أي مفتاح (أيقونة ⋯ على يمين الصف) واختار تجديد المفتاح. هيظهر صندوق تأكيد بيشرح التدوير. بعد التأكيد:

القيمة القديمة بتبطّل تشتغل على طول. أي كود لسه بيستخدمها بياخد خطأ مصادقة.
بتتولّد قيمة جديدة وبتتنسخ على الحافظة تلقائيًا.
المفتاح بيحتفظ بإسمه (للمفاتيح المقيّدة) ونطاق صلاحياته.

التبديل بيشتغل على كل أنواع المفاتيح، بما فيها المفاتيح القياسية. خطّط للتدوير: حدّث كودك بالقيمة الجديدة قبل التبديل، أو كون مستعد لتوقّف الخدمة وإنت بتبدّل.

عدّل واحذف مفتاح مقيّد

المفاتيح القياسية ما ينفعش تتعدّل ولا تتحذف. المفاتيح المقيّدة بتحمل خيارين زيادة في قائمة الإجراءات:

تعديل المفتاح بيفتح لوح تعديل مفتاح API المقيد علشان تحدّث الاسم ونطاق الصلاحيات. الحفظ بيطبّق على طول؛ الطلبات الحالية اللي بتستخدم المفتاح بتكمّل بالنطاق الجديد.
حذف المفتاح بيفتح صندوق تأكيد. الحذف بيبطّل المفتاح نهائيًا. مفيش تراجع، وأي كود لسه بيستخدمه بياخد خطأ مصادقة في الطلب اللي بعده.

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

وضع الاختبار مقابل الحساب الفعلي

المفاتيح اللي بتشوفها بتعتمد على مفتاح الوضع:

في وضع الاختبار، لوحة التحكم بتوريك مفاتيحك القياسية بتاعة وضع الاختبار وأي مفاتيح مقيّدة بتاعة وضع الاختبار عملتها. الطلبات لـ API وضع الاختبار بتشتغل بالمفاتيح دي بس.
في الحساب الفعلي، لوحة التحكم بتوريك مفاتيحك القياسية بتاعة الحساب الفعلي وأي مفاتيح مقيّدة بتاعة الحساب الفعلي. طلبات API الحساب الفعلي بتشتغل بالمفاتيح دي بس.

مفتاح وضع الاختبار عمره ما هيشتغل مع API الحساب الفعلي والعكس. المفاتيح المقيّدة بتعيش في وضع واحد في المرة؛ اعمل مفتاح مقيّد منفصل لكل وضع محتاجه.

خطوة الكشف بخطوتين بتتفرض في الحساب الفعلي بس. وضع الاختبار بيكشف على طول علشان تقدر تاخد المفاتيح من غير احتكاك أثناء التطوير.