multitenetsaas/docs/api/beauty/README.md

# Beauty Module API Documentation

## Overview

The Beauty Module API provides comprehensive functionality for beauty salons and spas including client management, service catalog, appointment scheduling, and Malaysian beauty industry compliance.

## Clients

### Create Client
```http
POST /api/v1/beauty/clients/
```

**Request Body:**
```json
{
  "first_name": "Siti",
  "last_name": "Aminah",
  "email": "siti.aminah@example.com",
  "phone_number": "+60123456789",
  "ic_number": "900101-01-1234",
  "date_of_birth": "1990-01-01",
  "gender": "female",
  "address": {
    "street": "123 Client Street",
    "city": "Kuala Lumpur",
    "state": "Wilayah Persekutuan",
    "postal_code": "50050",
    "country": "Malaysia"
  },
  "emergency_contact": {
    "name": "Hassan Ibrahim",
    "relationship": "husband",
    "phone_number": "+60123456788"
  },
  "skin_type": "combination",
  "hair_type": "colored",
  "allergies": ["fragrance", "nuts"],
  "medical_conditions": ["eczema"],
  "preferred_services": ["facial", "manicure", "hair_treatment"],
  "frequency": "monthly",
  "membership_level": "gold",
  "loyalty_points": 1250,
  "notes": "Prefers organic products, sensitive to strong fragrances",
  "marketing_consent": true,
  "pdpa_consent": true
}
```

**Response:**
```json
{
  "success": true,
  "data": {
    "id": "cli_123456",
    "first_name": "Siti",
    "last_name": "Aminah",
    "email": "siti.aminah@example.com",
    "phone_number": "+60123456789",
    "ic_number": "900101-01-1234",
    "date_of_birth": "1990-01-01",
    "gender": "female",
    "address": {
      "street": "123 Client Street",
      "city": "Kuala Lumpur",
      "state": "Wilayah Persekutuan",
      "postal_code": "50050",
      "country": "Malaysia"
    },
    "emergency_contact": {
      "name": "Hassan Ibrahim",
      "relationship": "husband",
      "phone_number": "+60123456788"
    },
    "skin_type": "combination",
    "hair_type": "colored",
    "allergies": ["fragrance", "nuts"],
    "medical_conditions": ["eczema"],
    "preferred_services": ["facial", "manicure", "hair_treatment"],
    "frequency": "monthly",
    "membership_level": "gold",
    "loyalty_points": 1250,
    "notes": "Prefers organic products, sensitive to strong fragrances",
    "marketing_consent": true,
    "pdpa_consent": true,
    "pdpa_consent_date": "2024-01-01T00:00:00Z",
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-01T00:00:00Z"
  }
}
```

### Get Client
```http
GET /api/v1/beauty/clients/{client_id}/
```

### Update Client
```http
PUT /api/v1/beauty/clients/{client_id}/
```

### List Clients
```http
GET /api/v1/beauty/clients/
```

**Query Parameters:**
- `page` - Page number (default: 1)
- `page_size` - Items per page (default: 20, max: 100)
- `membership_level` - Filter by membership level
- `skin_type` - Filter by skin type
- `hair_type` - Filter by hair type
- `search` - Search in name, email, phone
- `frequency` - Filter by visit frequency

### Delete Client
```http
DELETE /api/v1/beauty/clients/{client_id}/
```

### Get Client History
```http
GET /api/v1/beauty/clients/{client_id}/history/
```

**Query Parameters:**
- `page` - Page number (default: 1)
- `page_size` - Items per page (default: 20, max: 100)
- `date_from` - Filter by date (YYYY-MM-DD)
- `date_to` - Filter by date (YYYY-MM-DD)

## Services

### Create Service
```http
POST /api/v1/beauty/services/
```

