شرح مفاتيح Stripe API: مفاتيح الاختبار مقابل المباشرة، والمفتاح العام مقابل السري، والمفاتيح المقيدة

كل تكامل مع Stripe يبدأ بالسؤال نفسه: أي مفتاح يُوضع وأين؟ يمنحك Stripe مفتاحًا قابلًا للنشر (publishable key)، ومفتاحًا سريًا (secret key)، وخيار إنشاء مفاتيح مقيّدة (restricted keys)، وكل منها بنسختين: اختبارية وحقيقية. ضع المفتاح الخطأ في المكان الخطأ، وستُسرّب إما القدرة على تحريك الأموال أو تُهدر بعد الظهر في تتبع خطأ 401. يغطي هذا الدليل ما يفعله كل مفتاح من مفاتيح Stripe API، وأين يوجد، وكيف ترسل أول طلب في وضع الاختبار، وكيف تُبقي المفتاح الحقيقي بعيدًا عن أي شيء مشترك. للمفهوم العام أولًا، ابدأ بـما هو مفتاح API. كل ما يلي يستند إلى توثيق مفاتيح API من Stripe، الذي تم التحقق منه في سبتمبر 2026.

أين توجد مفاتيح Stripe API في لوحة التحكم

افتح صفحة مفاتيح API على dashboard.stripe.com/apikeys. تقع ضمن Developers في لوحة التحكم وتُظهر المفاتيح الخاصة بأي حساب أو بيئة اختبار (sandbox) تعرضه. يوجد مفتاح تبديل بين وضع الاختبار والوضع الحقيقي، وتتغير قائمة المفاتيح معه.

تحتوي الصفحة على قائمتين:

• المفاتيح القياسية تضمّ المفتاح القابل للنشر والمفتاح السري.
• المفاتيح المقيّدة تضمّ أي مفاتيح أنشأتها بأذونات محدودة.

تختلف الرؤية حسب الوضع. في بيئة الاختبار يمكنك كشف كل مفتاح في أي وقت. أما في الوضع الحقيقي، فالمفتاح السري الذي تُنشئه بنفسك يُعرض مرة واحدة فقط عند الإنشاء. انسخه إلى خزنتك قبل إغلاق النافذة؛ ففقدانه يعني تدويره. أما المفاتيح الافتراضية التي أنشأها Stripe فيمكن كشفها مجددًا في الوضع الحقيقي.

شيء واحد لن تعرضه الصفحة: أسرار توقيع الـ webhook. تلك توجد ضمن Webhooks، لكل نقطة نهاية (endpoint)، وليست مفاتيح API على الإطلاق.

المفاتيح القابلة للنشر مقابل المفاتيح السرية

الأسماء تصف حدود الثقة.

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

المفتاح السري مكانه خادمك ولا مكان آخر. لقد تغيّر توجيه Stripe: تقول التوثيق الآن إنها "لا توصي باستخدام المفاتيح السرية لحالات استخدام جديدة" وتشير بدلًا من ذلك إلى المفاتيح المقيّدة. لا يزال المفتاح السري غير المقيّد يعمل، لكن تعامل معه كخيار للطوارئ، لا كخيار افتراضي.

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

يشغّل Stripe عالمين منفصلين، لكل منهما مجموعة مفاتيح خاصة. مفاتيح الاختبار (تسمّي التوثيق الأحدث جانب الاختبار بيئة اختبار sandbox، رغم أن البادئات لا تزال تقول _test_) تُرجع كائنات محاكاة: عملاء وهميون، وPaymentIntents وهمية، وبطاقات اختبار تنجح أو تفشل بحسب الطلب، دون أموال حقيقية. أما المفاتيح الحقيقية فتصل إلى شبكات البطاقات وتحرّك أموالًا فعلية.

