> ## 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.
# FastAPI ボイラープレート
> Dodo Payments を Python バックエンドアプリケーションに統合するための FastAPI ボイラープレートで迅速に始めましょう
FastAPI + Dodo Payments のボイラープレートを完成させる
## 概要
FastAPI ボイラープレートは、Dodo Payments を Python バックエンドに統合するための生産準備が整った出発点を提供します。このテンプレートには、チェックアウトセッションの処理、Webhook の検証、カスタマーポータルの統合、非同期 API パターンが含まれており、迅速に支払いを受け入れることができます。
このボイラープレートでは、非同期/await パターンの FastAPI、検証には Pydantic、シームレスな API 統合には `dodopayments` Python SDK を使用しています。
### 特徴
* **クイックセットアップ** - 5 分以内に始められます
* **非同期サポート** - FastAPI のネイティブな非同期/待機パターンで構築
* **チェックアウトセッション** - Python SDK を使用した事前設定されたチェックアウトフロー
* **Webhook 処理** - 署名検証付きの安全な Webhook エンドポイント
* **カスタマーポータル** - 簡単なカスタマーポータルセッションの作成
* **型安全性** - 完全な Pydantic 検証と型ヒント
* **環境設定** - すぐに使用できる環境変数のセットアップ
## 前提条件
始める前に、次のものを用意してください：
* **Python 3.9+**（推奨：Python 3.11+）
* **pip** または **uv** パッケージ管理用
* **Dodo Payments アカウント**（ダッシュボードから API および Webhook キーにアクセスするため）
## クイックスタート
```bash theme={null}
git clone https://github.com/dodopayments/fastapi-boilerplate.git
cd fastapi-boilerplate
```
独立した Python 環境をセットアップします:
```bash theme={null}
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
```
または、依存関係管理を高速化するために uv を使用：
```bash theme={null}
uv venv
source .venv/bin/activate
```
```bash theme={null}
pip install -r requirements.txt
```
または uv を使用：
```bash theme={null}
uv pip install -r requirements.txt
```
[Dodo Payments](https://dodopayments.com/) にサインアップし、ダッシュボードから資格情報を取得します:
* **API キー:** [ダッシュボード → 開発者 → API キー](https://app.dodopayments.com/developer/api-keys)
* **Webhook キー:** [ダッシュボード → 開発者 → Webhooks](https://app.dodopayments.com/developer/webhooks)
開発中は **Test Mode** にしておいてください！
ルートディレクトリに `.env` ファイルを作成します:
```bash theme={null}
cp .env.example .env
```
Dodo Payments の認証情報で値を更新します：
```bash .env theme={null}
DODO_PAYMENTS_API_KEY=your_api_key_here
DODO_PAYMENTS_WEBHOOK_KEY=your_webhook_signing_key_here
DODO_PAYMENTS_ENVIRONMENT=test_mode
```
`.env` ファイルをバージョン管理にコミットしないでください。`.gitignore` にすでに含まれています。
```bash theme={null}
uvicorn main:app --reload
```
[http://localhost:8000/docs](http://localhost:8000/docs) を開いて、インタラクティブな API ドキュメントを確認してください！
利用可能なすべてのエンドポイントがテスト可能な状態で FastAPI の Swagger UI が表示されているはずです。
## プロジェクト構造
```text theme={null}
fastapi-boilerplate/
├── main.py # FastAPI application entry point
├── routers/
│ ├── checkout.py # Checkout session endpoints
│ ├── webhook.py # Webhook handler endpoint
│ └── customer_portal.py # Customer portal endpoints
├── config.py # Environment configuration
├── requirements.txt # Python dependencies
├── .env.example # Environment template
└── README.md
```
## API エンドポイント
ボイラープレートには、次の事前設定されたエンドポイントが含まれています：
| エンドポイント | メソッド | 説明 |
| ------------------ | ---- | -------------------------- |
| `/checkout` | POST | 新しいチェックアウトセッションを作成する |
| `/webhook` | POST | Dodo Payments のウェブフックを処理する |
| `/customer-portal` | POST | カスタマーポータル URL を生成する |
## コード例
### チェックアウトセッションの作成
```python theme={null}
from fastapi import APIRouter, HTTPException
from dodopayments import AsyncDodoPayments
from pydantic import BaseModel
from config import settings
router = APIRouter()
dodo = AsyncDodoPayments(
bearer_token=settings.DODO_PAYMENTS_API_KEY,
environment=settings.DODO_PAYMENTS_ENVIRONMENT
)
class CheckoutRequest(BaseModel):
product_id: str
quantity: int = 1
customer_email: str | None = None
customer_name: str | None = None
@router.post("/checkout")
async def create_checkout(request: CheckoutRequest):
try:
session = await dodo.checkout_sessions.create(
product_cart=[{
"product_id": request.product_id,
"quantity": request.quantity
}],
customer={
"email": request.customer_email,
"name": request.customer_name
} if request.customer_email else None,
return_url="http://localhost:8000/success"
)
return {"checkout_url": session.checkout_url, "session_id": session.session_id}
except Exception as e:
raise HTTPException(status_code=400, detail=str(e))
```
### Webhook の処理
```python theme={null}
from fastapi import APIRouter, Request, HTTPException
import hmac
import hashlib
from config import settings
router = APIRouter()
def verify_webhook_signature(payload: bytes, signature: str) -> bool:
expected = hmac.new(
settings.DODO_PAYMENTS_WEBHOOK_KEY.encode(),
payload,
hashlib.sha256
).hexdigest()
return hmac.compare_digest(expected, signature)
@router.post("/webhook")
async def handle_webhook(request: Request):
payload = await request.body()
signature = request.headers.get("webhook-signature", "")
if not verify_webhook_signature(payload, signature):
raise HTTPException(status_code=401, detail="Invalid signature")
event = await request.json()
event_type = event.get("type")
match event_type:
case "payment.succeeded":
# Handle successful payment
payment_id = event["data"]["payment_id"]
print(f"Payment succeeded: {payment_id}")
case "subscription.active":
# Handle subscription activation
subscription_id = event["data"]["subscription_id"]
print(f"Subscription activated: {subscription_id}")
case "refund.succeeded":
# Handle refund
refund_id = event["data"]["refund_id"]
print(f"Refund processed: {refund_id}")
return {"status": "received"}
```
### カスタマーポータルの統合
```python theme={null}
from fastapi import APIRouter, HTTPException
from dodopayments import AsyncDodoPayments
from pydantic import BaseModel
from config import settings
router = APIRouter()
dodo = AsyncDodoPayments(
bearer_token=settings.DODO_PAYMENTS_API_KEY,
environment=settings.DODO_PAYMENTS_ENVIRONMENT
)
class PortalRequest(BaseModel):
customer_id: str
@router.post("/customer-portal")
async def create_portal_session(request: PortalRequest):
try:
session = await dodo.customers.customer_portal.create(
customer_id=request.customer_id,
)
return {"portal_url": session.link}
except Exception as e:
raise HTTPException(status_code=400, detail=str(e))
```
## Webhook イベント
ボイラープレートは、一般的な Webhook イベントの処理を示しています：
| イベント | 説明 |
| ------------------------ | -------------------- |
| `payment.succeeded` | 支払いが正常に完了しました |
| `payment.failed` | 支払いの試行に失敗しました |
| `subscription.active` | サブスクリプションが有効になりました |
| `subscription.cancelled` | サブスクリプションがキャンセルされました |
| `refund.succeeded` | 返金が正常に処理されました |
Webhook ハンドラー内にビジネスロジックを追加して：
* データベース内のユーザー権限を更新
* 確認メールを送信
* デジタル製品へのアクセスを提供
* 分析とメトリクスを追跡
## Webhook をローカルでテスト
ローカル開発には、[ngrok](https://ngrok.com/) のようなツールを使用してローカルサーバーを公開します：
```bash theme={null}
ngrok http 8000
```
Webhook URL を [Dodo Payments ダッシュボード](https://app.dodopayments.com/developer/webhooks) で更新します：
```
https://your-ngrok-url.ngrok.io/webhook
```
## デプロイメント
### Docker
```dockerfile theme={null}
FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]
```
ビルドして実行：
```bash theme={null}
docker build -t fastapi-dodo .
docker run -p 8000:8000 --env-file .env fastapi-dodo
```
### 本番環境での考慮事項
本番環境にデプロイする前に:
* `DODO_PAYMENTS_ENVIRONMENT` を `live_mode` に切り替える
* ダッシュボードの本番用 API キーを使用する
* Webhook URL を本番ドメインに更新する
* 全てのエンドポイントで HTTPS を有効化する
## トラブルシューティング
仮想環境がアクティブ化され、依存関係がインストールされていることを確認してください:
```bash theme={null}
source venv/bin/activate
pip install -r requirements.txt
```
**一般的な原因:**
* 無効な商品 ID - Dodo ダッシュボードに存在することを確認してください
* `.env` に誤った API キーまたは環境設定がある
* 詳細なエラーメッセージは FastAPI のログを確認してください
ローカルテストには [ngrok](https://ngrok.com) を使用してサーバーを公開します:
```bash theme={null}
ngrok http 8000
```
ウェブフック URL を [Dodo ダッシュボード](https://app.dodopayments.com/developer/webhooks) で ngrok URL に更新し、`.env` ファイルを正しいウェブフック検証キーで更新してください。
* `.env` 内の `DODO_PAYMENTS_WEBHOOK_KEY` が正しく設定されていることを確認する
* 署名検証には生のリクエストボディを使用していることを確認する
* `webhook-signature` ヘッダーを正しく読み取っているか確認する
## 詳細を学ぶ
非同期対応の Python SDK ドキュメントを完成させる
すべてのウェブフックイベントとベストプラクティスについて学ぶ
チェックアウトセッションの設定を詳細に掘り下げる
Dodo Payments API ドキュメントを完成させる
## サポート
ボイラープレートに関して助けが必要ですか？
* 質問や議論のために [Discord コミュニティ](https://discord.gg/bYqAp4ayYh) に参加してください
* 問題や更新については [GitHub リポジトリ](https://github.com/dodopayments/fastapi-boilerplate) を確認してください
* 支援が必要な場合は [サポートチーム](mailto:support@dodopayments.com) にお問い合わせください