Hugging Face's logo

Spaces:
cuatrolabs
/
cuatrolabs-scm-ms
Running

App Files Community
cuatrolabs-scm-ms / docs /security /TAXONOMY_API_COMPLETE_GUIDE.md
MukeshKapoor25's picture
MukeshKapoor25
merchant fixes
63f05fb
preview code
|
raw
history blame contribute delete
16.8 kB

Complete Taxonomy API Implementation Guide

Overview

This document provides a comprehensive guide to the taxonomy management system implementation based on the complete JSON structure. The system supports all taxonomy categories including product, employee, customer, and operational taxonomies with full CRUD operations and performance optimization through projection lists.

Supported Taxonomy Categories

Based on the provided JSON structure, the system supports the following taxonomy categories:

Product Taxonomies

  • brands: Product brands (e.g., "L'Oréal Professional", "Schwarzkopf", "Kerastase")
  • categories: Product categories (e.g., "Hair", "Skin", "Nails", "Spa", "Makeup")
  • lines: Product lines (e.g., "Hair Care", "Hair Styling", "Facials")
  • classes: Product classes (e.g., "Premium", "Luxury", "Basic", "VIP")
  • subcategories: Hierarchical subcategories mapped to parent categories

Employee Taxonomies

  • job_role: Employee job roles (e.g., "Senior Stylist", "Director", "Massage therapist")
  • specializations: Employee specializations (e.g., "Hairdresser", "Nail technician", "Esthetician")
  • languages: Supported languages (e.g., "English", "Hindi", "Tamil")

Customer Taxonomies

  • customer_group: Customer groups (e.g., "VIP", "Regular", "Premium", "Enterprise", "Gold")

Operational Taxonomies

POS & Payment

  • pos_tender_modes: POS tender modes (e.g., "Cash", "Credit Card", "Debit Card", "Mobile Payment")
  • payment_types: Payment types (e.g., "Cash and Carry", "Credit")
  • payment_methods: Payment methods (e.g., "Bank Transfer", "Cash", "Cheque")

Asset & Inventory

  • asset_location: Asset locations (e.g., "Store Floor", "Warehouse", "Back Office")
  • asset_category: Asset categories (e.g., "Electronics", "Furniture", "Equipment")
  • stock_bin_location: Stock bin locations (e.g., "A1-01", "B2-15", "C3-07", "Receiving")

Business Structure

  • branch_types: Branch types (e.g., "Flagship", "Outlet", "Pop-up", "Franchise")
  • expense_types: Expense types (e.g., "Travel", "Office Supplies")

UOM Conversions

  • uom_conversions: Unit of measurement conversions with base UOM and conversion factors

API Endpoints

Base URL 

/taxonomy

Authentication

All endpoints require JWT authentication with merchant_id in the token metadata.

1. Create or Update Taxonomy

Endpoint: POST /taxonomy/

Description: Create new taxonomy data or update existing data for a merchant. Supports all taxonomy categories and uses MongoDB addToSet operations to prevent duplicates.

Request Body 

{
  "brands": ["L'Oréal Professional", "Schwarzkopf", "Kerastase", "Olaplex"],
  "categories": ["Hair", "Skin", "Nails", "Spa", "Makeup", "Foot"],
  "lines": ["Hair Care", "Hair Styling", "Facials", "Body Treatments"],
  "classes": ["Premium", "Luxury", "Basic", "VIP"],
  "subcategories": {
    "Hair": ["Hair Cut", "Hair Color", "Hair Spa", "Keratin Treatment"],
    "Skin": ["Clean-up", "Facial", "De-Tan", "Peel Treatments"],
    "Nails": ["Manicure", "Pedicure", "Nail Art", "Gel Polish"],
    "Spa": ["Head Massage", "Full Body Massage", "Aromatherapy"],
    "Makeup": ["Bridal Makeup", "Party Makeup"]
  },
  "job_role": ["Senior Stylist", "Director", "Massage therapist", "Esthetician"],
  "specializations": ["Hairdresser", "Nail technician", "Massage therapist", "Esthetician"],
  "languages": ["English", "Hindi", "Tamil"],
  "customer_group": ["VIP", "Regular", "Premium", "Enterprise", "Gold"],
  "pos_tender_modes": ["Cash", "Credit Card", "Debit Card", "Mobile Payment"],
  "payment_types": ["Cash and Carry", "Credit"],
  "payment_methods": ["Bank Transfer", "Cash", "Cheque"],
  "asset_location": ["Store Floor", "Warehouse", "Back Office"],
  "asset_category": ["Electronics", "Furniture", "Equipment"],
  "stock_bin_location": ["A1-01", "B2-15", "C3-07", "Receiving"],
  "branch_types": ["Flagship", "Outlet", "Pop-up", "Franchise"],
  "expense_types": ["Travel", "Office Supplies"],
  "uom_conversions": [
    {
      "base_uom": "g",
      "conversions": [
        {
          "alt_uom": "kg",
          "factor": 1000.0,
          "description": "1 kg = 1000 g"
        }
      ]
    },
    {
      "base_uom": "ml",
      "conversions": [
        {
          "alt_uom": "L",
          "factor": 1000.0,
          "description": "1 L = 1000 ml"
        },
        {
          "alt_uom": "bottle",
          "factor": 650.0,
          "description": "650 ml bottle"
        }
      ]
    }
  ],
  "is_delete": false
}

