182 lines
7.3 KiB
Plaintext
182 lines
7.3 KiB
Plaintext
# Florida Gym - Owner App API Documentation
|
|
|
|
This documentation details the API endpoints available for the **Owner Mobile Application**. The app provides full administrative oversight across all branches, staff, investors, and financial reports.
|
|
|
|
## Connection Details
|
|
- **Base URL**: `http://[YOUR_SERVER_IP]:8002/api`
|
|
- **Headers**:
|
|
- `Accept: application/json`
|
|
- `Content-Type: application/json`
|
|
- `X-Requested-With: XMLHttpRequest`
|
|
- **Authentication**: The system uses session-based authentication. Ensure cookies are persisted across requests after login.
|
|
|
|
---
|
|
|
|
## 1. Authentication & Profile
|
|
Endpoints for managing owner access.
|
|
|
|
- **POST /login**
|
|
- **Description**: Primary login for Owners.
|
|
- **Parameters**:
|
|
- `email`: (string) Owner's email address.
|
|
- `password`: (string) Owner's password.
|
|
- **Response**:
|
|
- `Success (200)`: `{ "user": { "id": 1, "name": "Owner", "role": "admin" }, "redirect": "/owner/dashboard" }`
|
|
- `Error (422)`: `{ "message": "The provided credentials do not match our records." }`
|
|
|
|
- **GET /api/profile**
|
|
- **Description**: Returns details of the authenticated owner.
|
|
- **Query**: `context=owner`
|
|
- **Returns**: User object including name, email, and global permissions.
|
|
|
|
- **POST /logout**
|
|
- **Description**: Validates and terminates the current session.
|
|
|
|
---
|
|
|
|
## 2. Branch Oversight
|
|
Management of all business locations and their regulatory documents.
|
|
|
|
- **GET /api/branches**
|
|
- **Query (Optional)**: `status` (Active/Inactive)
|
|
- **Returns**: Array of branches with document counts, manager details, and operational status.
|
|
|
|
- **GET /api/branches/{id}**
|
|
- **Description**: Full profile of a specific branch.
|
|
- **Returns**: Branch details, metadata, and an array of `documents` (ID cards, licenses, etc.) with expiry dates.
|
|
|
|
- **POST /api/branches**
|
|
- **Headers**: `Content-Type: multipart/form-data`
|
|
- **Parameters**: `name`, `location`, `manager_name`, `operational_start_date`, `payroll_from_day`, `payroll_to_day`, `salary_generation_day`
|
|
- **Files**: `docs[i][file]`, `docs[i][name]`, `docs[i][expiry_date]`
|
|
- **Description**: Creates a new branch and uploads its legal documents.
|
|
|
|
- **PUT /api/branches/{id}**
|
|
- **Description**: Update branch details or toggle status.
|
|
- **Note**: Inactivating a branch automatically inactivates all associated staff.
|
|
|
|
- **GET /api/branches/{id}/active-staff**
|
|
- **Returns**: A list of staff members currently active at the specified branch.
|
|
|
|
---
|
|
|
|
## 3. Staff & Payroll Management
|
|
Comprehensive employee tracking and automated salary settlements.
|
|
|
|
- **GET /api/staff**
|
|
- **Query (Optional)**: `branch_id`, `status`
|
|
- **Returns**: List of staff with basic details and salary configuration.
|
|
|
|
- **POST /api/staff**
|
|
- **Headers**: `Content-Type: multipart/form-data`
|
|
- **Required Params**: `full_name`, `role`, `branch_id`, `joining_date`, `salary_type`, `salary_amount`.
|
|
- **Salary Settings**: `advance_enabled` (boolean), `advance_amount` (numeric), `commission_enabled` (boolean).
|
|
- **Files**: `documents[]` (Passport, Visa, etc.)
|
|
|
|
- **GET /api/staff/{id}/payroll-status**
|
|
- **Description**: Provides a month-by-month history of salaries paid and highlights "Unpaid" months.
|
|
|
|
- **GET /api/staff/{id}/settlement**
|
|
- **Description**: Calculates the net payable amount for a specific month.
|
|
- **Returns**: Base salary, commissions earned, and deductions (Advances/Fine) due.
|
|
- **Enforcement**: Blocks settlement if a previous month is still pending.
|
|
|
|
- **POST /api/staff/{id}/settle**
|
|
- **Params**: `month` (e.g., "2026-03"), `payment_date`, `remarks`.
|
|
- **Action**: Marks the month as Paid and creates an Expense record.
|
|
|
|
- **GET /api/staff/pending-salaries**
|
|
- **Description**: Global list of all staff members currently awaiting salary settlement across the organization.
|
|
|
|
- **POST /api/staff/bulk-settle**
|
|
- **Description**: Settle salaries for multiple employees in one transaction.
|
|
- **Params**: `settlements` (array of `{staff_id, month_key}`), `payment_date`, `remarks`.
|
|
|
|
---
|
|
|
|
## 4. Investor Network & ROI
|
|
Track capital investments and automate ROI returns.
|
|
|
|
- **GET /api/investors**
|
|
- **Returns**: List of investors, their total investment, and eager-loaded `payouts` data.
|
|
- **Key Fields**: `total_invested`, `total_roi_paid_so_far`.
|
|
|
|
- **POST /api/investors**
|
|
- **Params**: `name`, `investment_date`, `investment_amount`, `roi_type` (Percentage/Fixed), `roi_value`, `roi_period` (Monthly/Quarterly/Yearly).
|
|
|
|
- **GET /api/investors/{id}/roi-status**
|
|
- **Description**: Detailed ledger of ROI cycles, showing Pending vs Paid for each month of the investment life.
|
|
|
|
- **POST /api/investors/{id}/settle-roi**
|
|
- **Params**: `payout_month`, `amount`, `payment_method`, `remarks`.
|
|
- **Action**: Processes the ROI return and updates the investor's balance.
|
|
|
|
---
|
|
|
|
## 5. Inventory Control & Sales
|
|
Real-time stock management and sales reporting.
|
|
|
|
- **GET /api/inventory/products**
|
|
- **Query**: `branch_id`, `status` (In Stock/Low Stock/Out of Stock).
|
|
- **Returns**: Product list with SKU and current quantities.
|
|
|
|
- **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` (e.g., -5 for breakage, +10 for restock), `reason`, `remarks`.
|
|
|
|
- **GET /api/inventory/sales**
|
|
- **Description**: History of all product sales.
|
|
- **Return Order**: Latest first (date desc, created_at desc).
|
|
- **Fields**: `transaction_id`, `total_amount`, `payment_method`, `items`.
|
|
|
|
- **POST /api/inventory/sales**
|
|
- **Params**: `branch_id`, `payment_method`, `total_amount`, `items` (array of `product_id`, `quantity`, `unit_price`).
|
|
- **Validation**: Enforces selected payment method and prevents selling beyond available stock.
|
|
|
|
---
|
|
|
|
## 6. Financial Operations (Collections & Expenses)
|
|
Tracking of non-inventory income and operational costs.
|
|
|
|
- **GET /api/collections**
|
|
- **Query**: `start_date`, `end_date`, `branch_id`.
|
|
- **Returns**: Daily collections (Membership fees, lockers, etc.).
|
|
|
|
- **POST /api/collections**
|
|
- **Params**: `date`, `branch_id`, `collection_type_id`, `amount`, `payment_method`, `remarks`.
|
|
|
|
- **GET /api/expenses**
|
|
- **Description**: Full list of expenses across all branches.
|
|
- **POST /api/expenses**
|
|
- **Params**: `date`, `branch_id`, `expense_category_id`, `expense_type` (Account/Petty Cash), `amount`, `remarks`.
|
|
|
|
---
|
|
|
|
## 7. Global Reports & Analytics
|
|
Executive dashboards for data-driven decisions.
|
|
|
|
- **GET /api/reports/profit**
|
|
- **Query**: `branch_id`, `start_date`, `end_date`.
|
|
- **Returns**: `total_income`, `total_expense`, `net_profit`, and a list of all raw transactions.
|
|
|
|
- **GET /api/reports/expiry-reminders**
|
|
- **Returns**: Alerts for documents expiring in the next 30/60/90 days for both Staff and Branches.
|
|
|
|
- **GET /api/reports/investments**
|
|
- **Returns**: Aggregated summary of organization-wide capital and ROI performance.
|
|
|
|
- **GET /api/inventory/movements**
|
|
- **Description**: Global audit log of every stock change (Sales, Adjustments, Initial load).
|
|
|
|
---
|
|
|
|
## 8. Master Data Management
|
|
Manage the base configurations for the system.
|
|
|
|
- **GET /api/masters/{type}**
|
|
- **Types**: `collection` (types), `expense` (categories), `product` (categories), `payment_method`, `staff_role`.
|
|
- **POST /api/masters/{type}**
|
|
- **Params**: `name`, `status` (Active/Inactive).
|