الفصل صارم. العميل المُنشأ بـsk_test_ لا وجود له بالنسبة إلى sk_live_، والعكس صحيح. رمز خطأ Stripe عند خلط الوضعين، livemode_mismatch، يقولها بوضوح: "مفاتيح API والطلبات والكائنات في وضع الاختبار والوضع الحقيقي متاحة فقط ضمن الوضع المطابق."

تتبع ذلك قاعدتان عمليتان:

• ابنِ واختبر بالكامل باستخدام sk_test_ أو rk_test_. توصي Stripe ببيئة اختبار عامة منفصلة للتكاملات الجديدة حتى تبقى إعداداتها وبياناتها معزولة.
• الانتقال إلى الوضع الحقيقي تغيير في التهيئة، لا في الكود. يقرأ خادمك المفتاح من متغير بيئة أو خزنة، والانتقال إلى الوضع الحقيقي يعني تغيير تلك القيمة.

كل استجابة من API تتضمن قيمة منطقية livemode. تحقق منها في اختباراتك؛ فهي أرخص حماية ضد نشر مفتاح خاطئ.

المفاتيح المقيّدة ومبدأ الحد الأدنى من الصلاحيات

مفتاح API المقيّد (يختصره Stripe بـ RAK) هو مفتاح سري بقناع أذونات. عند إنشاء واحد، تختار إذنًا لكل مجموعة موارد: None أو Read أو Write. كل شيء افتراضيًا None. تتضمن Write إذن Read، والتعيين إلى HTTP بسيط: GET يحتاج Read، وPOST وDELETE يحتاجان Write.

لإنشاء واحد، اضغط Create restricted key في صفحة مفاتيح API، واختر مجموعة أذونات مُعدّة مسبقًا أو ابدأ من الصفر، وسمّه، واضبط الأذونات، وأكمل طلب التحقق بخطوتين. وكما هو الحال مع مفتاح سري تُنشئه بنفسك في الوضع الحقيقي، ترى القيمة مرة واحدة.

يقترح دليل المفاتيح المقيّدة مفتاحًا واحدًا لكل خدمة: خدمة الفوترة تحصل على Write على Invoices وCustomers، ومهمة التقارير تحصل على Read على Charges وDisputes. إذا اختُرقت خدمة واحدة، يُحصر المهاجم في أذونات ذلك المفتاح. مفتاح خلافات للقراءة فقط لا يمكنه إنشاء عملية دفع أو المساس بالمدفوعات الصادرة.

امنح مفتاحًا جديدًا أذونات واسعة في بيئة اختبار، وشغّل مجموعة اختباراتك، ثم افتح سجلات طلبات المفتاح (قائمة overflow، View request logs) واستبعد كل إذن لم يشهد أي حركة. تتيح لك Stripe أيضًا وسم المفاتيح المخصصة لوكلاء الذكاء الاصطناعي المستقلين بحيث تخضع لقواعد الموافقة على المدفوعات الصادرة والاستردادات؛ استخدم هذا المسار بدلًا من مفتاح سري عادي.

طلبك الأول باستخدام curl وPython

تتم المصادقة في Stripe عبر HTTP Basic Auth: المفتاح هو اسم المستخدم وكلمة المرور فارغة. النقطتان المتتاليتان تخبران curl بعدم طلب إدخالهما:

export STRIPE_API_KEY=sk_test_...   # your sandbox secret key

curl https://api.stripe.com/v1/payment_intents \
  -u "$STRIPE_API_KEY:" \
  -d amount=2000 \
  -d currency=usd \
  -d "automatic_payment_methods[enabled]=true"

الاستجابة هي PaymentIntent بمعرّف id يبدأ بـpi_، وstatus: "requires_payment_method"، وlivemode: false. يؤكد هذا الحقل الأخير أنك استخدمت مفتاح اختبار.

