ORDER_API_QUICK_REF.md

# Order API Quick Reference

## Endpoints

### 1. Create Order
```
POST /orders/create
Authorization: Bearer <customer_token>
```

**Request Body:**
```json
{
  "items": [
    {
      "catalogue_id": "string",
      "quantity": 1
    }
  ],
  "shipping_address": {
    "address_type": "shipping",
    "line1": "string",
    "city": "string",
    "state": "string",
    "postal_code": "string",
    "country": "India"
  },
  "billing_address": {  // Optional, defaults to shipping
    "address_type": "billing",
    "line1": "string",
    "city": "string",
    "state": "string",
    "postal_code": "string",
    "country": "India"
  },
  "customer_name": "string",
  "customer_phone": "string",
  "customer_email": "string",
  "payment_method": "string",
  "notes": "string"
}
```

**Response (201):**
```json
{
  "success": true,
  "message": "Order created successfully",
  "data": {
    "sales_order_id": "uuid",
    "order_number": "ORD-20260207-0001",
    "merchant_id": "uuid",
    "order_date": "2026-02-07T10:30:00",
    "status": "pending",
    "customer_id": "string",
    "subtotal": 1000.00,
    "total_tax": 180.00,
    "grand_total": 1180.00,
    "payment_status": "pending",
    "fulfillment_status": "pending",
    "items": [...],
    "addresses": [...]
  }
}
```

---

### 2. Get Order Details
```
GET /orders/{order_id}
Authorization: Bearer <customer_token>
```

**Response (200):**
```json
{
  "success": true,
  "data": {
    "sales_order_id": "uuid",
    "order_number": "ORD-20260207-0001",
    "status": "pending",
    "grand_total": 1180.00,
    "items": [
      {
        "id": "uuid",
        "product_id": "CAT-001",
        "product_name": "Product Name",
        "quantity": 2,
        "unit_price": 500.00,
        "line_total": 1180.00
      }
    ],
    "addresses": [...]
  }
}
```

---

### 3. List Orders (Simple)
```
GET /orders/?skip=0&limit=10
Authorization: Bearer <customer_token>
```

**Response (200):**
```json
{
  "success": true,
  "data": {
    "total": 25,
    "orders": [...]
  }
}
```

---

### 4. List Orders (Advanced with Projection)
```
POST /orders/list
Authorization: Bearer <customer_token>
```

**Request Body:**
```json
{
  "filters": {
    "status": "pending",
    "payment_status": "pending",
    "fulfillment_status": "pending"
  },
  "skip": 0,
  "limit": 10,
  "projection_list": [
    "sales_order_id",
    "order_number",
    "order_date",
    "status",
    "grand_total",
    "payment_status"
  ],
  "sort_by": "created_at",
  "sort_order": "desc"
}
```

**Response (200):**
```json
{
  "total": 25,
  "skip": 0,
  "limit": 10,
  "orders": [
    {
      "sales_order_id": "uuid",
      "order_number": "ORD-20260207-0001",
      "order_date": "2026-02-07T10:30:00",
      "status": "pending",
      "grand_total": 1180.00,
      "payment_status": "pending"
    }
  ]
}
```

---

## Order Statuses

### Order Status
- `pending` - Order created, awaiting confirmation
- `confirmed` - Order confirmed by merchant
- `processing` - Order being prepared
- `shipped` - Order shipped
- `delivered` - Order delivered
- `cancelled` - Order cancelled

### Payment Status
- `pending` - Payment not received
- `paid` - Payment completed
- `failed` - Payment failed
- `refunded` - Payment refunded

### Fulfillment Status
- `pending` - Not yet fulfilled
- `processing` - Being prepared
- `shipped` - Shipped to customer
- `delivered` - Delivered to customer
- `cancelled` - Fulfillment cancelled

---

## Error Responses

### 400 Bad Request
```json
{
  "detail": "Product not found: CAT-001"
}
```

### 401 Unauthorized
```json
{
  "detail": "Could not validate credentials"
}
```

### 403 Forbidden
```json
{
  "detail": "This endpoint requires customer authentication"
}
```

### 404 Not Found
```json
{
  "detail": "Order not found"
}
```

---

## Authentication

Get customer token from auth-ms:

```bash
# 1. Request OTP
curl -X POST "http://localhost:8001/auth/customer/request-otp" \
  -H "Content-Type: application/json" \
  -d '{"phone_number": "+919876543210"}'

# 2. Verify OTP and get token
curl -X POST "http://localhost:8001/auth/customer/verify-otp" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+919876543210",
    "otp": "123456"
  }'

# Response includes access_token
{
  "access_token": "eyJhbGc...",
  "token_type": "bearer"
}
```

---

## Testing with cURL

### Create Order
```bash
curl -X POST "http://localhost:8000/orders/create" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [{"catalogue_id": "CAT-001", "quantity": 2}],
    "shipping_address": {
      "address_type": "shipping",
      "line1": "123 Main St",
      "city": "Mumbai",
      "state": "Maharashtra",
      "postal_code": "400001",
      "country": "India"
    },
    "customer_name": "John Doe",
    "payment_method": "cod"
  }'
```

### Get Order
```bash
curl -X GET "http://localhost:8000/orders/ORDER_ID" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

### List Orders with Projection
```bash
curl -X POST "http://localhost:8000/orders/list" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "projection_list": ["order_number", "status", "grand_total"],
    "limit": 5
  }'
```

---

## Python Example

```python
import requests

# Get token
token_response = requests.post(
    "http://localhost:8001/auth/customer/verify-otp",
    json={"phone_number": "+919876543210", "otp": "123456"}
)
token = token_response.json()["access_token"]

# Create order
headers = {"Authorization": f"Bearer {token}"}
order_data = {
    "items": [{"catalogue_id": "CAT-001", "quantity": 2}],
    "shipping_address": {
        "address_type": "shipping",
        "line1": "123 Main St",
        "city": "Mumbai",
        "state": "Maharashtra",
        "postal_code": "400001",
        "country": "India"
    }
}

response = requests.post(
    "http://localhost:8000/orders/create",
    headers=headers,
    json=order_data
)

order = response.json()["data"]
print(f"Order created: {order['order_number']}")
```

---

## Database Tables

### trans.sales_orders
Main order table with customer, merchant, and financial information.

### trans.sales_order_items
Order line items with product details, quantities, and pricing.

### trans.sales_order_addresses
Shipping and billing addresses for orders.

---

## Key Features

✅ Customer JWT authentication  
✅ Product validation from MongoDB  
✅ Single merchant per order validation  
✅ Automatic tax calculation  
✅ Unique order number generation  
✅ PostgreSQL persistence (trans schema)  
✅ Projection list support (API standard)  
✅ Filtering and sorting  
✅ Comprehensive error handling