# KFA Website API Documentation

This document serves as the official technical specification for the backend API required to power the KFA front-end application. All endpoints follow RESTful conventions and return JSON responses.

**Base API URL:** `http://127.0.0.1:8001/api`

---

## 1. Global & Landing Page

### 1.1 Home Sliders
`GET /slides`
- **Description:** Returns high-resolution images and marketing text for the hero slider.
- **Response Structure:**
```json
[
  {
    "id": 1,
    "image_url": "https://kfa.com.kh/uploads/sliders/slide1.jpg",
    "title": "Welcome to KFA",
    "subtitle": "Excellence in Property Appraisal",
    "button_text": "Our Services",
    "button_link": "/services"
  }
]
```

### 1.4 Building Achievements
`GET /properties/achievements`
- **Description:** Returns the 3 most recent completed or featured projects.
- **Response Structure:**
```json
[
  {
    "id": 1,
    "title": "KFA Main Tower",
    "category": "Commercial",
    "image_url": "https://...",
    "status": "completed",
    "is_featured": 1
  }
]
```

### 1.2 Our Partners
`GET /partners`
- **Description:** Returns logos and names of trusted partners for the homepage carousel.
- **Response Structure:**
```json
[
  {
    "id": 1,
    "name": "ABA Bank",
    "logo_url": "https://kfa.com.kh/uploads/partners/aba.png"
  }
]
```

### 1.3 Company Statement
`GET /company-statement`
- **Description:** Returns the welcome message, mission, and company overview for the homepage.
- **Response Structure:**
```json
{
  "title": "Welcome to Khmer Foundation Appraisals",
  "image_url": "https://kfa.com.kh/images/welcome-img.jpg",
  "statement_1": "Khmer Foundation Appraisals Co., Ltd. (KFA) was founded in 2015...",
  "statement_2": "Our core mission is to provide accurate, transparent, and professional...",
  "years_of_excellence": "10+",
  "appraisals_done": "25k+"
}
```

---

## 2. Core Business Services

### 2.1 Service Listing
`GET /services`
- **Description:** Returns KFA's professional service offerings.
- **Response Structure:**
```json
[
  {
    "id": 1,
    "title": "Asset & Property Appraisal",
    "icon": "🏠",
    "short_description": "We provide accurate, transparent, and professional valuation services...",
    "full_description": "Extensive details about the appraisal process...",
    "features": ["Bank Loan Securities", "Legal Appraisal", "Acquisitions"]
  }
]
```

---

## 3. Real Estate Listings (External)

> [!IMPORTANT]
> **Status: Deprecated / Externalized**
> Property listings are no longer served via this API. KFA Properties are now hosted on a dedicated platform at `https://properties.kfa.com.kh`. 
> The front-end now links directly to that external domain.

### 3.1 Properties (Deprecated)
`GET /properties`
- **Description:** [DEPRECATED] Internal property fetching is no longer used.

---

## 4. Market Intelligence

### 4.1 Land Market Prices
`GET /land-market-prices`
- **Description:** Provides historical and current market data for land prices across Cambodia.
- **Response Structure:**
```json
[
  {
    "province": "Phnom Penh",
    "district": "Tuol Kork",
    "min_price": 2500,
    "max_price": 5500,
    "average_price": 4000,
    "currency": "USD",
    "unit": "sqm"
  }
]
```

---

## 5. Media & Engagement

### 5.1 News & Media
`GET /news`
- **Description:** Fetches corporate news, press releases, and market insights.
- **Query Parameters:**
  - `category`: `corporate` | `market` | `awards`
  - `limit`: integer
- **Response Structure:**
```json
[
  {
    "id": 1,
    "title": "KFA Expands Operations to Siem Reap",
    "thumbnail": "https://images.unsplash.com/...",
    "category": "Corporate News",
    "date": "Dec 20, 2023",
    "excerpt": "We are excited to announce our new branch opening..."
  }
]
```

### 5.2 Contact Submission
`POST /contact`
- **Description:** Validates and stores user inquiries.
- **Headers:** `Content-Type: application/json`
- **Payload:**
```json
{
  "full_name": "John Doe",
  "email": "john@example.com",
  "subject": "Appraisal Inquiry",
  "message": "I would like to request a quote for..."
}
```
- **Response:** `200 OK` with confirmation message.

---

## 6. Media & News
### 6.1 News Categories
`GET /news?category={category}`
- **Categories:** `National`, `International`, `Company`, `Video`
- **Response:** List of news items refined by category.

### 6.2 Reports & Overviews
`GET /reports?type={type}`
- **Types:** `Real Estate Overview`, `Economic Overview`
- **Response:** PDF links or structured text for market reports.

---

## 7. Corporate & About Us
### 7.1 Careers
`GET /careers`
- **Description:** Returns a list of open job positions.
- **Response Structure:**
```json
[
  {
    "id": 1,
    "title": "Valuation Officer",
    "location": "Phnom Penh",
    "type": "Full-Time",
    "closing_date": "2024-12-31"
  }
]
```

`POST /careers/apply`
- **Description:** Submit a job application.
- **Payload:**
```json
{
  "name": "Jane Doe",
  "email": "jane@example.com",
  "phone": "012345678",
  "position_id": 1,
  "cv": "(File Upload)",
  "message": "Cover letter text..."
}
```

### 7.2 Business Licenses
`GET /business-licenses`
- **Description:** Returns list of business certificates and licenses.
- **Response Structure:**
```json
[
  {
    "id": 1,
    "title": "Valuation License",
    "image_url": "https://kfa.com.kh/licenses/val.jpg"
  }
]
```

### 7.3 Corporate Profile Sections
The following endpoints return structured content for specific "About Us" sections:

`GET /ceo-message`
- **Response:** `{ "title": "...", "author": "...", "quote": "...", "content": "...", "image_url": "..." }`

`GET /company-overview`
- **Response:** `{ "content": "HTML string of company history..." }`

`GET /vision-mission`
- **Response:** `{ "vision": "...", "mission": "...", "core_values": [ { "title": "Integrity", "description": "..." } ] }`

`GET /our-people`
- **Response:** `{ "content": "Intro text...", "founder": { ... }, "advisor": { ... } }`

`GET /ethical-standard`
- **Response:** `{ "content": "Intro text...",    "standards": [ { "title": "Integrity", "description": "..." } ] }`

### 7.4 Company Profile & Structure
`GET /company-profile`
- **Response:**
  ```json
  {
      "content": "Intro text...",
      "images": ["https://kfa.com.kh/uploads/profile1.jpg", "https://kfa.com.kh/uploads/profile2.jpg"],
      "file_url": "https://kfa.com.kh/uploads/profile.pdf"
  }
  ```

`GET /company-structure`
- **Response:**
  ```json
  {
      "content": "Intro text...",
      "images": ["https://kfa.com.kh/uploads/structure1.jpg"]
  }
  ```

---

## 8. Visuals & Data
### 8.1 Gallery
`GET /galleries`
- **Description:** Returns images grouped by album/event.

---

> [!NOTE]
> All image URLs should be absolute. The frontend uses `Axios` with the configured Base URL as the default interceptor.