ما الذي تولّده مايندلاب لـ Stripe
عندما تتضمّن مطالبتك متطلّب فوترة، تنتج مايندلاب تكامل Stripe كاملًا جاهزًا للإنتاج بدلًا من نموذج أوّلي. يتضمّن الكود المُولَّد:
1
نقطة نهاية جلسة الدفع
مسار FastAPI ينشئ جلسة Stripe Checkout ويعيد الرابط المُستضاف. تعيد الواجهة الأمامية توجيه المستخدمين إليه عند الشراء.
2
معالج Webhook
نقطة نهاية webhook موثّقة تستمع لأحداث Stripe (checkout.session.completed، customer.subscription.updated، invoice.payment_failed، إلخ) وتحدّث قاعدة البيانات وفقًا لذلك.
3
حالة الاشتراك في قاعدة البيانات
جدول اشتراكات (أو عمود على جدول المستخدمين) يخزّن الخطة والحالة ومعرّف عميل Stripe — حتى يتمكّن تطبيقك من حصر الميزات دون استدعاء واجهة Stripe API في كل طلب.
4
إعادة توجيه بوابة الفوترة
نقطة نهاية تنشئ جلسة Stripe Billing Portal حتى يتمكّن المستخدمون من إدارة اشتراكهم، أو تحديث تفاصيل الدفع، أو الإلغاء — دون أن تبني تلك الواجهة بنفسك.
5
صفحة الخطط في الواجهة الأمامية
صفحة React تسرد كل خطة مع سعرها وأبرز ميزاتها، إضافةً إلى زرّ دفع لكل فئة.
كتابة المطالبة
كلما كانت مطالبتك أكثر تحديدًا، كان التكامل المُولَّد أفضل. اذكر أسماء الخطط، والأسعار، وفترات الفوترة، وأيّ قواعد لحصر الميزات:
text
Add Stripe billing with a $29/mo Pro plan and a $99/mo Business plan.
Users on the free tier see an upgrade banner on any page that requires a paid
feature. Pro users get unlimited projects and API access. Business users also
get SSO, audit logs, and a dedicated support email. Cancelled subscriptions
should immediately downgrade the user to the free tier.
يمكنك أيضًا طلب تسعير سنوي، أو فترات تجريبية، أو تسعير لكل مقعد، أو فوترة قائمة على الاستخدام — صِف النموذج بلغة مبسّطة وستترجمه مايندلاب إلى تهيئة منتج وسعر Stripe المناسبة.
الملفات المُولَّدة
يمتدّ تكامل Stripe عبر ثلاثة ملفات رئيسية:
text
backend/
└── api/
└── routes/
└── billing.py # Checkout, webhook, portal endpoints
frontend/
└── src/
└── pages/
└── Billing.tsx # Plans page + upgrade bannersيتحقّق معالج webhook من توقيع Stripe باستخدام STRIPE_WEBHOOK_SECRET قبل معالجة أيّ حدث. يمنع هذا هجمات إعادة التشغيل والأحداث المنتحَلة. يُضاف السرّ تلقائيًا إلى قائمة متغيرات بيئة مشروعك.
إعداد متغيرات بيئة Stripe
بعد التوليد، أضف متغيرات البيئة التالية في إعدادات المشروع › متغيرات البيئة:
bash
STRIPE_SECRET_KEY=sk_test_... # Your Stripe secret key
STRIPE_WEBHOOK_SECRET=whsec_... # From the Stripe dashboard webhook endpoint
STRIPE_PRO_PRICE_ID=price_... # Stripe Price ID for the Pro plan
STRIPE_BIZ_PRICE_ID=price_... # Stripe Price ID for the Business plan
⚠انتبه.لا تكتب مفاتيح Stripe مباشرةً في شيفرتك المصدرية أبدًا. استخدم متغيرات البيئة دائمًا. المفاتيح التي تُودَع في نظام التحكّم بالمصدر يجب اعتبارها مكشوفة وتدويرها فورًا عبر لوحة تحكّم Stripe.
للعثور على معرّفات الأسعار (Price IDs)، انتقل إلى لوحة تحكّم Stripe › Products، وافتح كل خطة، وانسخ معرّف السعر من قسم التسعير. لكل سعر معرّفه الخاص (مثل price_1ABC...).
الاختبار باستخدام وضع اختبار Stripe
استخدم مفاتيح وضع الاختبار (sk_test_...) أثناء التطوير. يوفّر Stripe أرقام بطاقات اختبارية تُطلِق سيناريوهات محدّدة:
text
4242 4242 4242 4242 — successful payment
4000 0000 0000 9995 — card declined (insufficient funds)
4000 0025 0000 3155 — requires 3D Secure authentication
استخدم أيّ تاريخ انتهاء مستقبلي وأيّ رمز CVC من ٣ أرقام. لاختبار تسليم webhook محليًا، ثبّت Stripe CLI وشغّل:
bash
stripe listen --forward-to localhost:8000/api/billing/webhook
تطبع واجهة CLI سرّ توقيع webhook (whsec_...) — استخدمه بصفته STRIPE_WEBHOOK_SECRET للاختبار المحلي.
الانتقال إلى الوضع المباشر
1
التبديل إلى المفاتيح المباشرة
في لوحة تحكّم Stripe، بدّل من وضع الاختبار (Test) إلى الوضع المباشر (Live) وانسخ مفتاحك السرّي المباشر. حدّث STRIPE_SECRET_KEY في متغيرات بيئة مايندلاب.
2
إنشاء منتجات وأسعار مباشرة
المنتجات والأسعار التي أُنشئت في وضع الاختبار لا تُنقَل إلى الوضع المباشر. أعد إنشاءها في لوحة تحكّم Stripe ضمن الوضع المباشر وحدّث STRIPE_PRO_PRICE_ID وSTRIPE_BIZ_PRICE_ID.
3
تسجيل رابط webhook الإنتاجي
في لوحة تحكّم Stripe، انتقل إلى Developers › Webhooks وأضف رابط الواجهة الخلفية الإنتاجي (مثل https://your-app.myndlab.app/api/billing/webhook). انسخ سرّ التوقيع وحدّث STRIPE_WEBHOOK_SECRET.
4
اختبار دفعة حقيقية
نفّذ عملية شراء حقيقية صغيرة للتأكّد من أن التدفّق من البداية إلى النهاية يعمل قبل الإعلان عن إطلاقك.