135 lines
4.7 KiB
Plaintext
135 lines
4.7 KiB
Plaintext
# 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`.
|