تقبل Stripe أيضًا -H "Authorization: Bearer $STRIPE_API_KEY"، وهو النموذج الذي يستخدمه Apidog ومعظم عملاء HTTP. كلاهما يحمل المفتاح نفسه؛ وإذا لم تكن متأكدًا من أي نمط يناسب منظومتك، فتغطي مقارنتنا بين مفاتيح API ورموز bearer المقايضات. يجب أن تمر الطلبات عبر HTTPS؛ فـ HTTP العادي يفشل تمامًا، وفقًا لـمرجع المصادقة.

في Python، نمط SDK الحالي هو StripeClient الذي يقرأ المفتاح من البيئة:

import os
import stripe

client = stripe.StripeClient(os.environ["STRIPE_API_KEY"])

intent = client.v1.payment_intents.create({
    "amount": 2000,
    "currency": "usd",
    "automatic_payment_methods": {"enabled": True},
})
print(intent.id, intent.livemode)  # pi_..., False

لا يظهر أي نص مفتاح في الملف. الكود نفسه يعمل ضد وضع الاختبار أو الوضع الحقيقي حسب ما توفره البيئة.

دع وكيل البرمجة لديك يختبر مفتاح Stripe باستخدام Apidog CLI

يثبت curl أن المفتاح يعمل مرة واحدة. يمكن لوكيل البرمجة لديك تحويله إلى فحص قابل للتكرار عبر Apidog CLI وإبقاء المفتاح بعيدًا عن المشروع المشترك. أعدّ ذلك مرة واحدة (الرمز موجود ضمن Account Settings، API Access Token):

npm install -g apidog-cli@latest
apidog login --with-token <YOUR_TOKEN>
npx -y skills add https://apidog.com   # pick your agent when prompted

ثم أعطِ الوكيل طلبًا واحدًا:

Use Apidog CLI on project <id>. Create a "Stripe Test" environment with base URL
https://api.stripe.com. Add POST /v1/payment_intents with Bearer auth from
{{stripe_secret_key}} and a form-urlencoded body: amount=2000, currency=usd.
Create a test case asserting status 200, an id starting with pi_ and
livemode false, then run it and summarize any failures.

الأوامر التي ينفّذها، تم التحقق منها مقابل Apidog CLI 2.2.7:

apidog environment create "Stripe Test" --project <id> --base-url https://api.stripe.com
apidog cli-schema get endpoint-create
apidog endpoint create --project <id> --file payment-intents.json
apidog cli-schema validate test-case-create --file pi-case.json
apidog test-case create --project <id> --file pi-case.json
apidog run --test-case <caseId> --project <id> -e <envId> \
  --env-var "stripe_secret_key=$STRIPE_API_KEY" -r cli,json

يذكر الطلب ترميز النموذج (form encoding) لأن نقاط نهاية v1 في Stripe لا تقبل JSON. وفحص livemode هو فخّك الآمن: إذا شغّل أحدهم الحالة بمفتاح حقيقي، فشل قبل إرسال طلب ثانٍ. في CI، سطر apidog run نفسه يقرأ المفتاح من مخزن أسرار خط أنابيبك؛ ودليلنا حول خط أنابيب CI/CD من Apidog CLI يحتوي على نسخة جاهزة للنسخ. تعريف الطلب مشترك؛ أما بيانات الاعتماد الحقيقية فلا.

تدوير المفاتيح وما يجب فعله إذا تسرّب أحدها

يُصرّ دليل التعامل مع المفاتيح من Stripe نفسه بوضوح: افترض أن أي شيء أُودع في مستودع، أو لُصق في محادثة، أو طُبع في سجل، قد اختُرِق، حتى لو لم تكن متأكدًا من أن أحدًا رآه.

التدوير مدمج في لوحة التحكم. من قائمة overflow الخاصة بالمفتاح اختر Rotate key، واضبط انتهاء صلاحية للمفتاح القديم، وانسخ البديل. يعمل كلاهما خلال فترة السماح، التي تصل إلى 7 أيام، حتى تتمكن من النشر تدريجيًا ومراقبة سجلات الطلبات لاكتشاف أي متخلفين. أما Now فيُلغي المفتاح القديم فورًا.