Response 

{
  "success": true,
  "message": "Taxonomy operation completed successfully",
  "data": {
    "taxonomy_id": "uuid-string",
    "operation": "create",
    "merchant_id": "company_cuatro_beauty_ltd",
    "modified_count": 1
  },
  "timestamp": "2025-12-12T10:30:00Z"
}

2. List Taxonomy Data

Endpoint: POST /taxonomy/list

Description: List taxonomy data with optional projection and filtering. Follows SCM API standards with projection_list support for performance optimization.

Request Body Examples

Complete Data (No Projection) 

{
  "taxonomy_type": null,
  "projection_list": null
}

With Projection (Performance Optimized) 

{
  "taxonomy_type": null,
  "projection_list": ["merchant_id", "brands", "categories", "job_role", "created_at"]
}

Filtered by Taxonomy Type 

{
  "taxonomy_type": "brands",
  "projection_list": null
}

Combined Projection + Filtering 

{
  "taxonomy_type": "categories",
  "projection_list": ["merchant_id", "categories", "created_at"]
}

Response Examples

Complete Data Response 

{
  "success": true,
  "message": "Taxonomy data retrieved successfully",
  "data": {
    "id": "uuid-string",
    "merchant_id": "company_cuatro_beauty_ltd",
    "taxonomies": {
      "brands": ["L'Oréal Professional", "Schwarzkopf", "Kerastase"],
      "categories": ["Hair", "Skin", "Nails", "Spa", "Makeup"],
      "lines": ["Hair Care", "Hair Styling", "Facials"],
      "classes": ["Premium", "Luxury", "Basic", "VIP"],
      "subcategories": {
        "Hair": ["Hair Cut", "Hair Color", "Hair Spa"],
        "Skin": ["Clean-up", "Facial", "De-Tan"]
      },
      "job_role": ["Senior Stylist", "Director"],
      "specializations": ["Hairdresser", "Nail technician"],
      "languages": ["English", "Hindi", "Tamil"],
      "customer_group": ["VIP", "Regular", "Premium"],
      "pos_tender_modes": ["Cash", "Credit Card", "Debit Card"],
      "payment_types": ["Cash and Carry", "Credit"],
      "payment_methods": ["Bank Transfer", "Cash", "Cheque"],
      "asset_location": ["Store Floor", "Warehouse", "Back Office"],
      "asset_category": ["Electronics", "Furniture", "Equipment"],
      "stock_bin_location": ["A1-01", "B2-15", "C3-07"],
      "branch_types": ["Flagship", "Outlet", "Pop-up", "Franchise"],
      "expense_types": ["Travel", "Office Supplies"],
      "uom_conversions": [...]
    },
    "created_at": "2025-08-19T09:50:11.927Z",
    "updated_at": "2025-12-12T06:31:08.509Z"
  },
  "metadata": {
    "merchant_id": "company_cuatro_beauty_ltd",
    "taxonomy_type": null,
    "projection_applied": false,
    "timestamp": "2025-12-12T10:30:00Z"
  }
}

Projected Data Response 

{
  "success": true,
  "message": "Taxonomy data retrieved successfully",
  "data": [
    {
      "merchant_id": "company_cuatro_beauty_ltd",
      "brands": ["L'Oréal Professional", "Schwarzkopf", "Kerastase"],
      "categories": ["Hair", "Skin", "Nails", "Spa", "Makeup"],
      "job_role": ["Senior Stylist", "Director"],
      "created_at": "2025-08-19T09:50:11.927Z"
    }
  ],
  "metadata": {
    "merchant_id": "company_cuatro_beauty_ltd",
    "taxonomy_type": null,
    "projection_applied": true,
    "timestamp": "2025-12-12T10:30:00Z"
  }
}

