API Overview

The MN Exim API provides programmatic access to our premium leather goods e-commerce platform. This RESTful API supports both public endpoints for browsing products and secure admin endpoints for managing inventory and content.

Base URL

/api

Current Status

Operational

Key Features

  • RESTful API design with consistent JSON responses
  • Personal Access Token authentication for secure API access
  • Comprehensive product, category, and collection management
  • Pagination support for large datasets
  • Advanced search and filtering capabilities
  • Bulk operations via Excel file uploads
  • Bulk product creation with configurable format mapping
  • Permission-based access control

Authentication

The API supports two authentication methods for different use cases:

Web Session (Admin Panel)

Uses JWT cookies for admin panel access. Suitable for web-based administration.

Cookie: admin-jwt=eyJ0eXAi...

Personal Access Token

Uses Bearer tokens for API integrations. Perfect for external applications.

Authorization: Bearer abc123...

Getting Started

To get started, create a Personal Access Token in the admin panel with the required permissions for your use case.

API Endpoints

Products

GET/api/products

Retrieve paginated list of active products

Parameters & Example
Query Parameters:
  • page - Page number (default: 1)
  • limit - Items per page (default: 20, max: 100)
  • search - Search term
  • category - Filter by category ID
  • featured - Filter featured products only
/api/products?page=1&limit=5&featured=true
GET/api/products/{slug}

Retrieve a single product by its slug

Example Response
{
  "success": true,
  "data": {
    "id": 1,
    "name": "Premium Leather Handbag",
    "slug": "premium-leather-handbag",
    "description": "Elegant handbag crafted from finest Italian leather",
    "price": "299.99",
    "categoryId": 1,
    "images": ["https://example.com/image.jpg"],
    "specifications": {
      "material": "Italian leather",
      "color": ["Black", "Brown"]
    },
    "features": ["Genuine leather", "Multiple compartments"],
    "isActive": true,
    "isFeatured": true
  }
}

Categories

GET/api/categories

Retrieve hierarchical list of active categories

Admin Endpoints

🔒 Authentication Required: Admin endpoints require either a JWT cookie or Personal Access Token.

GET/api/admin/products
Requires: admin:read

List all products including inactive ones

Query Parameters
  • page - Page number (default: 1)
  • limit - Items per page (default: 20)
  • search - Search term
  • category - Filter by category ID
  • includeInactive - Include inactive products
POST/api/admin/products
Requires: admin:write

Create a new product

Request Body Schema
{
  "name": "string (required)",
  "slug": "string (required)",
  "description": "string",
  "shortDescription": "string",
  "sku": "string",
  "price": "string (required)",
  "comparePrice": "string",
  "costPrice": "string",
  "inventory": "number (default: 0)",
  "categoryId": "number (required)",
  "images": ["string array"],
  "specifications": {
    "material": "string",
    "color": ["string array"],
    "size": "string"
  },
  "features": ["string array"],
  "tags": ["string array"],
  "weight": "string",
  "dimensions": {
    "length": "number",
    "width": "number", 
    "height": "number"
  },
  "isActive": "boolean (default: true)",
  "isFeatured": "boolean (default: false)",
  "seoTitle": "string",
  "seoDescription": "string"
}
Example Request:
{
  "name": "Premium Leather Wallet",
  "slug": "premium-leather-wallet",
  "description": "Handcrafted wallet with RFID protection",
  "shortDescription": "RFID-protected leather wallet",
  "sku": "PLW-001",
  "price": "89.99",
  "comparePrice": "119.99",
  "costPrice": "45.00",
  "inventory": 25,
  "categoryId": 3,
  "images": ["https://example.com/wallet.jpg"],
  "specifications": {
    "material": "Genuine leather",
    "color": ["Black", "Brown", "Tan"],
    "size": "Bifold"
  },
  "features": [
    "RFID blocking technology",
    "8 card slots",
    "Genuine leather",
    "Compact design"
  ],
  "tags": ["wallet", "leather", "rfid", "premium"],
  "weight": "0.15",
  "dimensions": {
    "length": 11,
    "width": 8.5,
    "height": 1
  },
  "isActive": true,
  "isFeatured": false,
  "seoTitle": "Premium RFID Leather Wallet - MN Exim",
  "seoDescription": "Protect your cards with our premium RFID-blocking leather wallet"
}
PUT/api/admin/products/{id}
Requires: admin:write

Update an existing product

Request Body Schema

Same as POST schema, but all fields are optional for partial updates:

{
  "name": "Updated Product Name",
  "price": "99.99",
  "inventory": 30,
  "isActive": false
}
GET/api/admin/tokens
Requires: admin:read

List current user's Personal Access Tokens

POST/api/admin/tokens
Requires: admin:write

Create a new Personal Access Token

