Skip to main content

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

أو باستخدام uv:
4

Get API Credentials

سجّل حسابًا في Dodo Payments، ثم احصل على بيانات الاعتماد من لوحة التحكم:
أنشئ كليهما أثناء إيقاف مفتاح Live Mode في الشريط الجانبي. يعمل مفتاح وضع الاختبار فقط مع DODO_PAYMENTS_ENVIRONMENT=test_mode، ولا تنقل المدفوعات في وضع الاختبار أموالًا حقيقية.
5

Configure Environment Variables

انسخ الملف النموذجي لإنشاء ملف .env في الدليل الجذر:
عيّن القيم إلى بيانات اعتماد Dodo Payments الخاصة بك:
.env
المتغيرات الأربعة مطلوبة. يحمّل app/core/config.py هذه المتغيرات باستخدام pydantic-settings، ويفشل التطبيق في بدء التشغيل إذا كان أحدها مفقودًا أو فارغًا. DODO_PAYMENTS_RETURN_URL هو المكان الذي يرسل إليه checkout العميل بعد الدفع.
لا تُضمّن ملف .env في version control. يستبعده .gitignore الموجود في المستودع مسبقًا.
6

Add Your Products

استبدل المنتجات النموذجية في app/lib/products.py بمنتجاتك الخاصة. عيّن كل product_id إلى معرّف منتج ضمن المنتجات في لوحة التحكم. تعرض صفحة التسعير هذه المنتجات.
7

Run the Development Server

افتح http://localhost:8000/docs للاطلاع على توثيق API التفاعلي.
يسرد Swagger UI endpoints ‏/api/checkout/ و/api/webhook/ و/api/customer-portal/، وهي جاهزة للاختبار.
يخدم عنوان URL الجذر، http://localhost:8000، صفحة التسعير.
يستدعي app/main.py الدالة templates.TemplateResponse("index.html", {"request": request, ...})، وهي توقيع لم يعد Starlette 1.x يقبله، لذلك تُرجع صفحة التسعير خطأ 500 عند التثبيت الجديد. لإصلاح ذلك، غيّر الاستدعاء إلى templates.TemplateResponse(request, "index.html", {"products": products}).

بنية المشروع

نقاط نهاية 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 لإتاحة خادمك المحلي:
أضف URL الخاص بـ ngrok عبر HTTPS، متبوعًا بـ /api/webhook/، كنقطة نهاية في لوحة تحكم Dodo Payments:
انسخ سر توقيع نقطة النهاية إلى DODO_PAYMENTS_WEBHOOK_KEY في .env، ثم أعد تشغيل الخادم. يقرأ التطبيق .env عند بدء التشغيل فقط.

النشر

Docker

لا يتضمن المستودع ملف Dockerfile. لتشغيل التطبيق في حاوية، أضف ملف Dockerfile هذا إلى جذر المستودع:
ينسخ COPY . . كل ملف في سياق البناء، بما في ذلك .env. لإبقاء مفاتيحك خارج الصورة، أضف ملف .dockerignore يتضمن قائمة بـ .env. ثم أنشئ الصورة وشغّلها باستخدام ملف البيئة الخاص بك:

اعتبارات الإنتاج

قبل النشر إلى الإنتاج:
  • بدّل DODO_PAYMENTS_ENVIRONMENT إلى live_mode.
  • استخدم مفتاح API للوضع المباشر من لوحة التحكم.
  • أضف نقطة نهاية webhook لنطاق الإنتاج، واضبط DODO_PAYMENTS_WEBHOOK_KEY على سر توقيعها.
  • اضبط DODO_PAYMENTS_RETURN_URL على URL الخاص بالإنتاج.
  • فعّل HTTPS لجميع نقاط النهاية.

استكشاف الأخطاء وإصلاحها

تأكد من تفعيل البيئة الافتراضية وتثبيت التبعيات:
يخدم app/main.py الملفات الثابتة من app/static، لكن المستودع لا يتضمن هذا المجلد. أنشئه باستخدام mkdir app/static، ثم ابدأ تشغيل الخادم مرة أخرى.
تحقق من الأسباب الشائعة التالية:
  • معرّف المنتج غير موجود في لوحة تحكم Dodo Payments.
  • مفتاح API أو DODO_PAYMENTS_ENVIRONMENT في .env غير صحيح. يعمل مفتاح وضع الاختبار فقط مع test_mode.
تُرجع نقطة النهاية خطأ SDK في استجابة 400. راجع سجلات FastAPI للحصول على رسائل خطأ مفصلة.
للاختبار المحلي، استخدم ngrok لإتاحة خادمك:
في لوحة تحكم Dodo، أضف نقطة نهاية باستخدام URL الخاص بـ ngrok متبوعًا بـ /api/webhook/، بما في ذلك الشرطة المائلة الختامية. انسخ سر توقيع نقطة النهاية إلى DODO_PAYMENTS_WEBHOOK_KEY في ملف .env الخاص بك.
  • تأكد من أن 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 الكاملة

الدعم

للحصول على المساعدة بشأن النموذج الجاهز:
آخر تعديل في ٢٦ سبتمبر ٢٠٢٦