**Request Body:**
```json
{
  "name": "Premium Anti-Aging Facial",
  "description": "Advanced facial treatment with anti-aging properties",
  "category": "facial",
  "subcategory": "anti_aging",
  "duration_minutes": 90,
  "price": 350.00,
  "tax_rate": 6.0,
  "staff_level_required": "senior",
  "room_requirements": ["facial_bed", "steamer", "extractor"],
  "products_used": ["serum", "moisturizer", "mask"],
  "target_skin_types": ["all"],
  "contraindications": ["active_acne", "pregnancy", "recent_surgery"],
  "pre_care_instructions": "Avoid sun exposure 24 hours before treatment",
  "post_care_instructions": "Use gentle skincare products for 48 hours",
  "membership_discount": 15.0,
  "promotion_discount": 10.0,
  "is_active": true,
  "kkm_approved": true,
  "kkm_approval_number": "KKM-BEAUTY-12345",
  "halal_certified": true,
  "halal_certification_number": "JAKIM-1234-5678",
  "notes": "Popular treatment for mature skin"
}
```

**Response:**
```json
{
  "success": true,
  "data": {
    "id": "svc_123456",
    "name": "Premium Anti-Aging Facial",
    "description": "Advanced facial treatment with anti-aging properties",
    "category": "facial",
    "subcategory": "anti_aging",
    "duration_minutes": 90,
    "price": 350.00,
    "tax_rate": 6.0,
    "staff_level_required": "senior",
    "room_requirements": ["facial_bed", "steamer", "extractor"],
    "products_used": ["serum", "moisturizer", "mask"],
    "target_skin_types": ["all"],
    "contraindications": ["active_acne", "pregnancy", "recent_surgery"],
    "pre_care_instructions": "Avoid sun exposure 24 hours before treatment",
    "post_care_instructions": "Use gentle skincare products for 48 hours",
    "membership_discount": 15.0,
    "promotion_discount": 10.0,
    "is_active": true,
    "kkm_approved": true,
    "kkm_approval_number": "KKM-BEAUTY-12345",
    "halal_certified": true,
    "halal_certification_number": "JAKIM-1234-5678",
    "notes": "Popular treatment for mature skin",
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-01T00:00:00Z"
  }
}
```

### Get Service
```http
GET /api/v1/beauty/services/{service_id}/
```

### Update Service
```http
PUT /api/v1/beauty/services/{service_id}/
```

### List Services
```http
GET /api/v1/beauty/services/
```

**Query Parameters:**
- `page` - Page number (default: 1)
- `page_size` - Items per page (default: 20, max: 100)
- `category` - Filter by category
- `subcategory` - Filter by subcategory
- `min_price` - Minimum price
- `max_price` - Maximum price
- `is_active` - Filter by active status
- `halal_certified` - Filter by halal certification

### Delete Service
```http
DELETE /api/v1/beauty/services/{service_id}/
```

## Appointments

### Create Appointment
```http
POST /api/v1/beauty/appointments/
```

**Request Body:**
```json
{
  "client_id": "cli_123456",
  "services": [
    {
      "service_id": "svc_123456",
      "staff_id": "stf_123456",
      "start_time": "2024-01-15T10:00:00Z",
      "end_time": "2024-01-15T11:30:00Z"
    },
    {
      "service_id": "svc_789012",
      "staff_id": "stf_789012",
      "start_time": "2024-01-15T11:45:00Z",
      "end_time": "2024-01-15T12:30:00Z"
    }
  ],
  "total_price": 550.00,
  "total_duration_minutes": 135,
  "status": "confirmed",
  "payment_status": "paid",
  "payment_method": "credit_card",
  "notes": "Client prefers morning appointments",
  "special_requests": "Use fragrance-free products",
  "reminder_preferences": {
    "email": true,
    "sms": true,
    "reminder_hours_before": 24
  }
}
```

**Response:**
```json
{
  "success": true,
  "data": {
    "id": "apt_123456",
    "client_id": "cli_123456",
    "services": [
      {
        "service_id": "svc_123456",
        "service_name": "Premium Anti-Aging Facial",
        "staff_id": "stf_123456",
        "staff_name": "Nurul Aminah",
        "start_time": "2024-01-15T10:00:00Z",
        "end_time": "2024-01-15T11:30:00Z",
        "price": 350.00
      },
      {
        "service_id": "svc_789012",
        "service_name": "Classic Manicure",
        "staff_id": "stf_789012",
        "staff_name": "Farah Ibrahim",
        "start_time": "2024-01-15T11:45:00Z",
        "end_time": "2024-01-15T12:30:00Z",
        "price": 200.00
      }
    ],
    "total_price": 550.00,
    "total_duration_minutes": 135,
    "status": "confirmed",
    "payment_status": "paid",
    "payment_method": "credit_card",
    "notes": "Client prefers morning appointments",
    "special_requests": "Use fragrance-free products",
    "reminder_preferences": {
      "email": true,
      "sms": true,
      "reminder_hours_before": 24
    },
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-01T00:00:00Z"
  }
}
```

