الانتقال إلى المحتوى الرئيسي

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:
pip install dodopayments
لأداء غير متزامن معزز باستخدام 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

ترقيم تلقائي لردود القوائم عبر تكرار بسيط

التكوين

متغيرات البيئة

قم بالتكوين باستخدام متغيرات البيئة:
.env
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؟

المساهمة

نرحب بالمساهمات! تحقق من إرشادات المساهمة للبدء.
Last modified on May 14, 2026