multitenetsaas/docs/api/core/README.md

# 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"
  }
}
```