# API Specifications

| Field | Value |
|-------|-------|
| Document ID | API-ECOM-001 |
| Version | 1.0 |
| Date | 2025-12-01 |
| Status | Approved |

---

## 1. Overview

This document defines the complete API contracts for all three E-Commerce platform services.

| Service | Base URL | Version |
|---------|----------|---------|
| Order Service | http://localhost:8000/api/v1 | v1 |
| Payment Service | http://localhost:8001/api/v1 | v1 |
| Notification Service | http://localhost:8002/api/v1 | v1 |
| Frontend Admin Dashboard | http://localhost:5173 | — |

### Common Error Response

```json
{"detail": "Error description string"}
```

---

## 2. Order Service API

### 2.1 POST /api/v1/orders/ — Create Single Order

> **NOTE:** Creates ONE order per request. No bulk/batch creation endpoint exists.

**Request:**
```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"
}
```

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

**Side Effects:**
- Calls Payment Service: `POST /api/v1/payments`
- Calls Notification Service: `POST /api/v1/notifications/email`

### 2.2 GET /api/v1/orders/?skip=0&limit=20

**Response (200):** Array of OrderResponse objects.

### 2.3 GET /api/v1/orders/{order_id}

**Response (200):** Single OrderResponse. **404** if not found.

### 2.4 PUT /api/v1/orders/{order_id}/status

**Request:** `{"status": "shipped"}`
**Side Effect:** If status=shipped, sends ORDER_SHIPPED notification.

### 2.5 DELETE /api/v1/orders/{order_id}

**Side Effects:**
- Calls Payment Service: `POST /api/v1/payments/refund`
- Calls Notification Service: `POST /api/v1/notifications/email` (ORDER_CANCELLED)

### 2.6 POST /api/v1/orders/{order_id}/webhook

**Request:** `{"payment_status": "completed", "transaction_id": "uuid"}`

---

## 3. Payment Service API

### 3.1 POST /api/v1/payments/ — Create Single Payment

> **NOTE:** Processes ONE payment per request. Amount: min 100 JPY, max 1,000,000 JPY.

**Request:**
```json
{"order_id": 1, "amount": 183100.0, "currency": "JPY"}
```

**Response (201 Created):**
```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"
}
```

**Error Cases:**
- `400`: Amount below 100 JPY or above 1,000,000 JPY
- `400`: Duplicate order_id (payment already exists)

### 3.2 GET /api/v1/payments/{payment_id}

### 3.3 GET /api/v1/payments/order/{order_id}

Returns payment for specific order (1:1 relationship).

### 3.4 POST /api/v1/payments/refund

**Request:**
```json
{"payment_id": 1, "reason": "Order cancelled by customer"}
```

**Response (201):**
```json
{
    "id": 1,
    "payment_id": 1,
    "amount": 183100.0,
    "reason": "Order cancelled by customer",
    "status": "completed",
    "created_at": "2025-12-01T10:05:00Z"
}
```

---

## 4. Notification Service API

### 4.1 POST /api/v1/notifications/email — Send Single Email

> **NOTE:** Sends ONE email per request. Rate limit: 10/second.

**Request:**
```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
    }
}
```

**Response (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

Same structure with `to_phone` instead of `to_email`.

### 4.3 GET /api/v1/notifications/{notification_id}

### 4.4 GET /api/v1/notifications/order/{order_id}

Returns array of all notifications for an order.

---

## 5. Cross-Service API Contracts

### 5.1 Order Service → Payment Service

| Field | Value |
|-------|-------|
| Caller | Order Service |
| Endpoint | POST http://localhost:8001/api/v1/payments |
| Trigger | Order creation |
| Payload | `{"order_id": N, "amount": N.N, "currency": "JPY"}` |
| Expected Response | 201 with payment details |
| Timeout | 30 seconds |
| On Failure | Order status reverts to PENDING |

### 5.2 Order Service → Notification Service

| Field | Value |
|-------|-------|
| Caller | Order Service |
| Endpoint | POST http://localhost:8002/api/v1/notifications/email |
| Trigger | Order creation, status change, cancellation |
| Payload | `{"order_id": N, "to_email": "...", "template_name": "...", "template_data": {...}}` |
| Expected Response | 201 with notification details |
| Timeout | 10 seconds |
| On Failure | Logged, order creation continues |

### 5.3 Payment Service → Order Service

| Field | Value |
|-------|-------|
| Caller | Payment Service |
| Endpoint | POST http://localhost:8000/api/v1/orders/{order_id}/webhook |
| Trigger | Payment status change |
| Payload | `{"payment_status": "completed", "transaction_id": "uuid"}` |
| Expected Response | 200 OK |
| Timeout | 10 seconds |

---

## 6. Error Codes

| Code | Meaning | Services |
|------|---------|----------|
| 400 | Bad Request / Validation Error | All |
| 404 | Resource Not Found | All |
| 422 | Schema Validation Error (Pydantic) | All |
| 500 | Internal Server Error | All |

---

## 7. Rate Limits

| Service | Endpoint | Limit |
|---------|----------|-------|
| Notification Service | POST /email, POST /sms | **10 requests/second** |
| Order Service | All endpoints | No explicit limit |
| Payment Service | All endpoints | No explicit limit |

---

## 8. API Limitations Summary

1. **All endpoints handle single-entity operations only.** There are no batch/bulk endpoints for any service.
2. **No bulk order creation API.** Processing 10,000 orders requires 10,000 individual POST calls to Order Service.
3. **No batch payment API.** Each order requires its own payment call. Amount limit of 1,000,000 JPY per single transaction.
4. **No bulk notification API.** Rate limit of 10/second means 10,000 notifications take ~17 minutes minimum.
5. **Cross-service contracts assume single-order payloads.** All inter-service API calls carry one order_id per request.
6. **No retry or circuit breaker on any cross-service call.** Failures are logged but not retried.
7. **Frontend uses N+1 query pattern** for payments and notifications pages due to missing list-all endpoints.
8. **Frontend has no bulk import UI.** No CSV upload, no drag-and-drop file import, no batch creation form.