# 08-api-specification.md

# API Specification Document (Laravel eCommerce Backend)

**Version:** 1.0
**Project Type:** Single Vendor eCommerce
**Architecture:** Modular + Service Layer + REST API Ready
**Client Types:** Web Frontend + Admin Panel + Future Mobile App

---

## 1. PURPOSE OF THIS DOCUMENT

This file defines:

- All API endpoints
- Request/Response structure
- Authentication rules (future-ready)
- Business logic mapping
- Status codes standard

**Goal:** Backend should be usable by:

- Web frontend (Blade / Vue / React)
- Admin panel
- Future mobile app

---

## 2. API DESIGN PRINCIPLE

We follow:

- REST API structure
- JSON response format
- Stateless design
- Versioned APIs

**Base URL:**

```
/api/v1/
```

---

## 3. GLOBAL RESPONSE FORMAT

### Success Response

```json
{
  "status": true,
  "message": "Success",
  "data": {}
}
```

### Error Response

```json
{
  "status": false,
  "message": "Error message",
  "errors": {}
}
```

---

## 4. PUBLIC (NO AUTH) APIs

These APIs are used by website visitors.

---

### 4.1 PRODUCT APIs

#### Get Products List

```
GET /api/v1/products
```

**Query params:**

| Param        | Description                                      |
|--------------|--------------------------------------------------|
| `page`       | Page number                                      |
| `limit`      | Results per page                                 |
| `category_id`| Filter by category                               |
| `brand_id`   | Filter by brand                                  |
| `min_price`  | Minimum price filter                             |
| `max_price`  | Maximum price filter                             |
| `sort_by`    | `newest`, `price_low`, `price_high`, `popular`   |

---

#### Get Single Product

```
GET /api/v1/products/{slug}
```

**Response includes:**

- Product info
- Images
- Variants
- Related products

---

#### Search Products

```
GET /api/v1/products/search?q=keyword
```

---

### 4.2 CATEGORY APIs

```
GET /api/v1/categories
```

**Returns:**

- Category tree
- Subcategories

---

### 4.3 BRAND APIs

```
GET /api/v1/brands
```

---

## 5. CART APIs _(SESSION BASED)_

#### Add to Cart

```
POST /api/v1/cart/add
```

**Body:**

```json
{
  "product_id": 1,
  "variant_id": null,
  "qty": 2
}
```

---

#### Get Cart

```
GET /api/v1/cart
```

---

#### Update Cart

```
POST /api/v1/cart/update
```

---

#### Remove Item

```
POST /api/v1/cart/remove
```

---

#### Clear Cart

```
POST /api/v1/cart/clear
```

---

## 6. CHECKOUT APIs _(CRITICAL FLOW)_

#### Place Order (Guest Checkout)

```
POST /api/v1/checkout
```

**Body:**

```json
{
  "customer_name": "John Doe",
  "customer_phone": "017XXXXXXXX",
  "customer_alt_phone": "018XXXXXXXX",
  "address": "Full Address Here",
  "area_id": 1,
  "city_id": 1,
  "payment_method": "cod",
  "coupon_code": null,
  "note": "optional"
}
```

**Response:**

```json
{
  "status": true,
  "message": "Order placed successfully",
  "data": {
    "order_id": 101,
    "invoice_no": "INV-10001",
    "total": 1500
  }
}
```

---

## 7. ORDER APIs

#### Track Order

```
GET /api/v1/order/track?phone=017XXXXXX
```

**OR**

```
GET /api/v1/order/track?invoice=INV-10001
```

---

#### Get Order Details

```
GET /api/v1/orders/{id}
```

---

## 8. COUPON APIs

#### Apply Coupon

```
POST /api/v1/coupon/apply
```

**Body:**

```json
{
  "code": "DISCOUNT10",
  "subtotal": 2000
}
```

---

## 9. SHIPPING APIs

#### Get Areas

```
GET /api/v1/areas?city_id=1
```

#### Get Shipping Cost

```
POST /api/v1/shipping/calculate
```

---

## 10. CUSTOMER (GUEST LOGIC)

No authentication APIs required.

But system tracks:

- Phone number
- Session ID
- IP address

---

## 11. ADMIN APIs _(AUTH REQUIRED)_

**Prefix:**

```
/api/v1/admin/
```

---

### 11.1 DASHBOARD

```
GET /api/v1/admin/dashboard
```

**Returns:**

- Sales stats
- Orders stats
- Profit stats

---

### 11.2 PRODUCT MANAGEMENT

```
GET    /api/v1/admin/products
POST   /api/v1/admin/products
PUT    /api/v1/admin/products/{id}
DELETE /api/v1/admin/products/{id}
```

---

### 11.3 ORDER MANAGEMENT

```
GET  /api/v1/admin/orders
GET  /api/v1/admin/orders/{id}
POST /api/v1/admin/orders/{id}/status
```

---

### 11.4 INVENTORY

```
GET  /api/v1/admin/inventory
POST /api/v1/admin/inventory/update
```

---

### 11.5 EXPENSES

```
GET  /api/v1/admin/expenses
POST /api/v1/admin/expenses
```

---

### 11.6 PROFIT / LOSS REPORT

```
GET /api/v1/admin/reports/profit-loss
```

---

### 11.7 SETTINGS

```
GET  /api/v1/admin/settings
POST /api/v1/admin/settings/update
```

---

### 11.8 COURIER APIs

```
POST /api/v1/admin/courier/create-shipment
GET  /api/v1/admin/courier/track/{id}
```

---

## 12. AUTHENTICATION _(ADMIN ONLY)_

#### Login

```
POST /api/v1/admin/login
```

**Response:** `token` (JWT / Sanctum)

---

#### Logout

```
POST /api/v1/admin/logout
```

---

## 13. STATUS CODES STANDARD

| Code  | Meaning           |
|-------|-------------------|
| `200` | Success           |
| `201` | Created           |
| `400` | Bad Request       |
| `401` | Unauthorized      |
| `403` | Forbidden         |
| `404` | Not Found         |
| `422` | Validation Error  |
| `500` | Server Error      |

---

## 14. SECURITY RULES

- Rate limiting enabled
- CSRF protection (web routes)
- Sanctum for admin APIs
- Input validation required
- SQL injection prevention

---

## 15. PERFORMANCE RULES

- Pagination required on list APIs
- Cache product list
- Cache categories
- Use eager loading
- Avoid N+1 queries

---

## 16. FUTURE EXTENSIONS

This API system can easily support:

- Mobile App (Flutter / React Native)
- POS System
- Multi warehouse system
- Multi admin system
- Marketplace upgrade

---

## 17. FINAL GOAL

This API design ensures:

- ✅ Clean backend structure
- ✅ Easy frontend integration
- ✅ Scalable architecture
- ✅ AI-friendly code generation
- ✅ Future mobile app readiness