# API仕様書

| 項目 | 内容 |
|------|------|
| 文書番号 | API-ECOM-001 |
| バージョン | 1.0 |
| 作成日 | 2025年12月1日 |
| ステータス | 承認済み |

---

## 1. 概要

| サービス | ベースURL | バージョン |
|---------|----------|-----------|
| 注文サービス | http://localhost:8000/api/v1 | v1 |
| 決済サービス | http://localhost:8001/api/v1 | v1 |
| 通知サービス | http://localhost:8002/api/v1 | v1 |
| フロントエンド管理画面 | http://localhost:5173 | — |

### 共通エラーレスポンス
```json
{"detail": "エラー説明文"}
```

---

## 2. 注文サービスAPI

### 2.1 POST /api/v1/orders/ — 1件の注文作成

> **注記:** 1リクエストにつき**1件の注文**を作成。一括作成エンドポイントは存在しない。

**リクエスト:**
```json
{
    "customer_email": "tanaka@example.co.jp",
    "customer_name": "田中太郎",
    "items": [
        {"product_name": "ノートPC", "quantity": 2, "unit_price": 89800.0},
        {"product_name": "マウス", "quantity": 1, "unit_price": 3500.0}
    ],
    "currency": "JPY"
}
```

**レスポンス (201):**
```json
{
    "id": 1,
    "customer_email": "tanaka@example.co.jp",
    "customer_name": "田中太郎",
    "status": "paid",
    "total_amount": 183100.0,
    "currency": "JPY",
    "items": [
        {"id": 1, "product_name": "ノートPC", "quantity": 2, "unit_price": 89800.0},
        {"id": 2, "product_name": "マウス", "quantity": 1, "unit_price": 3500.0}
    ],
    "created_at": "2025-12-01T10:00:00Z",
    "updated_at": "2025-12-01T10:00:01Z"
}
```

**副作用:** 決済サービス呼出し + 通知サービス呼出し

### 2.2 GET /api/v1/orders/?skip=0&limit=20 — 注文一覧

### 2.3 GET /api/v1/orders/{order_id} — 注文取得

### 2.4 PUT /api/v1/orders/{order_id}/status — ステータス更新

### 2.5 DELETE /api/v1/orders/{order_id} — 注文キャンセル

**副作用:** 返金処理 + キャンセル通知

### 2.6 POST /api/v1/orders/{order_id}/webhook — 決済Webhook

---

## 3. 決済サービスAPI

### 3.1 POST /api/v1/payments/ — 1件の決済処理

> **注記:** 1リクエストにつき**1件の決済**。金額: 最低100円、最大100万円。

**リクエスト:** `{"order_id": 1, "amount": 183100.0, "currency": "JPY"}`

**レスポンス (201):**
```json
{
    "id": 1, "order_id": 1, "amount": 183100.0, "currency": "JPY",
    "status": "completed", "payment_method": "credit_card",
    "transaction_id": "550e8400-e29b-41d4-a716-446655440000",
    "created_at": "2025-12-01T10:00:00Z", "updated_at": "2025-12-01T10:00:01Z"
}
```

**エラー:** 400（金額範囲外、重複order_id）

### 3.2 GET /api/v1/payments/{payment_id}
### 3.3 GET /api/v1/payments/order/{order_id}
### 3.4 POST /api/v1/payments/refund

---

## 4. 通知サービスAPI

### 4.1 POST /api/v1/notifications/email — 1件のメール送信

> **注記:** 1リクエストにつき**1件のメール**。レート制限: 10件/秒。

**リクエスト:**
```json
{
    "order_id": 1,
    "to_email": "tanaka@example.co.jp",
    "template_name": "ORDER_CONFIRMATION",
    "template_data": {"order_id": 1, "customer_name": "田中太郎", "total_amount": 183100, "currency": "JPY", "item_count": 2}
}
```

**レスポンス (201):**
```json
{
    "id": 1, "order_id": 1, "channel": "email",
    "template_name": "ORDER_CONFIRMATION",
    "recipient": "tanaka@example.co.jp",
    "subject": "ご注文確認 — 注文番号 #1",
    "body": "田中太郎 様\n\nご注文ありがとうございます。...",
    "status": "sent",
    "sent_at": "2025-12-01T10:00:01Z", "created_at": "2025-12-01T10:00:01Z"
}
```

### 4.2 POST /api/v1/notifications/sms — 1件のSMS送信
### 4.3 GET /api/v1/notifications/{notification_id}
### 4.4 GET /api/v1/notifications/order/{order_id}

---

## 5. サービス間APIコントラクト

### 5.1 注文サービス → 決済サービス

| 項目 | 値 |
|------|-----|
| エンドポイント | POST http://localhost:8001/api/v1/payments |
| トリガー | 注文作成 |
| ペイロード | `{"order_id": N, "amount": N.N, "currency": "JPY"}` |
| タイムアウト | 30秒 |
| 失敗時 | 注文ステータスを保留中に戻す |

### 5.2 注文サービス → 通知サービス

| 項目 | 値 |
|------|-----|
| エンドポイント | POST http://localhost:8002/api/v1/notifications/email |
| トリガー | 注文作成、ステータス変更、キャンセル |
| タイムアウト | 10秒 |
| 失敗時 | ログ記録、注文処理は継続 |

### 5.3 決済サービス → 注文サービス

| 項目 | 値 |
|------|-----|
| エンドポイント | POST http://localhost:8000/api/v1/orders/{order_id}/webhook |
| トリガー | 決済ステータス変更 |
| ペイロード | `{"payment_status": "completed", "transaction_id": "uuid"}` |

---

## 6. レート制限

| サービス | エンドポイント | 制限 |
|---------|--------------|------|
| 通知サービス | POST /email, POST /sms | **10リクエスト/秒** |
| 注文サービス | 全エンドポイント | 明示的な制限なし |
| 決済サービス | 全エンドポイント | 明示的な制限なし |

---

## 7. API制限事項サマリー

1. **全エンドポイントが単一エンティティ操作のみ。** バッチ/一括エンドポイントは全サービスに存在しない。
2. **一括注文作成APIなし。** 10,000件の処理には10,000回の個別POSTコールが必要。
3. **バッチ決済APIなし。** 1取引あたり最大100万円。
4. **一括通知APIなし。** レート制限10件/秒で10,000件は最低約17分。
5. **サービス間コントラクトは単一注文ペイロードを前提。**
6. **リトライ・サーキットブレーカーなし。**
7. **フロントエンドがN+1クエリパターンを使用。** 決済・通知ページは一覧取得エンドポイントがないため。
8. **フロントエンドに一括インポートUIなし。** CSVアップロード、ドラッグ&ドロップ、バッチ作成フォームは存在しない。