Filtered by Type Response 

{
  "success": true,
  "message": "Taxonomy data retrieved successfully",
  "data": [
    {
      "id": "uuid-string",
      "merchant_id": "company_cuatro_beauty_ltd",
      "taxonomy_type": "brands",
      "data": ["L'Oréal Professional", "Schwarzkopf", "Kerastase", "Olaplex"],
      "created_at": "2025-08-19T09:50:11.927Z",
      "updated_at": "2025-12-12T06:31:08.509Z"
    }
  ],
  "metadata": {
    "merchant_id": "company_cuatro_beauty_ltd",
    "taxonomy_type": "brands",
    "projection_applied": false,
    "timestamp": "2025-12-12T10:30:00Z"
  }
}

3. Get Taxonomy by ID

Endpoint: GET /taxonomy/{taxonomy_id}

Description: Retrieve a specific taxonomy document by its unique identifier.

Response 

{
  "success": true,
  "message": "Taxonomy document retrieved successfully",
  "data": {
    "id": "uuid-string",
    "merchant_id": "company_cuatro_beauty_ltd",
    "brands": ["L'Oréal Professional", "Schwarzkopf"],
    "categories": ["Hair", "Skin", "Nails"],
    // ... all taxonomy fields
    "created_at": "2025-08-19T09:50:11.927Z",
    "updated_at": "2025-12-12T06:31:08.509Z"
  },
  "metadata": {
    "taxonomy_id": "uuid-string",
    "merchant_id": "company_cuatro_beauty_ltd",
    "timestamp": "2025-12-12T10:30:00Z"
  }
}

4. Delete Taxonomy Values

Endpoint: POST /taxonomy/

Description: Delete specific values from taxonomy fields using the is_delete flag.

Request Body 

{
  "brands": ["Brand to Delete", "Another Brand"],
  "categories": ["Category to Remove"],
  "expense_types": ["Expense Type to Remove"],
  "is_delete": true
}

Response 

{
  "success": true,
  "message": "Taxonomy delete completed successfully",
  "data": {
    "taxonomy_id": "uuid-string",
    "operation": "delete",
    "merchant_id": "company_cuatro_beauty_ltd",
    "modified_count": 1
  },
  "timestamp": "2025-12-12T10:30:00Z"
}

5. Delete Entire Taxonomy

Endpoint: DELETE /taxonomy/{taxonomy_id}

Description: Delete an entire taxonomy document.

Response 

{
  "success": true,
  "message": "Taxonomy entry deleted successfully",
  "data": {
    "taxonomy_id": "uuid-string",
    "merchant_id": "company_cuatro_beauty_ltd",
    "deleted_by": "user_id"
  }
}

6. UOM Conversions Management

Delete UOM Conversions

Endpoint: DELETE /taxonomy/uom-conversions/{base_uom}

Description: Delete UOM conversion entries. Can delete entire UOM group or specific conversion.

Delete Entire UOM Group 

{
  "alt_uom": null
}

Delete Specific Conversion 

{
  "alt_uom": "kg"
}

Response 

{
  "success": true,
  "message": "UOM conversion deleted successfully",
  "data": {
    "base_uom": "g",
    "alt_uom": "kg",
    "merchant_id": "company_cuatro_beauty_ltd",
    "modified_count": 1,
    "deleted_by": "user_id"
  }
}

Performance Optimization

Projection List Benefits

Using projection lists can provide significant performance improvements:

  • Payload Size Reduction: 50-90% reduction in response size
  • Network Bandwidth: Reduced data transfer
  • Database I/O: Less data read from MongoDB
  • Client Processing: Faster JSON parsing

Example Performance Comparison 

# Full data query (all fields)
POST /taxonomy/list
{
  "projection_list": null
}
# Response size: ~15KB

# Projected query (3 fields only)
POST /taxonomy/list
{
  "projection_list": ["merchant_id", "brands", "categories"]
}
# Response size: ~2KB (87% reduction)

Error Handling

Common Error Responses

Validation Error 

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid projection fields: invalid_field",
    "details": {
      "invalid_fields": ["invalid_field"],
      "valid_fields": ["brands", "categories", "job_role", ...]
    }
  }
}

