Documentation Index Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt
Use this file to discover all available pages before exploring further.
يوفر SDK بايثون واجهة بايثونية لواجهة برمجة تطبيقات مدفوعات دودو، حيث يقدم عملاء متزامنين وغير متزامنين مع تعريفات نوعية للطلبات والاستجابات. يدعم بايثون 3.9+ ويشمل تغطية شاملة للاختبارات.
التثبيت
قم بتثبيت المكتبة باستخدام pip:
لأداء غير متزامن معزز باستخدام aiohttp:
pip install dodopayments[aiohttp]
يتطلب SDK إصدار Python 3.9 أو أحدث. نوصي باستخدام أحدث إصدار ثابت من Python للحصول على أفضل تجربة وتحديثات الأمان.
البداية السريعة
العميل المتزامن
import os
from dodopayments import DodoPayments
client = DodoPayments(
bearer_token = os.environ.get( "DODO_PAYMENTS_API_KEY" ), # This is the default and can be omitted
environment = "test_mode" , # defaults to "live_mode"
)
checkout_session_response = client.checkout_sessions.create(
product_cart = [
{
"product_id" : "product_id" ,
"quantity" : 1
}
],
)
print (checkout_session_response.session_id)
العميل غير المتزامن
import os
import asyncio
from dodopayments import AsyncDodoPayments
client = AsyncDodoPayments(
bearer_token = os.environ.get( "DODO_PAYMENTS_API_KEY" ),
environment = "test_mode" ,
)
async def main () -> None :
checkout_session_response = await client.checkout_sessions.create(
product_cart = [
{
"product_id" : "product_id" ,
"quantity" : 1 ,
}
],
)
print (checkout_session_response.session_id)
asyncio.run(main())
قم دائمًا بتخزين مفاتيح API الخاصة بك بأمان باستخدام متغيرات البيئة. لا تقم أبدًا بإضافتها إلى نظام التحكم في الإصدارات.
الميزات الأساسية
Pythonic Interface كود Python نظيف وبلغة معبرة يتبع إرشادات PEP 8 واتفاقيات Python
Async/Await دعم كامل للعمليات غير المتزامنة باستخدام asyncio وتكامل aiohttp الاختياري
Type Hints تلميحات أنواع كاملة لدعم أفضل لبيئة التطوير المتكاملة وفحص الأنواع باستخدام mypy
Auto-Pagination ترقيم تلقائي لردود القوائم عبر تكرار بسيط
التكوين
متغيرات البيئة
قم بالتكوين باستخدام متغيرات البيئة:
DODO_PAYMENTS_API_KEY = your_api_key_here
مهلات
قم بتكوين مهلات الطلبات على مستوى عالمي أو لكل طلب:
import httpx
from dodopayments import DodoPayments
# Configure default for all requests (default is 1 minute)
client = DodoPayments(
timeout = 20.0 , # 20 seconds
)
# More granular control
client = DodoPayments(
timeout = httpx.Timeout( 60.0 , read = 5.0 , write = 10.0 , connect = 2.0 ),
)
# Override per-request
client.with_options( timeout = 5.0 ).checkout_sessions.create(
product_cart = [
{
"product_id" : "product_id" ,
"quantity" : 1 ,
}
],
)
إعادة المحاولة
قم بتكوين سلوك إعادة المحاولة التلقائي:
from dodopayments import DodoPayments
# Configure default for all requests (default is 2)
client = DodoPayments(
max_retries = 0 , # disable retries
)
# Override per-request
client.with_options( max_retries = 5 ).checkout_sessions.create(
product_cart = [
{
"product_id" : "product_id" ,
"quantity" : 1 ,
}
],
)
العمليات الشائعة
إنشاء جلسة دفع
قم بإنشاء جلسة دفع:
session = client.checkout_sessions.create(
product_cart = [
{
"product_id" : "prod_123" ,
"quantity" : 1
}
],
return_url = "https://yourdomain.com/return"
)
print ( f "Checkout URL: { session.url } " )
إدارة العملاء
قم بإنشاء واسترجاع معلومات العملاء:
# Create a customer
customer = client.customers.create(
email = "customer@example.com" ,
name = "John Doe" ,
metadata = {
"user_id" : "12345"
}
)
# Retrieve customer
customer = client.customers.retrieve( "cus_123" )
print ( f "Customer: { customer.name } ( { customer.email } )" )
التعامل مع الاشتراكات
قم بإنشاء وإدارة الاشتراكات المتكررة:
# Create a subscription
subscription = client.subscriptions.create(
billing = {
"country" : "US" ,
"city" : "San Francisco" ,
"state" : "CA" ,
"street" : "1 Market St" ,
"zipcode" : "94105" ,
},
customer = { "customer_id" : "cus_123" }, # or {"email": "...", "name": "..."} for a new customer
product_id = "pdt_456" ,
quantity = 1 ,
)
# Charge an on-demand subscription
# product_price is in the lowest currency denomination (e.g., 2500 = $25.00 USD)
charge_response = client.subscriptions.charge(
subscription_id = subscription.subscription_id,
product_price = 2500 ,
)
# Retrieve usage history (for metered subscriptions)
usage_history = client.subscriptions.retrieve_usage_history(
subscription_id = subscription.subscription_id,
start_date = "2024-01-01T00:00:00Z" ,
)
billing يتطلب على الأقل رمز البلد المكون من حرفين ISO. customer يقبل إما {"customer_id": ...} لإرفاق عميل موجود أو {"email": ..., "name": ...} لإنشاء عميل جديد. product_price يكون في أقل فئة عملة.
الفوترة القائمة على الاستخدام
إدخال أحداث الاستخدام
تتبع الأحداث المخصصة للفوترة القائمة على الاستخدام:
response = client.usage_events.ingest(
events = [
{
"event_id" : "api_call_12345" ,
"customer_id" : "cus_abc123" ,
"event_name" : "api_request" ,
"timestamp" : "2024-01-15T10:30:00Z" ,
"metadata" : {
"endpoint" : "/api/v1/users" ,
"method" : "GET" ,
"tokens_used" : "150"
}
}
]
)
قائمة واسترجاع الأحداث
# Get a specific event
event = client.usage_events.retrieve( "api_call_12345" )
# List events with filtering
events = client.usage_events.list(
customer_id = "cus_abc123" ,
event_name = "api_request" ,
limit = 20
)
for event in events.data:
print ( f "Event: { event.event_id } at { event.timestamp } " )
الترقيم
الترقيم التلقائي
التنقل عبر جميع العناصر تلقائيًا:
from dodopayments import DodoPayments
client = DodoPayments()
all_payments = []
# Automatically fetches more pages as needed
for payment in client.payments.list():
all_payments.append(payment)
print (all_payments)
الترقيم غير المتزامن
import asyncio
from dodopayments import AsyncDodoPayments
client = AsyncDodoPayments()
async def main () -> None :
all_payments = []
# Iterate through items across all pages
async for payment in client.payments.list():
all_payments.append(payment)
print (all_payments)
asyncio.run(main())
الترقيم اليدوي
للحصول على مزيد من التحكم في الترقيم:
# Access items from current page
first_page = client.payments.list()
for payment in first_page.items:
print (payment.brand_id)
# Check for more pages
if first_page.has_next_page():
next_page = first_page.get_next_page()
print ( f "Fetched { len (next_page.items) } more items" )
إعداد عميل HTTP
تخصيص العميل الأساسي httpx:
import httpx
from dodopayments import DodoPayments, DefaultHttpxClient
client = DodoPayments(
base_url = "http://my.test.server.example.com:8083" ,
http_client = DefaultHttpxClient(
proxy = "http://my.test.proxy.example.com" ,
transport = httpx.HTTPTransport( local_address = "0.0.0.0" ),
),
)
Async مع aiohttp
استخدم aiohttp لأداء متزامن معزز:
import asyncio
from dodopayments import DefaultAioHttpClient
from dodopayments import AsyncDodoPayments
async def main () -> None :
async with AsyncDodoPayments(
bearer_token = "My Bearer Token" ,
http_client = DefaultAioHttpClient(),
) as client:
checkout_session_response = await client.checkout_sessions.create(
product_cart = [
{
"product_id" : "product_id" ,
"quantity" : 1 ,
}
],
)
print (checkout_session_response.session_id)
asyncio.run(main())
التسجيل
تفعيل التسجيل عن طريق ضبط متغير البيئة:
export DODO_PAYMENTS_LOG = info
أو لتسجيل مستوى التصحيح:
export DODO_PAYMENTS_LOG = debug
تكامل الإطار
FastAPI
from fastapi import FastAPI, HTTPException
from dodopayments import AsyncDodoPayments
from pydantic import BaseModel
import os
app = FastAPI()
dodo = AsyncDodoPayments( bearer_token = os.getenv( "DODO_API_KEY" ))
class CheckoutRequest ( BaseModel ):
product_id: str
quantity: int
@app.post ( "/create-checkout" )
async def create_checkout ( request : CheckoutRequest):
try :
session = await dodo.checkout_sessions.create(
product_cart = [{
"product_id" : request.product_id,
"quantity" : request.quantity
}],
return_url = "https://yourdomain.com/return"
)
return { "checkout_url" : session.url}
except Exception as e:
raise HTTPException( status_code = 400 , detail = str (e))
Django
from django.http import JsonResponse
from django.views.decorators.http import require_POST
from django.views.decorators.csrf import csrf_exempt
from dodopayments import DodoPayments
import os
import json
client = DodoPayments( bearer_token = os.getenv( "DODO_PAYMENTS_API_KEY" ))
@csrf_exempt
@require_POST
def create_checkout ( request ):
try :
data = json.loads(request.body)
session = client.checkout_sessions.create(
product_cart = [{
"product_id" : data.get( "product_id" ),
"quantity" : data.get( "quantity" , 1 )
}],
return_url = "https://yourdomain.com/return"
)
return JsonResponse({
"status" : "success" ,
"checkout_url" : session.url,
"session_id" : session.session_id
})
except Exception as e:
return JsonResponse({
"status" : "error" ,
"message" : str (e)
}, status = 400 )
الموارد
GitHub Repository عرض مصدر التعليمات البرمجية والمساهمة
API Reference الوثائق الكاملة لواجهة برمجة التطبيقات
Discord Community الحصول على المساعدة والاتصال بالمطورين
Report Issues الإبلاغ عن الأخطاء أو طلب الميزات
الدعم
هل تحتاج إلى مساعدة مع Python SDK؟
المساهمة
نرحب بالمساهمات! تحقق من إرشادات المساهمة للبدء.