Request Body Schema
{
  "name": "string (required)",
  "permissions": [
    "admin:read",
    "admin:write", 
    "admin:delete",
    "admin:*"
  ],
  "expiresAt": "ISO 8601 datetime (optional)"
}
Example Request:
{
  "name": "API Integration Token",
  "permissions": ["admin:read", "admin:write"],
  "expiresAt": "2025-12-31T23:59:59.000Z"
}
Response:
{
  "success": true,
  "data": {
    "id": 1,
    "name": "API Integration Token",
    "permissions": ["admin:read", "admin:write"],
    "expiresAt": "2025-12-31T23:59:59.000Z",
    "createdAt": "2025-08-13T15:00:00.000Z"
  },
  "token": "abc123def456789...",
  "message": "Token created successfully. Save this token - you won't see it again!"
}
POST/api/admin/categories
Requires: admin:write

Create a new category

Request Body Schema
{
  "name": "string (required)",
  "slug": "string (required)",
  "description": "string",
  "parentId": "number (optional, null for root category)",
  "image": "string (URL)",
  "isActive": "boolean (default: true)",
  "sortOrder": "number (default: 0)",
  "seoTitle": "string",
  "seoDescription": "string"
}
Example Request:
{
  "name": "Travel Bags",
  "slug": "travel-bags",
  "description": "Durable leather bags for travel and adventure",
  "parentId": 1,
  "image": "https://example.com/travel-bags.jpg",
  "isActive": true,
  "sortOrder": 5,
  "seoTitle": "Premium Travel Bags - MN Exim",
  "seoDescription": "Discover our collection of premium leather travel bags"
}
POST/api/admin/collections
Requires: admin:write

Create a new collection

Request Body Schema
{
  "name": "string (required)",
  "slug": "string (required)",
  "description": "string",
  "image": "string (URL)",
  "isActive": "boolean (default: true)",
  "sortOrder": "number (default: 0)",
  "seoTitle": "string",
  "seoDescription": "string"
}
Example Request:
{
  "name": "Executive Collection",
  "slug": "executive-collection",
  "description": "Premium leather goods for business professionals",
  "image": "https://example.com/executive.jpg",
  "isActive": true,
  "sortOrder": 1,
  "seoTitle": "Executive Leather Collection - MN Exim",
  "seoDescription": "Professional leather goods for the modern executive"
}

Bulk Product Creation API

Transform external e-commerce platform data into MN Exim products using configurable mappers.

GET/api/admin/products/use-fmt-0
Requires: admin:read

Get API documentation and available mapper configurations

Response Schema
Response Example:
{
  "success": true,
  "data": {
    "documentation": {
      "endpoint": "/api/admin/products/use-fmt-0",
      "method": "POST",
      "description": "Bulk product creation with format transformation",
      "authentication": "Admin JWT token required"
    },
    "mappers": {
      "presets": ["myntra", "basic", "preserve"],
      "configurations": {
        "myntra": { /* configuration details */ },
        "basic": { /* configuration details */ },
        "preserve": { /* configuration details */ }
      }
    }
  }
}
POST/api/admin/products/use-fmt-0
Requires: admin:write

Create products in bulk by transforming external format data

Request Body Schema
{
  "data": {
    "l": [
      {
        "data": {
          "url": "string - Product reference URL",
          "title": "string - Product name",
          "brand": "string - Brand name",
          "category": [
            { "name": "string - Category name" }
          ],
          "color": [
            {
              "id": "string - Color ID",
              "name": "string - Color name",
              "image": [
                { "url": "string - Image URL" }
              ]
            }
          ],
          "variant": [
            {
              "id": "string|null - Variant ID",
              "price": "string - Product price",
              "price_mrp": "string - MRP price",
              "size_id": "string - Size ID",
              "color_id": "string - Color ID",
              "currency": "string - Currency code"
            }
          ],
          "field": [
            {
              "typ": "detail|info - Field type",
              "l": [
                {
                  "name": "string - Field name",
                  "value": "string - Field value"
                }
              ]
            }
          ],
          "seller": {
            "name": "string - Seller name"
          }
        },
        "id": "string - Unique product ID",
        "name": "string - Product identifier"
      }
    ]
  },
  "mapper": "string - Optional preset mapper (myntra|basic|preserve)",
  "mapperConfig": {
    "defaultCategoryId": "number - Fallback category ID",
    "imageLimit": "number - Max images per product",
    "defaultInventory": "number - Default inventory count"
  }
}
Available Preset Mappers:
myntra
Fashion platforms with hierarchical categories
basic
Simple product imports with minimal config
preserve
Maximum data preservation strategy
Example Request (Myntra Format):
{
  "data": {
    "l": [
      {
        "data": {
          "url": "https://www.myntra.com/17814260",
          "title": "Trendyol Men Navy Blue Solid Shorts",
          "brand": "Trendyol",
          "category": [
            { "name": "Men" },
            { "name": "Apparel" },
            { "name": "Bottomwear" },
            { "name": "Shorts" }
          ],
          "color": [
            {
              "id": "Navy Blue",
              "name": "Navy Blue",
              "image": [
                { "url": "https://assets.myntassets.com/image1.jpg" },
                { "url": "https://assets.myntassets.com/image2.jpg" }
              ]
            }
          ],
          "variant": [
            {
              "id": null,
              "price": "559",
              "size_id": "32",
              "color_id": "Navy Blue",
              "currency": "INR",
              "price_mrp": "1399"
            }
          ],
          "field": [
            {
              "typ": "detail",
              "l": [
                {
                  "name": "Product Details",
                  "value": "Navy blue solid mid-rise regular shorts"
                }
              ]
            }
          ],
          "seller": { "name": "Supercom Net" }
        },
        "id": "04117a84-f47f-4dcd-91f9-7c0e37d8b3b6",
        "name": "navy-blue-shorts"
      }
    ]
  },
  "mapper": "myntra",
  "mapperConfig": {
    "defaultCategoryId": 1,
    "imageLimit": 5
  }
}
Success Response:
{
  "success": true,
  "message": "Processed 1 products. Created 1 successfully.",
  "data": {
    "created": 1,
    "errors": 0,
    "processed": 1,
    "errorDetails": []
  }
}
Error Response:
{
  "success": false,
  "message": "Processed 1 products. Created 0 successfully.",
  "data": {
    "created": 0,
    "errors": 1,
    "processed": 1,
    "errorDetails": [
      "Product abc-123: No matching category found for: Electronics"
    ]
  }
}