### Get Appointment
```http
GET /api/v1/beauty/appointments/{appointment_id}/
```

### Update Appointment
```http
PUT /api/v1/beauty/appointments/{appointment_id}/
```

### List Appointments
```http
GET /api/v1/beauty/appointments/
```

**Query Parameters:**
- `page` - Page number (default: 1)
- `page_size` - Items per page (default: 20, max: 100)
- `client_id` - Filter by client
- `staff_id` - Filter by staff
- `date_from` - Filter by start date (YYYY-MM-DD)
- `date_to` - Filter by end date (YYYY-MM-DD)
- `status` - Filter by status (pending, confirmed, in_progress, completed, cancelled, no_show)

### Cancel Appointment
```http
POST /api/v1/beauty/appointments/{appointment_id}/cancel/
```

**Request Body:**
```json
{
  "reason": "Client unable to attend",
  "cancelled_by": "client",
  "refund_amount": 0.00
}
```

### Check-in Client
```http
POST /api/v1/beauty/appointments/{appointment_id}/check-in/
```

### Start Service
```http
POST /api/v1/beauty/appointments/{appointment_id}/start/
```

### Complete Appointment
```http
POST /api/v1/beauty/appointments/{appointment_id}/complete/
```

**Request Body:**
```json
{
  "services_rendered": [
    {
      "service_id": "svc_123456",
      "notes": "Good skin condition, minimal blackheads",
      "products_used": ["anti-aging serum", "moisturizer"],
      "recommendations": ["Continue with home care routine"]
    }
  ],
  "total_amount": 550.00,
  "payment_received": 550.00,
  "payment_method": "credit_card",
  "staff_notes": "Client satisfied with results",
  "follow_up_required": true,
  "follow_up_date": "2024-02-15"
}
```

## Staff

### Create Staff
```http
POST /api/v1/beauty/staff/
```

**Request Body:**
```json
{
  "first_name": "Nurul",
  "last_name": "Aminah",
  "email": "nurul.aminah@beautysalon.com",
  "phone_number": "+60123456789",
  "ic_number": "900101-01-1234",
  "date_of_birth": "1990-01-01",
  "gender": "female",
  "address": {
    "street": "123 Staff Street",
    "city": "Kuala Lumpur",
    "state": "Wilayah Persekutuan",
    "postal_code": "50050",
    "country": "Malaysia"
  },
  "position": "senior_beauty_therapist",
  "specializations": ["facial", "massage", "waxing"],
  "certifications": [
    {
      "name": "CIDESCO Diploma",
      "issuing_body": "CIDESCO International",
      "certificate_number": "CID-123456",
      "issue_date": "2020-01-01",
      "expiry_date": "2025-01-01"
    },
    {
      "name": "Malaysian Beauty Therapy Certificate",
      "issuing_body": "KKM",
      "certificate_number": "KKM-BT-123456",
      "issue_date": "2019-06-01",
      "expiry_date": "2024-06-01"
    }
  ],
  "experience_years": 8,
  "hourly_rate": 50.00,
  "commission_rate": 15.0,
  "employment_status": "full_time",
  "working_hours": {
    "monday": ["09:00-18:00"],
    "tuesday": ["09:00-18:00"],
    "wednesday": ["09:00-18:00"],
    "thursday": ["09:00-18:00"],
    "friday": ["09:00-18:00"],
    "saturday": ["10:00-17:00"],
    "sunday": []
  },
  "skills": ["advanced_facial", "microdermabrasion", "chemical_peel"],
  "languages": ["english", "malay", "mandarin"],
  "emergency_contact": {
    "name": "Aminah Hassan",
    "relationship": "mother",
    "phone_number": "+60123456788"
  },
  "status": "active",
  "notes": "Excellent customer service skills"
}
```

### Get Staff
```http
GET /api/v1/beauty/staff/{staff_id}/
```

### Update Staff
```http
PUT /api/v1/beauty/staff/{staff_id}/
```

