# API Endpoints & Routes Reference

## 🛒 Shopping Cart Endpoints

### View Shopping Cart
```
GET /customer/cart
Route Name: customer.cart.index
Auth: Required (Customer role)
Response: Cart items with vehicle details, totals, discounts
```

### Add Item to Cart
```
POST /customer/cart/{vehicle}/add
Route Name: customer.cart.add
Auth: Required (Customer role)
Params: 
  - {vehicle}: Vehicle ID
  - quantity: (optional, default: 1)
Response: Redirect to referrer with success message
```

### Update Cart Item Quantity
```
PUT /customer/cart/{cart}
Route Name: customer.cart.update
Auth: Required (Customer role)
Payload:
  {
    "quantity": integer (>0)
  }
Response: Redirect with success message
```

### Remove Item from Cart
```
DELETE /customer/cart/{cart}
Route Name: customer.cart.remove
Auth: Required (Customer role)
Response: Redirect with success message
```

### Clear All Cart Items
```
POST /customer/cart/clear
Route Name: customer.cart.clear
Auth: Required (Customer role)
Response: Redirect with success message
```

### Get Cart Item Count
```
GET /customer/cart/count
Route Name: customer.cart.count
Auth: Required (Customer role)
Response: JSON {count: integer}
```

## 🛍️ Checkout Endpoints

### View Checkout Page
```
GET /customer/checkout
Route Name: customer.checkout.index
Auth: Required (Customer role)
Response: Checkout page with cart items and form
```

### Place Order (Checkout)
```
POST /customer/checkout
Route Name: customer.checkout.store
Auth: Required (Customer role)
Payload:
  {
    "shipping_address": "required|string",
    "payment_method": "required|in:card,bank_transfer,cash_on_delivery",
    "notes": "nullable|string"
  }
Response: Redirect to order show page
Creates:
  - Order record
  - OrderItem records from cart
  - Payment record
  - Clears cart
```

## 📦 Customer Order Endpoints

### List Customer Orders
```
GET /customer/orders
Route Name: customer.orders.index
Auth: Required (Customer role)
Query Params:
  - page: (optional, defaults to 1)
Response: Paginated list of customer's orders
```

### View Order Details
```
GET /customer/orders/{order}
Route Name: customer.orders.show
Auth: Required (Customer role, must be order owner)
Params:
  - {order}: Order ID
Response: Order details with items, payments, timeline
```

### Create Order (Direct, from vehicle page)
```
POST /customer/orders
Route Name: customer.orders.store
Auth: Required (Customer role)
Payload:
  {
    "vehicle_id": "required|exists:vehicles,id",
    "shipping_address": "required|string",
    "notes": "nullable|string"
  }
Response: Redirect to order show page
Note: Direct order creation. Cart checkout is preferred.
```

## 🚚 Seller Order Endpoints

### List Seller's Orders
```
GET /seller/orders
Route Name: seller.orders.index
Auth: Required (Seller role)
Query Params:
  - page: (optional)
Response: Orders for seller's vehicles with stats
Stats Included:
  - total_orders
  - pending_orders
  - shipped_orders
  - delivered_orders
```

### View Order Details (Seller)
```
GET /seller/orders/{order}
Route Name: seller.orders.show
Auth: Required (Seller role, must have items in order)
Params:
  - {order}: Order ID
Response: Order details, customer info, items with images
```

### Update Order Status (Seller)
```
PUT /seller/orders/{order}
Route Name: seller.orders.update
Auth: Required (Seller role, must have items in order)
Params:
  - {order}: Order ID
Payload:
  {
    "status": "required|in:pending,paid,shipped,delivered,cancelled",
    "tracking_number": "nullable|string|max:100",
    "notes": "nullable|string|max:1000"
  }
Response: Redirect back with success message
```

## 👨‍💼 Admin Order Endpoints

### List All Orders
```
GET /admin/orders
Route Name: admin.orders.index
Auth: Required (Admin role)
Query Params:
  - page: (optional)
Response: All system orders with stats dashboard
Stats Included:
  - total_orders
  - pending_orders
  - paid_orders
  - shipped_orders
  - delivered_orders
  - total_revenue
```

### View Order Details (Admin)
```
GET /admin/orders/{order}
Route Name: admin.orders.show
Auth: Required (Admin role)
Params:
  - {order}: Order ID
Response: Complete order details
```

### Update Order (Admin)
```
PUT /admin/orders/{order}
Route Name: admin.orders.update
Auth: Required (Admin role)
Params:
  - {order}: Order ID
Payload:
  {
    "status": "required|in:pending,paid,shipped,delivered,cancelled",
    "tracking_number": "nullable|string|max:255",
    "shipping_cost": "nullable|numeric|min:0"
  }
Response: Redirect to order show page
```

## 📊 Dashboard Endpoints