Key Features

  • Configurable Mappers: Transform data from different e-commerce platforms
  • Smart Category Resolution: Hierarchical and custom category mapping strategies
  • Image Processing: Multiple strategies for extracting and limiting product images
  • SEO Optimization: Automatic generation of SEO-friendly titles and descriptions
  • Comprehensive Validation: Input validation with detailed error reporting
  • Batch Processing: Process multiple products in a single request

Code Examples

cURL Examples

Get products with search and pagination:

curl "/api/products?search=leather&page=1&limit=5"

Create a product (requires token):

curl -X POST "/api/admin/products" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Premium Leather Wallet",
    "slug": "premium-leather-wallet",
    "description": "Handcrafted wallet with RFID protection",
    "price": "89.99",
    "categoryId": 3,
    "inventory": 25
  }'

JavaScript Example

// Get products with search and pagination
const response = await fetch('/api/products?search=leather&page=1&limit=10');
const data = await response.json();
console.log(data.data); // Array of products
console.log(data.meta); // Pagination info

// Create Personal Access Token
const tokenResponse = await fetch('/api/admin/tokens', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_EXISTING_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'E-commerce Integration',
    permissions: ['admin:read', 'admin:write'],
    expiresAt: '2025-12-31T23:59:59.000Z'
  })
});
const tokenData = await tokenResponse.json();
console.log(tokenData.token); // Save this token securely!

// Create product with detailed specifications
const productResponse = await fetch('/api/admin/products', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Premium Leather Briefcase',
    slug: 'premium-leather-briefcase',
    description: 'Professional briefcase made from top-grain leather',
    shortDescription: 'Professional leather briefcase',
    sku: 'PLB-001',
    price: '299.99',
    comparePrice: '399.99',
    costPrice: '150.00',
    inventory: 15,
    categoryId: 2,
    images: [
      'https://example.com/briefcase-main.jpg',
      'https://example.com/briefcase-interior.jpg'
    ],
    specifications: {
      material: 'Top-grain leather',
      color: ['Black', 'Brown'],
      closure: 'Dual lock system',
      compartments: 'Multiple'
    },
    features: [
      'Top-grain leather construction',
      'Dual lock system',
      'Multiple compartments',
      'Laptop sleeve included'
    ],
    tags: ['briefcase', 'leather', 'professional', 'business'],
    weight: '2.5',
    dimensions: {
      length: 42,
      width: 30,
      height: 12
    },
    isActive: true,
    isFeatured: true,
    seoTitle: 'Premium Leather Briefcase - Professional Business Bag',
    seoDescription: 'Elevate your professional image with our premium leather briefcase'
  })
});
const newProduct = await productResponse.json();

// Update product inventory
const updateResponse = await fetch(`/api/admin/products/${newProduct.data.id}`, {
  method: 'PUT',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    inventory: 20,
    isFeatured: false
  })
});

// Create category
const categoryResponse = await fetch('/api/admin/categories', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Business Accessories',
    slug: 'business-accessories',
    description: 'Professional leather accessories for business',
    parentId: null, // Root category
    isActive: true,
    sortOrder: 3
  })
});

SDKs & Libraries

JavaScript/Node.js

A simple wrapper class for easy API integration in JavaScript applications.

const api = new MNEximAPI('/api', 'your_token');

Python

Python client library with type hints and comprehensive error handling.

api = MNEximAPI(token='your_token')

Complete Documentation

For complete API documentation including all endpoints, parameters, and response schemas, see our comprehensive API guide in the project files or download the OpenAPI specification.

Request Validation

All request bodies are validated using Zod schemas. Required fields must be provided, and data types must match the schema. Validation errors return a 400 status with detailed error information.

Authentication Headers

All admin endpoints require authentication. Use one of these methods:

Authorization: Bearer your_personal_access_token
Cookie: admin-jwt=your_jwt_token