# 📚 SUNNAGHAR API DOCUMENTATION

## Base URL
```
https://api.yourdomain.com/api/v1
(Development: http://127.0.0.1:8000/api/v1)
```

## Authentication
API endpoints are **public** (no authentication required). CORS enabled for all origins.

---

## PRODUCTS API

### Get All Products
```http
GET /api/v1/products?category=shirts&page=1&limit=12
```

**Query Parameters:**
- `category` (optional) - Filter by category slug
- `page` (optional) - Page number (default: 1)
- `limit` (optional) - Items per page (default: 12)
- `search` (optional) - Search by product name

**Response:**
```json
{
  "data": [
    {
      "id": 1,
      "slug": "product-name",
      "name": "Product Name",
      "price": 99.99,
      "discount_price": 79.99,
      "category_id": 1,
      "category": {
        "id": 1,
        "name": "Category Name",
        "slug": "category-slug"
      },
      "image": "/storage/products/img1.jpg",
      "colors": ["Red", "Blue"],
      "sizes": ["S", "M", "L"],
      "fabrics": ["Cotton", "Polyester"],
      "description": "..."
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 12,
    "total": 45
  }
}
```

---

### Get Single Product
```http
GET /api/v1/products/product-slug
```

**Response:**
```json
{
  "id": 1,
  "slug": "product-slug",
  "name": "Product Name",
  "price": 99.99,
  "discount_price": 79.99,
  "category_id": 1,
  "category": {
    "id": 1,
    "name": "Category Name",
    "slug": "category-slug"
  },
  "image": "/storage/products/img1.jpg",
  "colors": ["Red", "Blue"],
  "sizes": ["S", "M", "L"],
  "fabrics": ["Cotton", "Polyester"],
  "description": "Product description here",
  "created_at": "2026-04-12T10:00:00Z"
}
```

---

## CATEGORIES API

### Get All Categories
```http
GET /api/v1/categories
```

**Response:**
```json
{
  "data": [
    {
      "id": 1,
      "name": "Shirts",
      "slug": "shirts",
      "image": "/storage/categories/img1.jpg",
      "description": "Men's and women's shirts",
      "is_active": true,
      "sort_order": 1
    }
  ]
}
```

---

### Get Category by Slug
```http
GET /api/v1/categories/shirts
```

**Response:**
```json
{
  "id": 1,
  "name": "Shirts",
  "slug": "shirts",
  "image": "/storage/categories/img1.jpg",
  "description": "Men's and women's shirts",
  "is_active": true,
  "product_count": 25
}
```

---

## HOMEPAGE CONTENT APIs

### Get Hero Slides
```http
GET /api/v1/hero-slides
```

**Response:**
```json
[
  {
    "id": 1,
    "title": "Summer Collection",
    "subtitle": "New arrivals",
    "image": "/storage/hero-slides/img1.jpg",
    "cta_text": "Shop Now",
    "cta_link": "/collections",
    "sort_order": 1
  }
]
```

---

### Get Banners
```http
GET /api/v1/banners
```

**Query Parameters:**
- Filters by `is_active=true` and date range automatically

**Response:**
```json
[
  {
    "id": 1,
    "title": "Spring Sale",
    "image": "/storage/banners/spring-sale.jpg",
    "link": "/collections",
    "start_date": "2026-04-01",
    "end_date": "2026-04-30",
    "is_active": true
  }
]
```

---

### Get Current Flash Sale
```http
GET /api/v1/flash-sale
```

**Response:**
```json
{
  "id": 1,
  "title": "Lightning Deal",
  "description": "50% off selected items",
  "discount_percentage": 50,
  "start_date": "2026-04-12T00:00:00Z",
  "end_date": "2026-04-12T23:59:59Z",
  "products": [
    {
      "id": 1,
      "name": "Product 1",
      "slug": "product-1",
      "price": 99.99,
      "discount_price": 49.99,
      "image": "/storage/products/img1.jpg"
    }
  ]
}
```

---

### Get Site Settings
```http
GET /api/v1/settings
```

**Response:**
```json
{
  "site_name": "Sunnaghar",
  "currency": "BDT",
  "shipping_cost": 50,
  "currency_symbol": "৳",
  "free_shipping_threshold": 500,
  "business_email": "info@sunnaghar.com",
  "phone": "+880123456789",
  "address": "Dhaka, Bangladesh"
}
```

---

## ORDERS API

### Create Order
```http
POST /api/v1/orders
Content-Type: application/json

{
  "order_number": "ORD-123456",
  "items": [
    {
      "product_id": 1,
      "quantity": 2,
      "price": 99.99
    }
  ],
  "shipping_info": {
    "full_name": "John Doe",
    "email": "john@example.com",
    "phone": "01712345678",
    "address": "123 Street",
    "city": "Dhaka",
    "postal_code": "1000",
    "country": "Bangladesh"
  },
  "payment_info": {
    "method": "bkash|nagad|roket|card|cod",
    "transaction_id": "TXN123"
  },
  "subtotal": 199.98,
  "shipping_cost": 50,
  "discount": 0,
  "coupon_code": "CODE123",
  "notes": "Optional delivery notes"
}
```

**Response:**
```json
{
  "success": true,
  "message": "Order created successfully",
  "order_number": "ORD-123456",
  "id": 1
}
```