### Customer Dashboard
```
GET /customer/dashboard
Route Name: customer.dashboard
Auth: Required (Customer role)
Response: Customer overview page
```

### Seller Dashboard
```
GET /seller/dashboard
Route Name: seller.dashboard
Auth: Required (Seller role)
Response: Seller overview with stats
Stats:
  - vehicleCount
  - availableVehicles
  - totalOrders
  - pendingOrders
  - totalRevenue
```

### Admin Dashboard
```
GET /admin/dashboard
Route Name: admin.dashboard
Auth: Required (Admin role)
Response: Admin overview
Stats:
  - sellerCount
  - vehicleCount
  - availableCount
  - soldCount
  - featuredCount
  - clearanceCount
  - vehicleTypes breakdown
```

## 🚗 Vehicle Endpoints (Public)

### Home/Browse Vehicles
```
GET /
Route Name: home
Auth: Public
Response: Vehicle catalog with search/filter
```

### Vehicle Details
```
GET /vehicles/{vehicle}
Route Name: vehicles.show
Auth: Public
Params:
  - {vehicle}: Vehicle ID
Response: Vehicle details with "Add to Cart" button (if logged in)
```

## 🔐 Authentication Endpoints

### Login
```
GET  /login
POST /login
```

### Register
```
GET  /register
POST /register
Includes role selection: admin, seller, customer
```

### Logout
```
POST /logout
```

## 📋 Request/Response Models

### Order Response Model
```json
{
  "id": 1,
  "user_id": 5,
  "status": "pending",
  "total_price": 45000,
  "discount_amount": 5000,
  "shipping_cost": 100,
  "shipping_address": "123 Main St, City",
  "tracking_number": "TRACK123",
  "notes": "Leave at door",
  "order_date": "2026-04-08T10:00:00Z",
  "shipped_at": null,
  "delivered_at": null,
  "created_at": "2026-04-08T10:00:00Z",
  "updated_at": "2026-04-08T10:00:00Z",
  "user": { /* User object */ },
  "items": [
    {
      "id": 1,
      "order_id": 1,
      "vehicle_id": 10,
      "quantity": 1,
      "price": 50000,
      "discount_applied": 5000,
      "vehicle": { /* Vehicle object */ }
    }
  ],
  "payments": [
    {
      "id": 1,
      "order_id": 1,
      "payment_method": "card",
      "amount": 45000,
      "status": "pending",
      "transaction_id": null,
      "paid_at": null
    }
  ]
}
```

### Cart Response Model
```json
{
  "id": 1,
  "user_id": 5,
  "vehicle_id": 10,
  "quantity": 1,
  "created_at": "2026-04-08T10:00:00Z",
  "updated_at": "2026-04-08T10:00:00Z",
  "vehicle": {
    "id": 10,
    "make": "Toyota",
    "model": "Camry",
    "year": 2020,
    "price": 50000,
    "discount_percentage": 10,
    "discount_amount": 5000,
    "images": [ /* VehicleImage objects */ ]
  }
}
```

### Checkout Request Payload
```json
{
  "shipping_address": "123 Main St, Anytown, State 12345",
  "payment_method": "card",
  "notes": "Please handle with care"
}
```

## 🔄 Status Code Reference

### Success Codes
- **200 OK** - Request succeeded
- **201 Created** - Resource created
- **302 Found** - Redirect response
- **204 No Content** - Success with no response body

### Client Error Codes
- **400 Bad Request** - Invalid input
- **401 Unauthorized** - Authentication required
- **403 Forbidden** - Not authorized for this action
- **404 Not Found** - Resource not found
- **422 Unprocessable Entity** - Validation error

### Server Error Codes
- **500 Internal Server Error** - Server error occurred
- **503 Service Unavailable** - Service temporarily down

## 📝 Error Response Format

```json
{
  "message": "Error description",
  "errors": {
    "field_name": ["Error message for field"]
  }
}
```

Example validation error on checkout:
```json
{
  "message": "The given data was invalid.",
  "errors": {
    "shipping_address": ["The shipping address field is required."],
    "payment_method": ["The payment method must be one of: card, bank_transfer, cash_on_delivery."]
  }
}
```

## 🔄 Request Headers

All authenticated requests should include:
```
Accept: application/json
Content-Type: application/json
Authorization: Bearer {token}  // If using API tokens
X-CSRF-TOKEN: {csrf_token}     // For form submissions
```

## 🚀 Rate Limiting

- Checkout: 5 requests per minute
- Order creation: 10 requests per minute
- Cart operations: Unlimited
- Order queries: 100 requests per minute

## 📚 Additional Resources

- Full API documentation: See IMPLEMENTATION_SUMMARY.md
- Quick start guide: See QUICK_START.md
- Database schema: Run `php artisan migrate:status`
- Model relationships: Check app/Models/