> ## 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.
# Python
> Integra Dodo Payments nelle tue applicazioni Python con un'interfaccia Pythonica e supporto moderno per async/await
Il SDK Python offre un'interfaccia Pythonica per l'API Dodo Payments, fornendo sia client sincroni che asincroni con definizioni di tipo per richieste e risposte. Supporta Python 3.9+ e include una copertura di test completa.
## Installazione
Installa il SDK usando pip:
```bash theme={null}
pip install dodopayments
```
Per prestazioni asincrone migliorate con aiohttp:
```bash theme={null}
pip install dodopayments[aiohttp]
```
L'SDK richiede Python 3.9 o versioni successive. Consigliamo di utilizzare l'ultima versione stabile di Python per offrire la migliore esperienza e gli aggiornamenti di sicurezza.
## Avvio Veloce
### Client Sincrono
```python theme={null}
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)
```
### Client Asincrono
```python theme={null}
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())
```
Conserva sempre in modo sicuro le chiavi API usando le variabili d'ambiente. Non inserirle mai nel controllo versione.
## Caratteristiche Principali
Codice Python pulito e idiomatico che segue le linee guida di PEP 8 e le convenzioni Python
Supporto completo per le operazioni asincrone con asyncio e integrazione opzionale con aiohttp
Hint di tipo completi per un migliore supporto IDE e controllo dei tipi con mypy
Paginazione automatica per le risposte di elenco con semplice iterazione
## Configurazione
### Variabili d'Ambiente
Configura utilizzando variabili d'ambiente:
```bash .env theme={null}
DODO_PAYMENTS_API_KEY=your_api_key_here
```
### Timeout
Configura i timeout delle richieste globalmente o per richiesta:
```python theme={null}
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,
}
],
)
```
### Riprova
Configura il comportamento di riprova automatica:
```python theme={null}
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,
}
],
)
```
## Operazioni Comuni
### Crea una Sessione di Checkout
Genera una sessione di checkout:
```python theme={null}
session = client.checkout_sessions.create(
product_cart=[
{
"product_id": "prod_123",
"quantity": 1
}
],
return_url="https://yourdomain.com/return"
)
print(f"Checkout URL: {session.checkout_url}")
```
### Gestisci Clienti
Crea e recupera informazioni sui clienti:
```python theme={null}
# 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})")
```
### Gestisci Abbonamenti
Crea e gestisci abbonamenti ricorrenti:
```python theme={null}
# 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` richiede almeno il codice ISO del paese a due lettere. `customer` accetta `{"customer_id": ...}` per allegare un cliente esistente o `{"email": ..., "name": ...}` per crearne uno nuovo. `product_price` è nella denominazione più bassa della valuta.
## Fatturazione Basata sull'Uso
### Ingestione degli Eventi di Utilizzo
Traccia eventi personalizzati per la fatturazione basata sull'uso:
```python theme={null}
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"
}
}
]
)
```
### Elencare e Recuperare Eventi
```python theme={null}
# 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}")
```
## Paginazione
### Auto-Paginazione
Iterare automaticamente attraverso tutti gli elementi:
```python theme={null}
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)
```
### Paginazione Asincrona
```python theme={null}
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())
```
### Paginazione Manuale
Per un maggiore controllo sulla paginazione:
```python theme={null}
# 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")
```
## Configurazione Client HTTP
Personalizza il client sottostante `httpx`:
```python theme={null}
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 con aiohttp
Usa aiohttp per prestazioni asincrone migliorate:
```python theme={null}
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())
```
## Logging
Abilita il logging impostando la variabile d'ambiente:
```bash theme={null}
export DODO_PAYMENTS_LOG=info
```
Oppure per il logging a livello di debug:
```bash theme={null}
export DODO_PAYMENTS_LOG=debug
```
## Integrazione con Framework
### FastAPI
```python theme={null}
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.checkout_url}
except Exception as e:
raise HTTPException(status_code=400, detail=str(e))
```
### Django
```python theme={null}
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.checkout_url,
"session_id": session.session_id
})
except Exception as e:
return JsonResponse({
"status": "error",
"message": str(e)
}, status=400)
```
## Risorse
Visualizza il codice sorgente e contribuisci
Documentazione completa dell'API
Ottieni aiuto e connettiti con gli sviluppatori
Segnala bug o richiedi funzionalità
## Supporto
Hai bisogno di aiuto con il Python SDK?
* **Discord**: Unisciti al nostro [server della community](https://discord.gg/bYqAp4ayYh) per supporto in tempo reale
* **Email**: Contattaci a [support@dodopayments.com](mailto:support@dodopayments.com)
* **GitHub**: Apri un problema nel [repository](https://github.com/dodopayments/dodopayments-python)
## Contributi
Accogliamo con favore i contributi! Controlla le [linee guida sui contributi](https://github.com/dodopayments/dodopayments-python/blob/main/CONTRIBUTING.md) per iniziare.