Skip to main content
يمنح Python SDK تطبيقات Python وصولًا م typed إلى REST API الخاص بـ Dodo Payments. ويتضمن عميلًا متزامنًا، DodoPayments، وعميلًا غير متزامن، AsyncDodoPayments، وكلاهما مبني على httpx. وتكون معلمات الطلبات المتداخلة عبارة عن قواميس typed، بينما تكون الاستجابات نماذج Pydantic.

التثبيت

ثبّت SDK باستخدام pip:
لاستخدام aiohttp كواجهة HTTP الخلفية للعميل غير المتزامن، ثبّت الإضافة aiohttp:
للتحقق من توقيعات webhook باستخدام 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 مع كل استدعاء:
احتفظ بمفاتيح API في متغيرات البيئة أو في secrets manager. لا ترفعها مطلقًا إلى version control.

الميزات الأساسية

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 لتحديد حدود منفصلة للقراءة والكتابة والاتصال:
عند انتهاء مهلة الطلب، يرفع SDK الاستثناء APITimeoutError. وتُعاد محاولة الطلبات التي انتهت مهلتها، لذلك قد يستغرق الاستدعاء وقتًا أطول من timeout قبل فشله.

إعادة المحاولات

عيّن max_retries على العميل، أو في طلب واحد باستخدام with_options():
يعيد SDK محاولة أخطاء الاتصال والاستجابات ذات status 408 أو 409 أو 429 أو 500 وما فوق. ويعيد المحاولة مرتين افتراضيًا، مع exponential backoff. عند استمرار فشل الطلب، يرفع SDK فئة فرعية من dodopayments.APIError: ترث استثناءات status من dodopayments.APIStatusError، الذي يحتوي على سمتي status_code وresponse. ويُعد APITimeoutError فئة فرعية من APIConnectionError.

العمليات الشائعة

تستخدم الأمثلة في هذا القسم client من البدء السريع.

إنشاء جلسة دفع

أنشئ جلسة دفع، ثم أعد توجيه العميل إلى checkout_url المُعاد:
يعمل كل checkout_url مرة واحدة وتنتهي صلاحيته بعد 24 ساعة. للاطلاع على كل خيار من خيارات الجلسة، راجع جلسات الدفع.

إدارة العملاء

أنشئ عميلًا باستخدام عنوان بريد إلكتروني واسم، ثم استرده باستخدام المعرّف:

التعامل مع الاشتراكات

أنشئ اشتراكًا، وحمّل تكلفة اشتراك عند الطلب، واقرأ سجل استخدام الاشتراك.
يُعد POST /subscriptions (أسلوب subscriptions.create في SDK) deprecated. ولا يزال يعمل مع عمليات التكامل الحالية، لكن يجب أن تنشئ عمليات التكامل الجديدة الاشتراكات من خلال جلسة دفع.
يتطلب 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:
لاستخدام HTTP client مختلف لطلب واحد، استدعِ 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:

المساهمة

للمساهمة، اقرأ إرشادات المساهمة.
آخر تعديل في ٢٦ سبتمبر ٢٠٢٦