إذا تسرّب مفتاح سري أو مقيّد:

• دوّره فورًا بانتهاء صلاحية قصير.
• حدّث كل خادم كان يستخدمه، وأكّد الحركة في سجلات الطلبات، ثم اترك المفتاح القديم ينتهي.
• راجع النشاط الأخير في Workbench بحثًا عن أي شيء لن يفعله تكاملك: حسابات متصلة غير معروفة، أو مدفوعات صادرة لم تبدأها، أو حسابات بنكية جديدة.
• أوقف المدفوعات الصادرة المشبوهة مؤقتًا، واعكس أي منها أُرسل بالفعل، واسترد الرسوم الاحتيالية بسرعة لتفادي النزاعات.
• دوّر مفاتيحك الأخرى أيضًا. إذا تسرّب أحدها، افترض أن القناة التي سرّبته رأت أكثر من ذلك.

تفحص Stripe المفاتيح المكشوفة وستُعلمك، وأحيانًا تعطّل المفتاح بشكل استباقي، لكن الكشف غير مضمون. البحث في مستودعاتك وتهيئة CI عن sk_live_ وrk_live_ هو تدقيق يستغرق خمس دقائق، ووجود ماسح للأسرار في خطاف ما قبل الإيداع (pre-commit hook) يوقف وصول التالي. لا تطلب Stripe مفتاحك السري أبدًا، لذا أي رسالة تطلبه هي تصيّد احتيالي.

أخطاء مفاتيح Stripe API الشائعة

تتوافق حالتا 401 و403 مع stripe.AuthenticationError وstripe.PermissionError في Python SDK، وفقًا لـمرجع الأخطاء، لذا يمكنك التقاطهما بشكل محدد. وهناك حالة أقل وضوحًا: المفتاح الحقيقي الذي لم يُنشئ تحويلات أو مدفوعات صادرة لمدة 180 يومًا يُقيّد في تلك الإجراءات، مع خيار Restore access على المفتاح.

الأسئلة الشائعة

هل من الآمن وضع مفتاح Stripe القابل للنشر في كود الواجهة الأمامية؟

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

هل يمكنني استخدام مفتاح مقيّد في وضع الاختبار؟

نعم. توجد المفاتيح المقيّدة في كلا الوضعين (rk_test_ وrk_live_). توصي Stripe بضبط نسخة الاختبار أولًا، ثم إنشاء مفتاح حقيقي بأذونات مطابقة.

هل سر توقيع الـ webhook هو نفسه مفتاح API الخاص بي؟

لا. تُصدَر أسرار التوقيع لكل نقطة نهاية webhook وتتحقق فقط من أن حدثًا واردًا جاء من Stripe. توجد ضمن Webhooks، لا في صفحة مفاتيح API. وإذا كنت تُعدّها، فراجع كيفية اختبار Stripe webhooks في CI.

ماذا يحدث إذا استخدمت مفتاح اختبار في بيئة الإنتاج؟

تنجح الطلبات لكن لا تُخصم أي بطاقة ولا يتحرك أي مال. ولأن livemode يعود بـfalse على كل كائن، فإن التحقق من ذلك الحقل يلتقط الخطأ قبل أن يلتقطه العملاء.

الخلاصة المختصرة

المفاتيح القابلة للنشر مكانها العميل، والمفاتيح السرية والمقيّدة تبقى على الخادم، والاختبار والحقيقي لا يختلطان أبدًا، والمقيّد يتفوق على السري كلما استطعت تحديد نطاقه. أبقِ المفتاح الحقيقي في خزنة، ومرّر مفتاح الاختبار إلى Apidog CLI وقت التشغيل، وأبقِ فحص livemode في كل حالة اختبار يكتبها وكيلك.