### List Staff
```http
GET /api/v1/beauty/staff/
```

**Query Parameters:**
- `page` - Page number (default: 1)
- `page_size` - Items per page (default: 20, max: 100)
- `position` - Filter by position
- `specialization` - Filter by specialization
- `status` - Filter by status
- `employment_status` - Filter by employment status

### Delete Staff
```http
DELETE /api/v1/beauty/staff/{staff_id}/
```

### Get Staff Schedule
```http
GET /api/v1/beauty/staff/{staff_id}/schedule/
```

**Query Parameters:**
- `date_from` - Filter by start date (YYYY-MM-DD)
- `date_to` - Filter by end date (YYYY-MM-DD)

## Products

### Create Product
```http
POST /api/v1/beauty/products/
```

**Request Body:**
```json
{
  "name": "Anti-Aging Serum",
  "brand": "GlowBeauty",
  "description": "Advanced anti-aging serum with hyaluronic acid",
  "category": "skincare",
  "subcategory": "serum",
  "sku": "GB-AS-001",
  "barcode": "9555123456789",
  "volume_ml": 30,
  "price": 180.00,
  "tax_rate": 6.0,
  "stock_quantity": 50,
  "minimum_stock": 10,
  "ingredients": ["hyaluronic_acid", "vitamin_c", "retinol"],
  "skin_types": ["all"],
  "age_groups": ["adult", "mature"],
  "expiry_date": "2026-01-01",
  "batch_number": "GB-2024-001",
  "supplier": "GlowBeauty Supplies Sdn Bhd",
  "kkm_approved": true,
  "kkm_notification_number": "NOT202400123456",
  "halal_certified": true,
  "halal_certification_number": "JAKIM-1234-5678",
  "cruelty_free": true,
  "vegan": false,
  "organic": false,
  "is_active": true
}
```

### Get Product
```http
GET /api/v1/beauty/products/{product_id}/
```

### Update Product
```http
PUT /api/v1/beauty/products/{product_id}/
```

### List Products
```http
GET /api/v1/beauty/products/
```

**Query Parameters:**
- `page` - Page number (default: 1)
- `page_size` - Items per page (default: 20, max: 100)
- `category` - Filter by category
- `subcategory` - Filter by subcategory
- `brand` - Filter by brand
- `min_price` - Minimum price
- `max_price` - Maximum price
- `halal_certified` - Filter by halal certification
- `low_stock` - Show low stock items

### Delete Product
```http
DELETE /api/v1/beauty/products/{product_id}/
```

## Packages and Memberships

### Create Package
```http
POST /api/v1/beauty/packages/
```

**Request Body:**
```json
{
  "name": "Beauty Queen Package",
  "description": "Complete beauty treatment package",
  "services": [
    {
      "service_id": "svc_123456",
      "frequency": "monthly",
      "duration_months": 12
    },
    {
      "service_id": "svc_789012",
      "frequency": "bi_weekly",
      "duration_months": 12
    }
  ],
  "total_price": 4800.00,
  "original_price": 6000.00,
  "discount_percentage": 20.0,
  "validity_months": 12,
  "payment_plan": "full_payment",
  "terms_and_conditions": "Non-refundable, non-transferable",
  "is_active": true,
  "membership_discount": 5.0
}
```

### Create Membership
```http
POST /api/v1/beauty/memberships/
```

**Request Body:**
```json
{
  "client_id": "cli_123456",
  "membership_type": "gold",
  "start_date": "2024-01-01",
  "end_date": "2025-01-01",
  "annual_fee": 500.00,
  "benefits": [
    {
      "benefit": "15% discount on all services",
      "type": "percentage_discount",
      "value": 15.0
    },
    {
      "benefit": "Free birthday facial",
      "type": "free_service",
      "service_id": "svc_123456"
    },
    {
      "benefit": "Priority booking",
      "type": "priority"
    }
  ],
  "payment_method": "credit_card",
  "auto_renew": true,
  "status": "active"
}
```

## Reports and Analytics

### Sales Report
```http
GET /api/v1/beauty/reports/sales/
```

**Query Parameters:**
- `date_from` - Filter by start date (YYYY-MM-DD)
- `date_to` - Filter by end date (YYYY-MM-DD)
- `group_by` - Group by (service, staff, client, day)
- `format` - Output format (json, csv, pdf)

