multitenetsaas/docs/api/beauty

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

POST /api/v1/beauty/clients/

Request Body:

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

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

GET /api/v1/beauty/clients/{client_id}/

Update Client

PUT /api/v1/beauty/clients/{client_id}/

List Clients

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

DELETE /api/v1/beauty/clients/{client_id}/

Get Client History

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

POST /api/v1/beauty/services/

Request Body:

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

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

GET /api/v1/beauty/services/{service_id}/

Update Service

PUT /api/v1/beauty/services/{service_id}/

List Services

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

DELETE /api/v1/beauty/services/{service_id}/

Appointments

Create Appointment

POST /api/v1/beauty/appointments/

Request Body:

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

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

GET /api/v1/beauty/appointments/{appointment_id}/

Update Appointment

PUT /api/v1/beauty/appointments/{appointment_id}/

List Appointments

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

POST /api/v1/beauty/appointments/{appointment_id}/cancel/

Request Body:

{
  "reason": "Client unable to attend",
  "cancelled_by": "client",
  "refund_amount": 0.00
}

Check-in Client

POST /api/v1/beauty/appointments/{appointment_id}/check-in/

Start Service

POST /api/v1/beauty/appointments/{appointment_id}/start/

Complete Appointment

POST /api/v1/beauty/appointments/{appointment_id}/complete/

Request Body:

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

POST /api/v1/beauty/staff/

Request Body:

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

GET /api/v1/beauty/staff/{staff_id}/

Update Staff

PUT /api/v1/beauty/staff/{staff_id}/

List Staff

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

DELETE /api/v1/beauty/staff/{staff_id}/

Get Staff Schedule

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

POST /api/v1/beauty/products/

Request Body:

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

GET /api/v1/beauty/products/{product_id}/

Update Product

PUT /api/v1/beauty/products/{product_id}/

List Products

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

DELETE /api/v1/beauty/products/{product_id}/

Packages and Memberships

Create Package

POST /api/v1/beauty/packages/

Request Body:

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

POST /api/v1/beauty/memberships/

Request Body:

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

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

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

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

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:

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

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

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

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

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

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

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

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

{
  "marketing_compliance": {
    "kkm_advertising_guidelines": true,
    "no_false_claims": true,
    "halal_certification_display": true,
    "price_transparency": true,
    "pdpa_compliance": true
  }
}