# Tower Paint Admin API Documentation

All admin endpoints require:
1. **Authentication**: Bearer token (Sanctum)
2. **Authorization**: User must have `is_admin = true`

Base URL: `/api/admin`

---

## Dashboard

### GET /api/admin/dashboard

Returns overview statistics for the admin panel.

**Response:**
```json
{
  "data": {
    "users": {
      "total": 10,
      "admins": 2,
      "partners": 5
    },
    "partners": {
      "total": 5,
      "active": 3,
      "inactive": 1,
      "suspended": 1,
      "pending_payment": 2,
      "confirmed_payment": 3
    },
    "partners_by_tier": {
      "zonal": 2,
      "state": 1,
      "local": 2,
      "advert": 0
    }
  }
}
```

---

## Users Management

### GET /api/admin/users

List all users with optional filters.

**Query Parameters:**
| Parameter | Type | Description |
|-----------|------|-------------|
| search | string | Search by name, email, or phone |
| is_admin | boolean | Filter by admin status |
| per_page | int | Items per page (default: 15) |

### POST /api/admin/users

Create a new user.

**Request Body:**
```json
{
  "name": "John Doe",
  "email": "john@example.com",
  "password": "SecurePass123!",
  "password_confirmation": "SecurePass123!",
  "phone": "+2348012345678",
  "is_admin": false
}
```

### GET /api/admin/users/{user}

Get a single user by ID.

### PUT/PATCH /api/admin/users/{user}

Update a user.

**Request Body (all optional):**
```json
{
  "name": "John Doe",
  "email": "john@example.com",
  "password": "NewPass123!",
  "password_confirmation": "NewPass123!",
  "phone": "+2348012345678",
  "is_admin": false
}
```

### DELETE /api/admin/users/{user}

Delete a user.

---

## Partners Management

### GET /api/admin/partners

List all partners with optional filters.

**Query Parameters:**
| Parameter | Type | Description |
|-----------|------|-------------|
| search | string | Search by business name, registration number, territory, or payment reference |
| tier_id | int | Filter by partner tier |
| status | string | active, inactive, suspended |
| payment_status | string | pending, confirmed, rejected |
| per_page | int | Items per page (default: 15) |

### GET /api/admin/partners/{id}

Get a single partner by ID.

### PUT /api/admin/partners/{id}

Update partner details (business info, territory).

**Request Body (all optional):**
```json
{
  "business_name": "Tower Paint Lagos",
  "business_address": "123 Main Street",
  "business_phone": "+2348012345678",
  "territory_type": "state",
  "territory_name": "Lagos",
  "territory_code": "LG",
  "latitude": 6.5244,
  "longitude": 3.3792,
  "coverage_radius": 50
}
```

### PATCH /api/admin/partners/{id}/status

Update partner status (active/inactive/suspended).

**Request Body:**
```json
{
  "status": "active"
}
```

### POST /api/admin/partners/{id}/confirm-payment

Confirm partner payment and activate partner.

**Request Body:**
```json
{
  "payment_reference": "TP-2024-001234",
  "payment_amount": 22500000,
  "payment_date": "2024-01-15"
}
```

### POST /api/admin/partners/{id}/reject-payment

Reject partner payment.

---

## Partner Tiers Management

### GET /api/admin/partner-tiers

List all partner tiers (Zonal, State, Local, Advert).

### GET /api/admin/partner-tiers/{id}

Get a single partner tier by ID.

### PUT /api/admin/partner-tiers/{id}

Update partner tier configuration.

**Request Body (all optional):**
```json
{
  "name": "Zonal",
  "registration_fee": 1000000,
  "product_value": 19000000,
  "mixer_value": 2500000,
  "paint_discount_min": 15,
  "paint_discount_max": 15,
  "plasterboard_discount": 7,
  "polystyrene_discount": 5,
  "paint_yearly_return": 10,
  "plasterboard_yearly_return": 5,
  "polystyrene_yearly_return": 2,
  "logistics_subsidy": 100
}
```

---

## Authentication

Include the Bearer token in all admin requests:

```
Authorization: Bearer {your_sanctum_token}
```

To obtain a token, login via `POST /api/auth/login` with admin credentials.

---

## Error Responses

| Status | Description |
|--------|-------------|
| 401 | Unauthorized - Invalid or missing token |
| 403 | Forbidden - User is not an admin |
| 404 | Resource not found |
| 422 | Validation error |