# Flutter Mobile App API Documentation

## Connection Details
- **Base URL**: `http://127.0.0.1:8002/api`
- **Mobile Testing**: For testing on a physical device, replace `127.0.0.1` with your computer's local IP (e.g., `http://192.168.1.5:8002/api`).
- **Headers**: 
  - `Accept: application/json`
  - `Content-Type: application/json`
  - `X-Requested-With: XMLHttpRequest`

---

## 1. Authentication Module
Manage user sessions and profiles.

- **POST /login**
  - Params: `email`, `password`
  - Response: `{ "user": { ... }, "redirect": "/owner/dashboard" }`
- **POST /receptionist/login**
  - Params: `email`, `password`
  - Response: `{ "user": { ... }, "redirect": "/receptionist/dashboard" }`
- **GET /api/profile**
  - Query: `context` (owner/receptionist)
  - Returns: Current user details and role.
- **POST /logout**
  - Action: Terminates session.

---

## 2. Branch Management
Manage business locations and their documents.

- **GET /api/branches**
  - Query: `status` (Active/Inactive)
  - Returns: List of all branches with document counts and revenue.
- **GET /api/branches/{id}**
  - Returns: Detailed branch info and documents.
- **POST /api/branches**
  - Type: `multipart/form-data`
  - Params: `name`, `location`, `manager_name`, `operational_start_date`, `payroll_from_day`, `payroll_to_day`, `salary_generation_day`
  - Files: `docs[0][file]`, `docs[0][name]`, `docs[0][expiry_date]`...
- **PUT /api/branches/{id}**
  - Params: Same as POST, plus `status`.
- **DELETE /api/branches/{id}**
  - Note: Only deletable if not used in staff/inventory/accounts.
- **GET /api/branches/{id}/active-staff**
  - Returns: List of active staff in that branch.

---

## 3. Staff & Payroll Module
Employee management and salary settlements.

- **GET /api/staff**
  - Query: `branch_id`
  - Returns: Complete staff list with documents.
- **POST /api/staff**
  - Type: `multipart/form-data`
  - Params: `full_name`, `email`, `phone`, `role`, `branch_id`, `joining_date`, `status`, `salary_type`, `salary_amount`.
  - Optional: `advance_enabled`, `advance_amount`, `commission_enabled`, `documents[]`.
- **GET /api/staff/{id}/payroll-status**
  - Returns: Month-by-month payment history and unpaid months.
- **GET /api/staff/{id}/settlement**
  - Returns: Pro-rated salary calculation, commissions, and advance deductions due.
- **POST /api/staff/{id}/settle**
  - Params: `month` (Y-m), `remarks`
  - Action: Processes salary payment and records expense.
- **GET /api/staff/pending-salaries**
  - Returns: List of all staff with pending settlements across branches.
- **POST /api/staff/bulk-settle**
  - Params: `settlements` (array of staff_id/month_key), `remarks`.

---

## 4. Investor & ROI Module
Manage investments and monthly payouts.

- **GET /api/investors**
  - Returns: List of all investors and their linked branches.
- **POST /api/investors**
  - Params: `name`, `investment_date`, `investment_amount`, `roi_type` (Percentage/Fixed Amount), `roi_value`, `roi_period` (Monthly/Quarterly/Yearly).
- **GET /api/investors/{id}/roi-status**
  - Returns: Breakdown of ROI due, paid, and carry-over for each period.
- **POST /api/investors/{id}/settle-roi**
  - Params: `payout_month`, `amount`, `payout_date`, `payment_method`, `remarks`.

---

## 5. Inventory & POS Module
Product management and sales tracking.

- **GET /api/inventory/products**
  - Query: `branch_id`, `status` (In Stock/Low Stock/Out of Stock).
- **POST /api/inventory/products**
  - Params: `name`, `sku`, `product_category_id`, `branch_id`, `cost_price`, `selling_price`, `current_stock`, `reorder_level`.
- **POST /api/inventory/products/{id}/adjust**
  - Params: `adjustment_qty` (+/-), `reason`, `adjustment_date`.
- **POST /api/inventory/sales**
  - Params: `branch_id`, `payment_method`, `items` (array of product_id/quantity/unit_price).
  - Action: Deducts stock and records revenue.

---

## 6. Collections & Expenses
Financial tracking.

- **GET /api/collections**
  - Query: `start_date`, `end_date`, `branch_id`.
- **POST /api/collections**
  - Params: `date`, `branch_id`, `collection_type_id`, `amount`, `payment_method`, `items[]`.
- **POST /api/expenses**
  - Params: `date`, `branch_id`, `expense_category_id`, `expense_type` (Account/Petty Cash), `amount`, `remarks`.

---

## 7. Reports
Data analysis and reminders.

- **GET /api/reports/profit**
  - Returns: Total income, total expense, net profit, and 6-month trend.
- **GET /api/reports/expiry-reminders**
  - Returns: Document expiry alerts for both Staff and Branches.
- **GET /api/reports/investments**
  - Returns: Summary of total investments and total ROI returned.

---

## 8. Master Settings
Manage dropdown options.

- **GET /api/masters/{type}**
  - Types: `collection`, `expense`, `product`, `payment_method`, `staff_role`.
- **POST /api/masters/{type}**
  - Params: `name`, `status`.