### Client Analytics
```http
GET /api/v1/beauty/reports/clients/
```

**Query Parameters:**
- `date_from` - Filter by start date (YYYY-MM-DD)
- `date_to` - Filter by end date (YYYY-MM-DD)
- `group_by` - Group by (membership_level, frequency, demographics)
- `format` - Output format (json, csv, pdf)

### Staff Performance
```http
GET /api/v1/beauty/reports/staff-performance/
```

**Query Parameters:**
- `date_from` - Filter by start date (YYYY-MM-DD)
- `date_to` - Filter by end date (YYYY-MM-DD)
- `staff_id` - Filter by staff
- `format` - Output format (json, csv, pdf)

### Inventory Report
```http
GET /api/v1/beauty/reports/inventory/
```

**Query Parameters:**
- `category` - Filter by category
- `low_stock` - Show low stock items
- `format` - Output format (json, csv, pdf)

## Malaysian Beauty Industry Features

### KKM Compliance
Full integration with Malaysian Ministry of Health (KKM) requirements:
```json
{
  "kkm_compliance": {
    "premise_license": "KKM-PREMISE-12345",
    "notification_number": "NOT202400123456",
    "last_inspection_date": "2024-01-01",
    "next_inspection_date": "2025-01-01",
    "inspection_result": "passed",
    "certificates": ["beauty_therapy", "massage_therapy"]
  }
}
```

### Halal Certification
Support for JAKIM halal certification:
```json
{
  "halal_certification": {
    "certified": true,
    "certificate_number": "JAKIM-1234-5678",
    "issue_date": "2024-01-01",
    "expiry_date": "2025-01-01",
    "certifying_body": "JAKIM",
    "products_covered": ["skincare", "haircare", "cosmetics"]
  }
}
```

### Malaysian Cultural Preferences
Support for Malaysian cultural and religious preferences:
```json
{
  "cultural_considerations": {
    "gender_specific_services": true,
    "female_therapists_for_female_clients": true,
    "prayer_room_access": true,
    "halal_products_only": true,
    "modest_attire_policy": true
  }
}
```

### Malaysian Beauty Standards
Alignment with Malaysian beauty preferences:
```json
{
  "malaysian_beauty_preferences": {
    "popular_services": ["facial", "hair_treatment", "manicure", "pedicure"],
    "preferred_products": ["halal_certified", "suitable_for_tropical_climate"],
    "peak_hours": ["evening", "weekends"],
    "seasonal_promotions": ["hari_raya", "chinese_new_year", "deepavali"]
  }
}
```

### Malaysian Time and Holidays
Respect for Malaysian time and holidays:
```json
{
  "operating_considerations": {
    "timezone": "Asia/Kuala_Lumpur",
    "prayer_times": true,
    "public_holidays": ["hari_raya", "chinese_new_year", "deepavali"],
    "ramadan_hours": true,
    "friday_prayer_break": true
  }
}
```

### Malaysian Language Support
Multi-language support for Malaysian clients:
```json
{
  "language_support": {
    "primary_languages": ["malay", "english", "mandarin"],
    "staff_languages": ["malay", "english", "mandarin", "tamil"],
    "marketing_materials": ["malay", "english", "mandarin"]
  }
}
```

### Malaysian Payment Methods
Support for Malaysian payment preferences:
```json
{
  "payment_methods": {
    "cash": true,
    "credit_card": true,
    "debit_card": true,
    "ewallet": ["touch_n_go", "grabpay", "boost"],
    "online_banking": ["maybank2u", "cimb_clicks", "rhbb"]
  }
}
```

### Malaysian Staff Requirements
Compliance with Malaysian beauty industry staff requirements:
```json
{
  "staff_requirements": {
    "minimum_certification": "KKM_Beauty_Therapy_Certificate",
    "foreign_worker_permits": true,
    "epf_contribution": true,
    "socso_coverage": true,
    "medical_checkup_required": true
  }
}
```

### Malaysian Marketing Compliance
Compliance with Malaysian advertising regulations:
```json
{
  "marketing_compliance": {
    "kkm_advertising_guidelines": true,
    "no_false_claims": true,
    "halal_certification_display": true,
    "price_transparency": true,
    "pdpa_compliance": true
  }
}
```