Access Denied 

{
  "success": false,
  "error": {
    "code": "ACCESS_DENIED",
    "message": "Access denied for merchant data",
    "details": {
      "merchant_id": "company_cuatro_beauty_ltd",
      "user_id": "user_id"
    }
  }
}

Not Found 

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Taxonomy document not found",
    "details": {
      "taxonomy_id": "uuid-string",
      "merchant_id": "company_cuatro_beauty_ltd"
    }
  }
}

Usage Examples

1. Create Complete Taxonomy for Beauty retail 

curl -X POST "https://api.example.com/taxonomy/" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "brands": ["L'\''Oréal Professional", "Schwarzkopf", "Kerastase"],
    "categories": ["Hair", "Skin", "Nails", "Spa", "Makeup"],
    "subcategories": {
      "Hair": ["Hair Cut", "Hair Color", "Hair Spa"],
      "Skin": ["Clean-up", "Facial", "De-Tan"],
      "Nails": ["Manicure", "Pedicure", "Nail Art"]
    },
    "job_role": ["Senior Stylist", "Director", "Massage therapist"],
    "specializations": ["Hairdresser", "Nail technician", "Esthetician"],
    "languages": ["English", "Hindi", "Tamil"],
    "customer_group": ["VIP", "Regular", "Premium"],
    "pos_tender_modes": ["Cash", "Credit Card", "Mobile Payment"],
    "branch_types": ["Flagship", "Outlet"],
    "expense_types": ["Travel", "Office Supplies"]
  }'

2. Get Optimized Data for Mobile App 

curl -X POST "https://api.example.com/taxonomy/list" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "projection_list": ["brands", "categories", "customer_group"]
  }'

3. Get Only Service Categories 

curl -X POST "https://api.example.com/taxonomy/list" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "taxonomy_type": "categories"
  }'

4. Update Expense Types 

curl -X POST "https://api.example.com/taxonomy/" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "expense_types": ["Marketing", "Training", "Equipment Maintenance"]
  }'

Best Practices

1. Use Projection Lists

Always use projection lists when you don't need all taxonomy data:

{
  "projection_list": ["brands", "categories", "job_role"]
}

2. Filter by Taxonomy Type

When working with specific taxonomy categories:

{
  "taxonomy_type": "brands"
}

3. Combine Projection and Filtering

For maximum performance optimization:

{
  "taxonomy_type": "categories",
  "projection_list": ["merchant_id", "categories", "created_at"]
}

4. Batch Updates

Group related updates in single requests:

{
  "brands": ["New Brand 1", "New Brand 2"],
  "categories": ["New Category"],
  "expense_types": ["New Expense Type"]
}

5. Use Meaningful Descriptions for UOM

Always provide clear descriptions for UOM conversions:

{
  "alt_uom": "bottle",
  "factor": 650.0,
  "description": "650 ml bottle (standard retail size)"
}

Integration Examples

Frontend Integration (React) 

// Fetch taxonomy data for dropdown
const fetchTaxonomyData = async (fields) => {
  const response = await fetch('/api/taxonomy/list', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      projection_list: fields
    })
  });
  
  const data = await response.json();
  return data.data[0]; // Projected data
};

// Usage
const taxonomyData = await fetchTaxonomyData(['brands', 'categories']);

Mobile App Integration (Flutter/Dart) 

Future<Map<String, dynamic>> getTaxonomyData(List<String> fields) async {
  final response = await http.post(
    Uri.parse('$baseUrl/taxonomy/list'),
    headers: {
      'Authorization': 'Bearer $token',
      'Content-Type': 'application/json',
    },
    body: jsonEncode({
      'projection_list': fields,
    }),
  );
  
  if (response.statusCode == 200) {
    final data = jsonDecode(response.body);
    return data['data'][0];
  }
  throw Exception('Failed to load taxonomy data');
}

Monitoring and Analytics

The taxonomy system provides comprehensive monitoring capabilities:

Health Check 

GET /taxonomy/health

Monitoring Dashboard 

GET /taxonomy/monitoring

Key Metrics Tracked

  • Operation counts (create, update, delete, list)
  • Performance metrics (response times, payload sizes)
  • Error rates and types
  • Projection usage statistics
  • Most requested taxonomy types

This complete implementation provides a robust, scalable, and performant taxonomy management system that handles all the categories from your JSON structure while following SCM API standards and best practices.