GitHub Repository
الشيفرة المصدرية لـ FastAPI وDodo Payments boilerplate.
نظرة عامة
FastAPI boilerplate هو backend مكتوب بلغة Python مع اتصال Dodo Payments مُعد مسبقًا. يحتوي على endpoints تنشئ checkout sessions وCustomer Portal sessions، وwebhook endpoint يتحقق من التواقيع، وصفحة تسعير معروضة من قوالب Jinja2.يستخدم هذا boilerplate FastAPI مع معالجات المسارات
async، وPydantic للتحقق والإعدادات، وPython SDK dodopayments. تستدعي المعالجات العميل المتزامن DodoPayments. لتجنب حظر event loop، بدّل إلى AsyncDodoPayments واستخدم await لاستدعاءاته.الميزات
يتضمن boilerplate ما يلي:- إعداد سريع: انتقل من الاستنساخ إلى خادم قيد التشغيل خلال نحو خمس دقائق.
- معالجات Async: معالجات المسارات هي دوال FastAPI
async def. - Checkout Sessions: checkout endpoint مُعد مسبقًا ويستخدم Python SDK.
- معالجة Webhook: webhook endpoint يتحقق من كل توقيع باستخدام طريقة SDK
unwrap. - Customer Portal: endpoint ينشئ Customer Portal sessions.
- أمان الأنواع: تتحقق نماذج Pydantic من request bodies، وتستخدم الشيفرة type hints.
- إعداد البيئة: يحمّل
pydantic-settingsالإعدادات ويتحقق منها من.env.
المتطلبات الأساسية
قبل البدء، تحتاج إلى:- Python 3.9 أو إصدار أحدث، وهو ما يتطلبه SDK
dodopayments. يوصى باستخدام Python 3.11 أو إصدار أحدث. - pip أو uv لإدارة الحزم.
- حساب Dodo Payments لإنشاء API key وwebhook signing secret في لوحة التحكم.
البدء السريع
1
Clone the Repository
2
Create Virtual Environment
أنشئ بيئة Python معزولة:أو استخدم uv لإدارة التبعيات بسرعة أكبر:
3
Install Dependencies
4
Get API Credentials
سجّل حسابًا في Dodo Payments، ثم احصل على بيانات الاعتماد من لوحة التحكم:
- API Key: أنشئ مفتاحًا ضمن لوحة التحكم ← المطور ← مفاتيح API.
- Webhook Key: أضف endpoint ضمن لوحة التحكم ← المطور ← Webhooks، ثم انسخ signing secret الخاص به. يجب أن يكون عنوان URL للـ endpoint عامًا ويستخدم HTTPS. لاستقبال الأحداث على جهازك، راجع اختبار Webhooks محليًا.
5
Configure Environment Variables
انسخ الملف النموذجي لإنشاء ملف عيّن القيم إلى بيانات اعتماد Dodo Payments الخاصة بك:المتغيرات الأربعة مطلوبة. يحمّل
.env في الدليل الجذر:.env
app/core/config.py هذه المتغيرات باستخدام pydantic-settings، ويفشل التطبيق في بدء التشغيل إذا كان أحدها مفقودًا أو فارغًا. DODO_PAYMENTS_RETURN_URL هو المكان الذي يرسل إليه checkout العميل بعد الدفع.6
Add Your Products
استبدل المنتجات النموذجية في
app/lib/products.py بمنتجاتك الخاصة. عيّن كل product_id إلى معرّف منتج ضمن المنتجات في لوحة التحكم. تعرض صفحة التسعير هذه المنتجات.7
Run the Development Server
يسرد Swagger UI endpoints
/api/checkout/ و/api/webhook/ و/api/customer-portal/، وهي جاهزة للاختبار.http://localhost:8000، صفحة التسعير.بنية المشروع
نقاط نهاية API
يُركّبapp/main.py كل موجّه تحت بادئة /api:
ينتهي كل مسار بشرطة مائلة. يستجيب FastAPI لطلب المسار من دون الشرطة المائلة بعملية إعادة توجيه
307، لذا استخدم المسار الدقيق، خاصةً في URL الخاص بـ webhook.
أمثلة على التعليمات البرمجية
هذه الأمثلة مختصرة من الملفات الموجودة فيapp/api/.
إنشاء جلسة Checkout
ينشئapp/api/checkout.py جلسة Checkout ويُرجع checkout_url الخاص بها. يتطلب نص الطلب product_id، وquantity اختياريًا، وكائن customer اختياريًا مع name وemail:
معالجة Webhooks
يتحققapp/api/webhook.py من التوقيع باستخدام طريقة unwrap في SDK، ثم يفرّع التنفيذ وفقًا لنوع الحدث:
تكامل Customer Portal
ينشئapp/api/portal.py جلسة Customer Portal لمعرّف عميل ويُرجع رابط البوابة كـ url:
app/templates/index.html معرّف عميل ثابتًا (cus_001) إلى نقطة النهاية هذه، واسمًا وبريدًا إلكترونيًا ثابتين إلى نقطة نهاية Checkout. استبدلهما بقيم المستخدم الذي سجّل دخوله.
أحداث Webhook
يفرّع المعالج الموجود فيapp/api/webhook.py التنفيذ وفقًا لهذه الأحداث:
لمعالجة حدث آخر، أضف فرعًا لنوعه، مثل
refund.succeeded لاسترداد أموال تمت معالجته بنجاح. لمعرفة كل نوع من الأحداث، راجع دليل أحداث Webhook.
أضف منطق نشاطك التجاري داخل معالج webhook من أجل:
- تحديث أذونات المستخدمين في قاعدة بياناتك
- إرسال رسائل بريد إلكتروني للتأكيد
- توفير الوصول إلى المنتجات الرقمية
- تتبع التحليلات والمقاييس
اختبار Webhooks محليًا
لا يستطيع Dodo Payments الوصول إلىlocalhost. للتطوير المحلي، استخدم أداة مثل ngrok لإتاحة خادمك المحلي:
/api/webhook/، كنقطة نهاية في لوحة تحكم Dodo Payments:
DODO_PAYMENTS_WEBHOOK_KEY في .env، ثم أعد تشغيل الخادم. يقرأ التطبيق .env عند بدء التشغيل فقط.
النشر
Docker
لا يتضمن المستودع ملفDockerfile. لتشغيل التطبيق في حاوية، أضف ملف Dockerfile هذا إلى جذر المستودع:
COPY . . كل ملف في سياق البناء، بما في ذلك .env. لإبقاء مفاتيحك خارج الصورة، أضف ملف .dockerignore يتضمن قائمة بـ .env. ثم أنشئ الصورة وشغّلها باستخدام ملف البيئة الخاص بك:
اعتبارات الإنتاج
استكشاف الأخطاء وإصلاحها
Import errors or missing modules
Import errors or missing modules
تأكد من تفعيل البيئة الافتراضية وتثبيت التبعيات:
Server fails to start with Directory 'app/static' does not exist
Server fails to start with Directory 'app/static' does not exist
يخدم
app/main.py الملفات الثابتة من app/static، لكن المستودع لا يتضمن هذا المجلد. أنشئه باستخدام mkdir app/static، ثم ابدأ تشغيل الخادم مرة أخرى.Checkout session creation fails
Checkout session creation fails
تحقق من الأسباب الشائعة التالية:
- معرّف المنتج غير موجود في لوحة تحكم Dodo Payments.
- مفتاح API أو
DODO_PAYMENTS_ENVIRONMENTفي.envغير صحيح. يعمل مفتاح وضع الاختبار فقط معtest_mode.
400. راجع سجلات FastAPI للحصول على رسائل خطأ مفصلة.Webhooks not receiving events
Webhooks not receiving events
للاختبار المحلي، استخدم ngrok لإتاحة خادمك:في لوحة تحكم Dodo، أضف نقطة نهاية باستخدام URL الخاص بـ ngrok متبوعًا بـ
/api/webhook/، بما في ذلك الشرطة المائلة الختامية. انسخ سر توقيع نقطة النهاية إلى DODO_PAYMENTS_WEBHOOK_KEY في ملف .env الخاص بك.Webhook signature verification fails
Webhook signature verification fails
- تأكد من أن
DODO_PAYMENTS_WEBHOOK_KEYفي.envيطابق سر توقيع نقطة النهاية. - تحقّق من التوقيع مقابل نص الطلب الخام، قبل تحليله كـ JSON.
- مرّر ترويسات
webhook-idوwebhook-timestampوwebhook-signatureالثلاث إلىclient.webhooks.unwrap(). يغطي توقيع Standard Webhooks قيمةid.timestamp.body، وليس النص وحده.
تعلّم المزيد
Python SDK
وثائق Python SDK كاملة مع دعم async
Webhooks Documentation
تعرّف على جميع أحداث webhook وأفضل الممارسات
Checkout Sessions
تعمّق في إعدادات جلسة Checkout
API Reference
وثائق Dodo Payments API الكاملة
الدعم
للحصول على المساعدة بشأن النموذج الجاهز:- اطرح الأسئلة في مجتمع Discord.
- أبلغ عن المشكلات وتابع التحديثات في مستودع GitHub.
- راسل فريق الدعم عبر البريد الإلكتروني.