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

POST /api/v1/auth/login/

Request Body:

{
  "username": "your_username",
  "password": "your_password",
  "tenant_id": "your_tenant_id"
}

Response:

{
  "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

POST /api/v1/auth/register/

Request Body:

{
  "username": "newuser",
  "email": "user@example.com",
  "password": "SecurePass123!",
  "first_name": "John",
  "last_name": "Doe",
  "phone_number": "+60123456789",
  "ic_number": "900101-01-1234"
}

Refresh Token

POST /api/v1/auth/refresh/

Request Body:

{
  "refresh_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."
}

Logout

POST /api/v1/auth/logout/

Headers:

Authorization: Bearer <access-token>

Tenants

Create Tenant

POST /api/v1/tenants/

Request Body:

{
  "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

GET /api/v1/tenants/{tenant_id}/

Update Tenant

PUT /api/v1/tenants/{tenant_id}/

List Tenants

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

DELETE /api/v1/tenants/{tenant_id}/

Users

Create User

POST /api/v1/users/

Request Body:

{
  "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

GET /api/v1/users/{user_id}/

Update User

PUT /api/v1/users/{user_id}/

List Users

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

DELETE /api/v1/users/{user_id}/

Change Password

POST /api/v1/users/{user_id}/change-password/

Request Body:

{
  "current_password": "old_password",
  "new_password": "NewSecurePass123!"
}

Subscriptions

Create Subscription

POST /api/v1/subscriptions/

Request Body:

{
  "tenant_id": "tenant_id",
  "plan_id": "plan_id",
  "modules": ["retail", "inventory"],
  "billing_cycle": "monthly",
  "payment_method_id": "payment_method_id"
}

Get Subscription

GET /api/v1/subscriptions/{subscription_id}/

Update Subscription

PUT /api/v1/subscriptions/{subscription_id}/

List Subscriptions

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

POST /api/v1/subscriptions/{subscription_id}/cancel/

Modules

List Available Modules

GET /api/v1/modules/

Response:

{
  "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

POST /api/v1/modules/{module_id}/enable/

Request Body:

{
  "tenant_id": "tenant_id",
  "configuration": {
    "retail": {
      "enable_loyalty_program": true,
      "enable_inventory_alerts": true
    }
  }
}

Disable Module

POST /api/v1/modules/{module_id}/disable/

Get Module Configuration

GET /api/v1/modules/{module_id}/configuration/

Payment Methods

Add Payment Method

POST /api/v1/payment-methods/

Request Body:

{
  "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

GET /api/v1/payment-methods/

Delete Payment Method

DELETE /api/v1/payment-methods/{payment_method_id}/

Payment Transactions

Create Payment

POST /api/v1/payments/

Request Body:

{
  "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

GET /api/v1/payments/{payment_id}/

List Payments

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

POST /api/v1/payments/{payment_id}/refund/

Request Body:

{
  "amount": 100.00,
  "reason": "Customer request"
}

Malaysian Features

Validate Malaysian Phone Number

POST /api/v1/utils/validate-phone/

Request Body:

{
  "phone_number": "+60123456789"
}

Response:

{
  "success": true,
  "data": {
    "is_valid": true,
    "normalized_format": "+60123456789",
    "type": "mobile",
    "carrier": "Maxis"
  }
}

Calculate SST

POST /api/v1/utils/calculate-sst/

Request Body:

{
  "amount": 100.00,
  "service_type": "retail"
}

Response:

{
  "success": true,
  "data": {
    "subtotal": 100.00,
    "sst_rate": 0.06,
    "sst_amount": 6.00,
    "total": 106.00
  }
}

Validate Business Registration

POST /api/v1/utils/validate-registration/

Request Body:

{
  "registration_number": "202401000123"
}

Response:

{
  "success": true,
  "data": {
    "is_valid": true,
    "company_name": "My Business Sdn Bhd",
    "registration_date": "2024-01-01",
    "status": "active"
  }
}