DodoPayments، وعميلًا غير متزامن، AsyncDodoPayments، وكلاهما مبني على httpx. وتكون معلمات الطلبات المتداخلة عبارة عن قواميس typed، بينما تكون الاستجابات نماذج Pydantic.
التثبيت
ثبّت SDK باستخدام pip:aiohttp:
client.webhooks.unwrap()، ثبّت أيضًا الإضافة webhooks: pip install "dodopayments[webhooks]".
يتطلب SDK استخدام Python 3.9 أو إصدار أحدث. استخدم أحدث إصدار مستقر من Python للحصول على تحديثات الأمان.
بدء سريع
العميل المتزامن
أنشئ عميلًا، ثم أنشئ جلسة دفع:bearer_token، فسيقرأ العميل متغير البيئة DODO_PAYMENTS_API_KEY. وإذا لم تحدد environment، فسيتصل العميل بالوضع المباشر. يعمل مفتاح API الخاص بوضع الاختبار فقط مع environment="test_mode".
العميل غير المتزامن
يحتويAsyncDodoPayments على الأساليب نفسها الموجودة في DodoPayments. استخدم await مع كل استدعاء:
الميزات الأساسية
Pythonic Interface
وسيطات keyword للمعلمات، وأنواع
TypedDict للكائنات المتداخلة، ونماذج Pydantic للاستجابات.Async/Await
AsyncDodoPayments لـ asyncio، مع aiohttp كواجهة HTTP خلفية اختيارية.Type Hints
تلميحات type في كل أسلوب، لتوفير الإكمال التلقائي في المحرر والتحقق من الأنواع باستخدام mypy.
Auto-Pagination
تُرجع أساليب القائمة iterators تجلب الصفحة التالية أثناء التكرار.
الإعدادات
متغيرات البيئة
خزّن مفتاح API في متغير بيئة:.env
إذا تم تعيين
DODO_PAYMENTS_BASE_URL ومررت أيضًا environment، فسيُصدر المُنشئ خطأ “Ambiguous URL”. لاستخدام environment في هذه الحالة، مرر base_url=None.
للتحقق من webhook، مرر نص الطلب الخام والعناوين إلى client.webhooks.unwrap(payload, headers=headers). ويتحقق من التوقيع باستخدام مفتاح webhook الخاص بك ويُرجع الحدث المحلل. أما client.webhooks.unsafe_unwrap(payload) فيحلل النص دون التحقق منه، لذا استخدمه للاختبار فقط. راجع Webhooks.
مهلات الانتظار
تنتهي مهلة الطلبات بعد دقيقة واحدة افتراضيًا، مع مهلة اتصال مدتها 5 ثوانٍ. مررtimeout بالثواني، أو مرر httpx.Timeout لتحديد حدود منفصلة للقراءة والكتابة والاتصال:
APITimeoutError. وتُعاد محاولة الطلبات التي انتهت مهلتها، لذلك قد يستغرق الاستدعاء وقتًا أطول من timeout قبل فشله.
إعادة المحاولات
عيّنmax_retries على العميل، أو في طلب واحد باستخدام with_options():
dodopayments.APIError:
ترث استثناءات status من
dodopayments.APIStatusError، الذي يحتوي على سمتي status_code وresponse. ويُعد APITimeoutError فئة فرعية من APIConnectionError.
العمليات الشائعة
تستخدم الأمثلة في هذا القسمclient من البدء السريع.
إنشاء جلسة دفع
أنشئ جلسة دفع، ثم أعد توجيه العميل إلىcheckout_url المُعاد:
checkout_url مرة واحدة وتنتهي صلاحيته بعد 24 ساعة. للاطلاع على كل خيار من خيارات الجلسة، راجع جلسات الدفع.
إدارة العملاء
أنشئ عميلًا باستخدام عنوان بريد إلكتروني واسم، ثم استرده باستخدام المعرّف:التعامل مع الاشتراكات
أنشئ اشتراكًا، وحمّل تكلفة اشتراك عند الطلب، واقرأ سجل استخدام الاشتراك.يتطلب
billing فقط country، وهو رمز دولة ISO مكوّن من حرفين. ويأخذ customer قيمة {"customer_id": ...} لإرفاق عميل موجود، أو {"email": ..., "name": ...} لإنشاء عميل. ويُستخدم charge مع الاشتراكات عند الطلب، بينما يكون product_price بوحدة العملة الأصغر. ويُرجع retrieve_usage_history قائمة مقسّمة إلى صفحات، ويمكنك التكرار خلالها كما هو موضح في التقسيم إلى صفحات.الفوترة المستندة إلى الاستخدام
إدخال أحداث الاستخدام
أرسل أحداث الاستخدام لعميل:إن
event_id هو مفتاح idempotency، لذا امنح كل حدث قيمة فريدة. إذا ظهر event_id نفسه مرتين في طلب واحد، فسيُرفض الطلب بأكمله. وإذا كان قد تم إدخال event_id من قبل، فسيُتجاهل الحدث الجديد. يقبل الطلب ما يصل إلى 1,000 حدث. وتكون قيمة timestamp افتراضيًا هي الوقت الحالي، ويُرفض الطلب إذا كانت أقدم من ساعة واحدة أو تتجاوز الوقت الحالي بأكثر من 5 دقائق.سرد الأحداث واستردادها
استرد حدثًا واحدًا باستخدامevent_id الخاص به، أو اسرد الأحداث مع تصفيتها حسب العميل واسم الحدث:
usage_events.list أيضًا عوامل تصفية meter_id وstart وend.
التقسيم إلى صفحات
التقسيم التلقائي إلى صفحات
تُرجع أساليب القائمة iterator يجلب الصفحة التالية أثناء التكرار:التقسيم غير المتزامن إلى صفحات
باستخدام العميل غير المتزامن، كرّر باستخدامasync for:
التقسيم اليدوي إلى صفحات
للعمل مع صفحة واحدة في كل مرة، اقرأitems واستدعِ has_next_page() وget_next_page(). ويُرجع next_page_info() المعلمات الخاصة بالطلب التالي:
إعدادات HTTP Client
لإضافة proxy أو transport مخصص أو إعدادات أخرى لـhttpx، مرر http_client الخاص بك. ويحافظ DefaultHttpxClient على حدود الاتصال والمهلة وإعدادات إعادة التوجيه الافتراضية لـ SDK:
client.with_options(http_client=...).
Async مع AIOHTTP
افتراضيًا، يرسل العميل غير المتزامن الطلبات باستخدامhttpx. ولتحقيق تزامن أفضل، ثبّت الإضافة aiohttp ومرر DefaultAioHttpClient() باعتباره http_client:
التسجيل
يسجل SDK باستخدام الوحدةlogging من standard library. لتفعيل التسجيل، عيّن DODO_PAYMENTS_LOG إلى info:
debug:
التكامل مع أطر العمل
تنشئ هذه الأمثلة جلسة دفع من web endpoint وتُرجع عنوان URL الخاص بها.FastAPI
تستخدم نقطة النهاية هذه العميل غير المتزامن:Django
يستخدم هذا العرض العميل المتزامن:الموارد
GitHub Repository
الشيفرة المصدرية والإصدارات والقائمة الكاملة للأساليب.
API Reference
كل نقطة نهاية ومعلمة واستجابة.
Discord Community
اطرح الأسئلة وتحدث مع المطورين الآخرين.
Report Issues
أبلغ عن الأخطاء أو اطلب ميزات جديدة.
الدعم
للحصول على المساعدة بشأن Python SDK:- Discord: انضم إلى خادم المجتمع للحصول على مساعدة فورية.
- البريد الإلكتروني: تواصل مع support@dodopayments.com.
- GitHub: افتح issue في المستودع.