project initialization

docs/api/core/README.md

@@ -0,0 +1,463 @@
+# Core API Documentation
+
+## Overview
+
+The Core API provides fundamental functionality for multi-tenant management, authentication, and platform administration.
+
+## Authentication
+
+### Login
+```http
+POST /api/v1/auth/login/
+```
+
+**Request Body:**
+```json
+{
+  "username": "your_username",
+  "password": "your_password",
+  "tenant_id": "your_tenant_id"
+}
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "data": {
+    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
+    "refresh_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
+    "user": {
+      "id": 1,
+      "username": "your_username",
+      "email": "user@example.com",
+      "role": "admin",
+      "tenant_id": "your_tenant_id"
+    }
+  }
+}
+```
+
+### Register
+```http
+POST /api/v1/auth/register/
+```
+
+**Request Body:**
+```json
+{
+  "username": "newuser",
+  "email": "user@example.com",
+  "password": "SecurePass123!",
+  "first_name": "John",
+  "last_name": "Doe",
+  "phone_number": "+60123456789",
+  "ic_number": "900101-01-1234"
+}
+```
+
+### Refresh Token
+```http
+POST /api/v1/auth/refresh/
+```
+
+**Request Body:**
+```json
+{
+  "refresh_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."
+}
+```
+
+### Logout
+```http
+POST /api/v1/auth/logout/
+```
+
+**Headers:**
+```
+Authorization: Bearer <access-token>
+```
+
+## Tenants
+
+### Create Tenant
+```http
+POST /api/v1/tenants/
+```
+
+**Request Body:**
+```json
+{
+  "name": "My Business Sdn Bhd",
+  "schema_name": "my_business",
+  "domain": "mybusiness.com",
+  "business_type": "retail",
+  "registration_number": "202401000123",
+  "business_address": {
+    "street": "123 Business Street",
+    "city": "Kuala Lumpur",
+    "state": "Wilayah Persekutuan",
+    "postal_code": "50050",
+    "country": "Malaysia"
+  },
+  "contact_email": "contact@mybusiness.com",
+  "contact_phone": "+60312345678"
+}
+```
+
+### Get Tenant
+```http
+GET /api/v1/tenants/{tenant_id}/
+```
+
+### Update Tenant
+```http
+PUT /api/v1/tenants/{tenant_id}/
+```
+
+### List Tenants
+```http
+GET /api/v1/tenants/
+```
+
+**Query Parameters:**
+- `page` - Page number (default: 1)
+- `page_size` - Items per page (default: 20, max: 100)
+- `business_type` - Filter by business type (retail, healthcare, education, logistics, beauty)
+- `is_active` - Filter by active status
+
+### Delete Tenant
+```http
+DELETE /api/v1/tenants/{tenant_id}/
+```
+
+## Users
+
+### Create User
+```http
+POST /api/v1/users/
+```
+
+**Request Body:**
+```json
+{
+  "username": "newuser",
+  "email": "user@example.com",
+  "password": "SecurePass123!",
+  "first_name": "John",
+  "last_name": "Doe",
+  "phone_number": "+60123456789",
+  "ic_number": "900101-01-1234",
+  "role": "staff",
+  "permissions": ["view_products", "manage_sales"]
+}
+```
+
+### Get User
+```http
+GET /api/v1/users/{user_id}/
+```
+
+### Update User
+```http
+PUT /api/v1/users/{user_id}/
+```
+
+### List Users
+```http
+GET /api/v1/users/
+```
+
+**Query Parameters:**
+- `page` - Page number (default: 1)
+- `page_size` - Items per page (default: 20, max: 100)
+- `role` - Filter by role (admin, manager, staff, user)
+- `is_active` - Filter by active status
+
+### Delete User
+```http
+DELETE /api/v1/users/{user_id}/
+```
+
+### Change Password
+```http
+POST /api/v1/users/{user_id}/change-password/
+```
+
+**Request Body:**
+```json
+{
+  "current_password": "old_password",
+  "new_password": "NewSecurePass123!"
+}
+```
+
+## Subscriptions
+
+### Create Subscription
+```http
+POST /api/v1/subscriptions/
+```
+
+**Request Body:**
+```json
+{
+  "tenant_id": "tenant_id",
+  "plan_id": "plan_id",
+  "modules": ["retail", "inventory"],
+  "billing_cycle": "monthly",
+  "payment_method_id": "payment_method_id"
+}
+```
+
+### Get Subscription
+```http
+GET /api/v1/subscriptions/{subscription_id}/
+```
+
+### Update Subscription
+```http
+PUT /api/v1/subscriptions/{subscription_id}/
+```
+
+### List Subscriptions
+```http
+GET /api/v1/subscriptions/
+```
+
+**Query Parameters:**
+- `page` - Page number (default: 1)
+- `page_size` - Items per page (default: 20, max: 100)
+- `tenant_id` - Filter by tenant
+- `status` - Filter by status (active, cancelled, expired)
+
+### Cancel Subscription
+```http
+POST /api/v1/subscriptions/{subscription_id}/cancel/
+```
+
+## Modules
+
+### List Available Modules
+```http
+GET /api/v1/modules/
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "data": [
+    {
+      "id": "retail",
+      "name": "Retail Management",
+      "description": "Complete retail and inventory management solution",
+      "features": [
+        "Product catalog management",
+        "Sales order processing",
+        "Inventory tracking",
+        "Customer management",
+        "Loyalty programs"
+      ],
+      "pricing": {
+        "monthly": 299.00,
+        "yearly": 2990.00
+      }
+    }
+  ]
+}
+```
+
+### Enable Module
+```http
+POST /api/v1/modules/{module_id}/enable/
+```
+
+**Request Body:**
+```json
+{
+  "tenant_id": "tenant_id",
+  "configuration": {
+    "retail": {
+      "enable_loyalty_program": true,
+      "enable_inventory_alerts": true
+    }
+  }
+}
+```
+
+### Disable Module
+```http
+POST /api/v1/modules/{module_id}/disable/
+```
+
+### Get Module Configuration
+```http
+GET /api/v1/modules/{module_id}/configuration/
+```
+
+## Payment Methods
+
+### Add Payment Method
+```http
+POST /api/v1/payment-methods/
+```
+
+**Request Body:**
+```json
+{
+  "type": "credit_card",
+  "card_number": "4111111111111111",
+  "expiry_month": 12,
+  "expiry_year": 2025,
+  "cvv": "123",
+  "cardholder_name": "John Doe",
+  "billing_address": {
+    "street": "123 Billing Street",
+    "city": "Kuala Lumpur",
+    "state": "Wilayah Persekutuan",
+    "postal_code": "50050",
+    "country": "Malaysia"
+  }
+}
+```
+
+### List Payment Methods
+```http
+GET /api/v1/payment-methods/
+```
+
+### Delete Payment Method
+```http
+DELETE /api/v1/payment-methods/{payment_method_id}/
+```
+
+## Payment Transactions
+
+### Create Payment
+```http
+POST /api/v1/payments/
+```
+
+**Request Body:**
+```json
+{
+  "amount": 299.00,
+  "currency": "MYR",
+  "payment_method_id": "payment_method_id",
+  "description": "Monthly subscription",
+  "metadata": {
+    "subscription_id": "sub_123456",
+    "tenant_id": "tenant_123456"
+  }
+}
+```
+
+### Get Payment
+```http
+GET /api/v1/payments/{payment_id}/
+```
+
+### List Payments
+```http
+GET /api/v1/payments/
+```
+
+**Query Parameters:**
+- `page` - Page number (default: 1)
+- `page_size` - Items per page (default: 20, max: 100)
+- `tenant_id` - Filter by tenant
+- `status` - Filter by status (pending, completed, failed, refunded)
+- `date_from` - Filter by date (YYYY-MM-DD)
+- `date_to` - Filter by date (YYYY-MM-DD)
+
+### Refund Payment
+```http
+POST /api/v1/payments/{payment_id}/refund/
+```
+
+**Request Body:**
+```json
+{
+  "amount": 100.00,
+  "reason": "Customer request"
+}
+```
+
+## Malaysian Features
+
+### Validate Malaysian Phone Number
+```http
+POST /api/v1/utils/validate-phone/
+```
+
+**Request Body:**
+```json
+{
+  "phone_number": "+60123456789"
+}
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "data": {
+    "is_valid": true,
+    "normalized_format": "+60123456789",
+    "type": "mobile",
+    "carrier": "Maxis"
+  }
+}
+```
+
+### Calculate SST
+```http
+POST /api/v1/utils/calculate-sst/
+```
+
+**Request Body:**
+```json
+{
+  "amount": 100.00,
+  "service_type": "retail"
+}
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "data": {
+    "subtotal": 100.00,
+    "sst_rate": 0.06,
+    "sst_amount": 6.00,
+    "total": 106.00
+  }
+}
+```
+
+### Validate Business Registration
+```http
+POST /api/v1/utils/validate-registration/
+```
+
+**Request Body:**
+```json
+{
+  "registration_number": "202401000123"
+}
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "data": {
+    "is_valid": true,
+    "company_name": "My Business Sdn Bhd",
+    "registration_date": "2024-01-01",
+    "status": "active"
+  }
+}
+```