---

### Get Order by Number
```http
GET /api/v1/orders/ORD-123456
```

**Response:**
```json
{
  "id": 1,
  "order_number": "ORD-123456",
  "customer_id": 1,
  "status": "processing",
  "items": [
    {
      "id": 1,
      "product_id": 1,
      "quantity": 2,
      "price": 99.99
    }
  ],
  "shipping_info": {
    "full_name": "John Doe",
    "email": "john@example.com",
    "phone": "01712345678",
    "address": "123 Street",
    "city": "Dhaka",
    "postal_code": "1000"
  },
  "payment_info": {
    "method": "bkash",
    "transaction_id": "TXN123"
  },
  "subtotal": 199.98,
  "shipping_cost": 50,
  "discount": 0,
  "total": 249.98,
  "coupon_code": "CODE123",
  "status_history": [
    {
      "status": "pending",
      "timestamp": "2026-04-12T10:00:00Z",
      "notes": "Order received"
    },
    {
      "status": "processing",
      "timestamp": "2026-04-12T11:00:00Z",
      "notes": "Payment verified"
    }
  ],
  "created_at": "2026-04-12T10:00:00Z",
  "updated_at": "2026-04-12T11:00:00Z"
}
```

---

### Get Orders by Email
```http
POST /api/v1/orders/by-email
Content-Type: application/json

{
  "email": "john@example.com"
}
```

**Response:**
```json
{
  "data": [
    {
      "id": 1,
      "order_number": "ORD-123456",
      "status": "delivered",
      "total": 249.98,
      "created_at": "2026-04-12T10:00:00Z"
    }
  ]
}
```

---

## COUPONS API

### Validate Coupon
```http
POST /api/v1/coupons/validate
Content-Type: application/json

{
  "code": "SAVE10",
  "order_total": 199.98
}
```

**Response (Valid):**
```json
{
  "success": true,
  "message": "Coupon applied successfully",
  "code": "SAVE10",
  "discount_type": "percentage",
  "discount_value": 10,
  "discount_amount": 20.00,
  "new_total": 179.98
}
```

**Response (Invalid):**
```json
{
  "success": false,
  "message": "Coupon code expired or invalid"
}
```

---

## NEWSLETTER API

### Subscribe
```http
POST /api/v1/newsletter/subscribe
Content-Type: application/json

{
  "email": "john@example.com"
}
```

**Response (Success):**
```json
{
  "success": true,
  "message": "আপনার ইমেইল সফলভাবে যুক্ত হয়েছে। ধন্যবাদ!"
}
```

**Response (Error):**
```json
{
  "success": false,
  "message": "এই ইমেইল ইতিমধ্যে নিবন্ধিত রয়েছে।"
}
```

---

### Unsubscribe
```http
POST /api/v1/newsletter/unsubscribe
Content-Type: application/json

{
  "email": "john@example.com"
}
```

**Response:**
```json
{
  "success": true,
  "message": "আপনি সফলভাবে আনসাবস্ক্রাইব হয়েছেন।"
}
```

---

## CONTACT API

### Submit Contact Message
```http
POST /api/v1/contact
Content-Type: application/json

{
  "name": "John Doe",
  "email": "john@example.com",
  "subject": "Inquiry about products",
  "message": "I have a question about your products..."
}
```

**Response:**
```json
{
  "success": true,
  "message": "আপনার বার্তা সফলভাবে পাঠানো হয়েছে।"
}
```

---

## ERROR RESPONSES

All error responses follow this format:

```json
{
  "success": false,
  "message": "Error description"
}
```

**Common HTTP Status Codes:**
- `200 OK` - Success
- `400 Bad Request` - Invalid request data
- `404 Not Found` - Resource not found
- `500 Server Error` - Server error

---

## CORS Headers

All endpoints support CORS with the following headers:

```
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
Access-Control-Allow-Headers: Content-Type, Authorization, X-Requested-With
```

---

## Rate Limiting

Currently no rate limiting implemented. For production, consider implementing:
- 100 requests per minute per IP for public endpoints
- 1000 requests per minute for admin endpoints

---

## Caching

Responses are cached for improved performance:

| Endpoint | TTL |
|----------|-----|
| /api/v1/products | 60s |
| /api/v1/categories | 60s |
| /api/v1/hero-slides | 60s |
| /api/v1/banners | 60s |
| /api/v1/settings | 300s |
| /api/v1/flash-sale | 30s |

---

## Implementation Examples

### JavaScript/Next.js (Fetch Products)
```javascript
const response = await fetch('https://api.yourdomain.com/api/v1/products?category=shirts');
const products = await response.json();
```

### JavaScript/Next.js (Create Order)
```javascript
const response = await fetch('https://api.yourdomain.com/api/v1/orders', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    order_number: 'ORD-123456',
    items: [...],
    shipping_info: {...},
    payment_info: {...},
    subtotal: 199.98,
    shipping_cost: 50,
    discount: 0
  })
});
const result = await response.json();
```

### Angular HttpClient (Get Single Product)
```typescript
this.http.get(`/api/v1/products/product-slug`).subscribe(product => {
  console.log(product);
});
```

---

**Version:** 1.0.0  
**Last Updated:** April 12, 2026  
**Status:** Production Ready ✅