🛣️ API Routes Reference - Main System Integration

📋 Overview

COMPLETE API DOCUMENTATION - Detailed Swagger-style reference for all Partner Services API routes with request/response specifications, headers, and examples.

Base URL: http://localhost:3000/api/v1
Authentication: HMAC SHA-256 (see Authentication Guide)
Content Type: application/json
API Version: v1.0.0

🔐 Authentication Headers

Service-Level Authentication (Main System APIs)

yaml

Headers:
  x-service-id:
    type: string
    required: true
    example: "TESTING_1"
    description: Service identifier for main system
  x-timestamp:
    type: integer
    required: true
    example: 1753357991
    description: Unix timestamp for request
  x-signature:
    type: string
    required: true
    example: "a1b2c3d4e5f6..."
    description: HMAC SHA-256 signature

Partner-Level Authentication (Partner-specific APIs)

yaml

Headers:
  x-partner-id:
    type: string
    required: true
    example: "partner_001"
    description: Partner identifier
  x-timestamp:
    type: integer
    required: true
    example: 1753357991
    description: Unix timestamp for request
  x-signature:
    type: string
    required: true
    example: "a1b2c3d4e5f6..."
    description: HMAC SHA-256 signature

🏥 System Health & Monitoring

GET /health

Basic system health check

URL: GET http://localhost:3000/health

Headers: None required

Request Body: None

Response:

json

{
  "success": true,
  "status": "healthy",
  "message": "Partner Services Microservice is healthy",
  "timestamp": "2025-07-24T11:48:30.332Z",
  "version": "1.0.0",
  "environment": "development",
  "uptime": 2.209568792,
  "buildInfo": {
    "nodeVersion": "v18.20.8",
    "platform": "linux",
    "arch": "arm64"
  },
  "components": {
    "database": {
      "status": "healthy",
      "lastCheck": "2025-07-24T11:48:15.107Z",
      "responseTime": 2,
      "details": {
        "status": "healthy",
        "duration": "2ms",
        "timestamp": "2025-07-24T11:48:15.107Z"
      }
    },
    "redis": {
      "status": "healthy",
      "lastCheck": "2025-07-24T11:48:15.107Z",
      "responseTime": 0,
      "details": {
        "status": "healthy",
        "duration": "0ms",
        "timestamp": "2025-07-24T11:48:15.107Z",
        "connected": true
      }
    },
    "memory": {
      "usage": 246525344,
      "percentage": 90.20675883529923,
      "heapTotal": 273289216,
      "heapUsed": 246525344,
      "external": 1914152,
      "rss": 355454976
    }
  },
  "monitoring": {
    "metricsEndpoint": "/metrics",
    "livenessProbe": "/health/live",
    "readinessProbe": "/health/ready",
    "systemInfo": "/health/info"
  }
}

Status Codes:

200 - Service healthy
503 - Service unhealthy

🌍 Geographical Data APIs

GET /api/v1/cities

Get cities with comprehensive filtering

URL: GET http://localhost:3000/api/v1/cities

Authentication: Service-Level Required

Query Parameters:

yaml

# Primary Filters (Required for specific results)
stateIds:
  type: string
  required: false # Optional - filter by state
  pattern: "^[0-9]+(,[0-9]+)*$"
  example: "1,2,7"
  description: Comma-separated state IDs to filter cities
  comment: "Use this to get cities from specific states. Essential for zone creation workflow."

# Search Filters (Optional)
search:
  type: string
  required: false # Optional - text search
  minLength: 2
  maxLength: 100
  example: "Mumbai"
  description: Search cities by name (partial matching)
  comment: "Supports partial text matching. Useful for dropdown search."

# Pagination (Optional - has defaults)
page:
  type: integer
  required: false # Optional - defaults to 1
  minimum: 1
  default: 1
  example: 1
  description: Page number for pagination
  comment: "Default page size is 50. Use with limit for custom pagination."

limit:
  type: integer
  required: false # Optional - defaults to 50
  minimum: 1
  maximum: 100
  default: 50
  example: 20
  description: Number of cities per page
  comment: "Maximum 100 cities per request. Use pagination for large datasets."

# Sorting (Optional)
sortBy:
  type: string
  required: false # Optional - defaults to 'name'
  enum: ["name", "stateId", "createdAt"]
  default: "name"
  example: "name"
  description: Sort cities by field
  comment: "Most commonly used: 'name' for alphabetical, 'stateId' for grouping."

sortOrder:
  type: string
  required: false # Optional - defaults to 'asc'
  enum: ["asc", "desc"]
  default: "asc"
  example: "asc"
  description: Sort order
  comment: "Use 'desc' for reverse alphabetical or newest first."

# Advanced Filters (Optional)
includeState:
  type: boolean
  required: false # Optional - defaults to true
  default: true
  example: true
  description: Include state information in response
  comment: "Recommended to keep true for UI display. Adds stateName and stateCode."

forceRefresh:
  type: boolean
  required: false # Optional - defaults to false
  default: false
  example: false
  description: Force refresh from database (bypass cache)
  comment: "Use only for testing or when cache issues suspected. Slower response."

Response:

json

{
  "success": true,
  "data": [
    {
      "id": 137,
      "name": "ARARIA",
      "stateId": 1,
      "createdAt": "2025-07-15T09:49:59.043Z",
      "stateName": "BIHAR",
      "stateCode": "BIHAR"
    },
    {
      "id": 41,
      "name": "ARWAL",
      "stateId": 1,
      "createdAt": "2025-07-15T09:49:21.718Z",
      "stateName": "BIHAR",
      "stateCode": "BIHAR"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 5,
    "total": 38,
    "totalPages": 8,
    "hasNext": true,
    "hasPrev": false
  },
  "filters": {
    "stateIds": [1],
    "states": null,
    "search": null,
    "name": null,
    "populationRange": {},
    "coordinates": null,
    "searchMode": "partial"
  },
  "options": {
    "includeAreaCount": false,
    "includeState": true,
    "includeCoordinates": false,
    "includeMetadata": false,
    "fields": null
  },
  "execution_time_ms": 6,
  "from_cache": false,
  "request_id": "cities_list_1753357730130"
}

Status Codes:

200 - Cities retrieved successfully
400 - Invalid query parameters
401 - Authentication failed (missing or invalid service headers)
500 - Internal server error

Common Use Cases:

bash

# Get all cities from Bihar state
GET /api/v1/cities?stateIds=1

# Search for cities with "Mumbai" in name
GET /api/v1/cities?search=Mumbai

# Get cities from multiple states with pagination
GET /api/v1/cities?stateIds=1,8&page=1&limit=20

# Get cities sorted by creation date (newest first)
GET /api/v1/cities?sortBy=createdAt&sortOrder=desc

GET /api/v1/areas

Get areas with comprehensive filtering

URL: GET http://localhost:3000/api/v1/areas

Authentication: Service-Level Required

Query Parameters:

yaml

# Primary Filters (Use these for specific results)
cityIds:
  type: string
  required: false # Optional - filter by city
  pattern: "^[0-9]+(,[0-9]+)*$"
  example: "1,115"
  description: Comma-separated city IDs to filter areas
  comment: "Use this after selecting cities. Essential for zone creation workflow."

stateIds:
  type: string
  required: false # Optional - filter by state (via cities)
  pattern: "^[0-9]+(,[0-9]+)*$"
  example: "1,8"
  description: Comma-separated state IDs to filter areas
  comment: "Gets all areas from all cities in specified states. Broader filter than cityIds."

# Search Filters (Optional)
search:
  type: string
  required: false # Optional - text search
  minLength: 2
  maxLength: 100
  example: "Andheri"
  description: Search areas by name (partial matching)
  comment: "Useful for finding specific areas like 'Andheri', 'Sector', etc."

# Pagination (Optional - has defaults)
page:
  type: integer
  required: false # Optional - defaults to 1
  minimum: 1
  default: 1
  example: 1
  description: Page number for pagination
  comment: "Areas can be numerous - always use pagination for performance."

limit:
  type: integer
  required: false # Optional - defaults to 50
  minimum: 1
  maximum: 100
  default: 50
  example: 20
  description: Number of areas per page
  comment: "Recommended limit: 20-50 for UI performance."

# Sorting (Optional)
sortBy:
  type: string
  required: false # Optional - defaults to 'name'
  enum: ["name", "cityId", "createdAt"]
  default: "name"
  example: "name"
  description: Sort areas by field
  comment: "Use 'cityId' to group areas by city, 'name' for alphabetical."

sortOrder:
  type: string
  required: false # Optional - defaults to 'asc'
  enum: ["asc", "desc"]
  default: "asc"
  example: "asc"
  description: Sort order

# Include Options (Optional)
includeCity:
  type: boolean
  required: false # Optional - defaults to true
  default: true
  example: true
  description: Include city information in response
  comment: "Recommended true for UI display. Adds cityName."

includeState:
  type: boolean
  required: false # Optional - defaults to true
  default: true
  example: true
  description: Include state information in response
  comment: "Adds stateName and stateCode. Useful for breadcrumb navigation."

# Advanced Options (Optional)
forceRefresh:
  type: boolean
  required: false # Optional - defaults to false
  default: false
  example: false
  description: Force refresh from database (bypass cache)
  comment: "Use only for testing. Cache is now properly fixed for filtering."

Response:

json

{
  "success": true,
  "data": [
    {
      "id": 12,
      "name": "A. H. GUARD",
      "cityId": 1,
      "createdAt": "2025-07-15T09:12:29.043Z",
      "cityName": "PATNA",
      "stateId": 1,
      "stateName": "BIHAR",
      "stateCode": "BIHAR"
    },
    {
      "id": 6108,
      "name": "A.PIPLAWAN",
      "cityId": 1,
      "createdAt": "2025-07-15T09:49:23.138Z",
      "cityName": "PATNA",
      "stateId": 1,
      "stateName": "BIHAR",
      "stateCode": "BIHAR"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 5,
    "total": 499,
    "totalPages": 100,
    "hasNext": true,
    "hasPrev": false
  },
  "filters": {
    "cityIds": [1],
    "cities": null,
    "stateIds": null,
    "states": null,
    "search": null,
    "name": null,
    "type": "all",
    "zone": null,
    "pincodeCountRange": {},
    "coordinates": null,
    "searchMode": "partial"
  },
  "options": {
    "includePincodeCount": false,
    "includeCity": true,
    "includeState": true,
    "includeCoordinates": false,
    "includeMetadata": false,
    "includePincodes": false,
    "fields": null
  },
  "execution_time_ms": 14,
  "from_cache": false,
  "request_id": "areas_list_1753357999960"
}

Status Codes:

200 - Areas retrieved successfully
400 - Invalid query parameters
401 - Authentication failed
500 - Internal server error

Common Use Cases:

bash

# Get all areas from Patna city
GET /api/v1/areas?cityIds=1

# Get all areas from Bihar state (via cities)
GET /api/v1/areas?stateIds=1

# Search for areas containing "Sector"
GET /api/v1/areas?search=Sector

# Get areas from multiple cities with pagination
GET /api/v1/areas?cityIds=1,115&page=1&limit=20

💰 Customer Charge Management APIs

GET /api/v1/customer-charges

Get customer charge configurations

URL: GET http://localhost:3000/api/v1/customer-charges

Authentication: Service-Level Required

Query Parameters:

yaml

# Filter Options (All Optional)
partnerId:
  type: string
  required: false # Optional - filter by partner
  example: "partner_001"
  description: Filter charges for specific partner
  comment: "Leave empty to get global/default charges. Use for partner-specific charges."

type:
  type: string
  required: false # Optional - filter by charge type
  enum: ["fsc", "docket", "cod", "insurance"]
  example: "fsc"
  description: Filter by charge type
  comment: "fsc=Fuel Surcharge, docket=Document fee, cod=Cash on Delivery, insurance=Insurance fee"

chargeType:
  type: string
  required: false # Optional - filter by calculation method
  enum: ["flat", "percentage"]
  example: "percentage"
  description: Filter by calculation method
  comment: "flat=Fixed amount (₹), percentage=% of shipment value"

status:
  type: boolean
  required: false # Optional - filter by active status
  example: true
  description: Filter by active status
  comment: "true=Active charges only, false=Inactive only, omit=All charges"

# Pagination (Optional)
page:
  type: integer
  required: false # Optional - defaults to 1
  minimum: 1
  default: 1
  example: 1

limit:
  type: integer
  required: false # Optional - defaults to 20
  minimum: 1
  maximum: 100
  default: 20
  example: 50

Response:

json

{
  "success": true,
  "data": [
    {
      "id": 1,
      "partnerId": "partner_001",
      "customerId": null,
      "type": "fsc",
      "chargeType": "percentage",
      "value": 3.5,
      "minKg": 0.5,
      "maxKg": 10.0,
      "status": true,
      "createdAt": "2025-07-20T10:00:00.000Z",
      "applicableFor": "partner_customers"
    },
    {
      "id": 2,
      "partnerId": null,
      "customerId": "customer_123",
      "type": "cod",
      "chargeType": "flat",
      "value": 25.0,
      "status": true,
      "createdAt": "2025-07-20T11:00:00.000Z",
      "applicableFor": "specific_customer"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 25,
    "totalPages": 2
  },
  "summary": {
    "totalCharges": 25,
    "activeCharges": 22,
    "byType": {
      "fsc": 8,
      "docket": 6,
      "cod": 7,
      "insurance": 4
    },
    "byChargeType": {
      "flat": 12,
      "percentage": 13
    }
  },
  "execution_time_ms": 89
}

POST /api/v1/customer-charges/bulk

Create multiple customer charges

URL: POST http://localhost:3000/api/v1/customer-charges/bulk

Authentication: Service-Level Required

Request Body:

json

{
  "charges": [
    {
      "partnerId": "partner_001",
      "type": "fsc",
      "chargeType": "percentage",
      "value": 3.5,
      "customerId": null,
      "minKg": 0.5,
      "maxKg": 10.0,
      "status": true
    },
    {
      "partnerId": "partner_001",
      "type": "cod",
      "chargeType": "flat",
      "value": 25.0,
      "customerId": "customer_123",
      "status": true
    },
    {
      "partnerId": "partner_001",
      "type": "insurance",
      "chargeType": "percentage",
      "value": 0.5,
      "minKg": 0.1,
      "maxKg": 50.0,
      "status": true
    }
  ]
}

Required Fields:

yaml

partnerId:
  type: string
  required: true
  description: Partner identifier
  example: "partner_001"
  comment: "Must be valid partner ID. Use for partner-specific charges."

type:
  type: string
  required: true
  enum: ["fsc", "docket", "cod", "insurance"]
  description: Charge type
  comment: "fsc=Fuel Surcharge, docket=Document fee, cod=COD fee, insurance=Insurance fee"

chargeType:
  type: string
  required: true
  enum: ["flat", "percentage"]
  description: Calculation method
  comment: "flat=Fixed ₹ amount, percentage=% of shipment/COD value"

value:
  type: number
  required: true
  minimum: 0.01
  description: Charge value
  comment: "For flat: amount in ₹, for percentage: % value (e.g., 3.5 for 3.5%)"

Response:

json

{
  "success": true,
  "data": {
    "created": 3,
    "total": 3,
    "failed": 0,
    "charges": [
      {
        "id": 27,
        "partnerId": "partner_001",
        "type": "fsc",
        "status": "created",
        "message": "FSC charge created successfully"
      },
      {
        "id": 28,
        "partnerId": "partner_001",
        "type": "cod",
        "status": "created",
        "message": "COD charge created successfully"
      },
      {
        "id": 29,
        "partnerId": "partner_001",
        "type": "insurance",
        "status": "created",
        "message": "Insurance charge created successfully"
      }
    ],
    "errors": []
  },
  "summary": {
    "partnerId": "partner_001",
    "totalChargesAfterCreation": 12,
    "chargesByType": {
      "fsc": 3,
      "cod": 4,
      "docket": 2,
      "insurance": 3
    }
  },
  "execution_time_ms": 298
}

🎯 Discount Management APIs

GET /api/v1/discounts

Get discount configurations with filtering

URL: GET http://localhost:3000/api/v1/discounts

Authentication: Service-Level Required

Query Parameters:

yaml

# Filter Options (All Optional)
partnerId:
  type: string
  required: false # Optional - query parameter for service auth
  example: "partner_001"
  description: Partner ID for service-level access
  comment: "Required when using service auth. Omit to get all discounts (admin access)."

discountType:
  type: string
  required: false # Optional - filter by discount type
  enum: ["flat", "percentage"]
  example: "percentage"
  description: Filter by discount type
  comment: "flat=Fixed ₹ discount, percentage=% discount on charges"

status:
  type: boolean
  required: false # Optional - filter by active status
  example: true
  description: Filter by active status
  comment: "true=Active only, false=Inactive only, omit=All discounts"

validOnly:
  type: boolean
  required: false # Optional - filter by current validity
  default: false
  example: true
  description: Only return currently valid discounts
  comment: "Checks validFrom/validTo dates against current time"

# Weight Range Filters (Optional)
minWeight:
  type: number
  required: false # Optional - minimum weight filter
  example: 1.0
  description: Filter by minimum weight range
  comment: "Get discounts applicable to shipments >= this weight"

maxWeight:
  type: number
  required: false # Optional - maximum weight filter
  example: 10.0
  description: Filter by maximum weight range
  comment: "Get discounts applicable to shipments <= this weight"

# Pagination (Optional)
page:
  type: integer
  required: false # Optional - defaults to 1
  minimum: 1
  default: 1
  example: 1

limit:
  type: integer
  required: false # Optional - defaults to 10
  minimum: 1
  maximum: 100
  default: 10
  example: 20

Response:

json

{
  "success": true,
  "data": [
    {
      "id": 1,
      "partnerId": "partner_001",
      "fromWeight": 1.0,
      "toWeight": 10.0,
      "discountType": "percentage",
      "discountValue": 15.5,
      "description": "Bulk shipment discount for 1kg to 10kg",
      "validFrom": "2025-07-17T00:00:00Z",
      "validTo": "2025-12-31T23:59:59Z",
      "status": true,
      "isCurrentlyValid": true,
      "createdAt": "2025-07-16T10:30:00Z",
      "applicabilityRules": {
        "weightRange": "1.0kg - 10.0kg",
        "validityPeriod": "Jul 17, 2025 - Dec 31, 2025",
        "applicableShipments": "All B2B and B2C"
      }
    },
    {
      "id": 2,
      "partnerId": "partner_001",
      "fromWeight": 5.0,
      "toWeight": 25.0,
      "discountType": "flat",
      "discountValue": 100.0,
      "description": "Heavy package flat discount",
      "validFrom": null,
      "validTo": null,
      "status": true,
      "isCurrentlyValid": true,
      "createdAt": "2025-07-16T11:00:00Z",
      "applicabilityRules": {
        "weightRange": "5.0kg - 25.0kg",
        "validityPeriod": "Always valid",
        "applicableShipments": "Heavy packages"
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 12,
    "totalPages": 2,
    "hasNext": true,
    "hasPrev": false
  },
  "summary": {
    "partnerId": "partner_001",
    "totalDiscounts": 12,
    "activeDiscounts": 10,
    "validDiscounts": 8,
    "discountsByType": {
      "percentage": 7,
      "flat": 5
    },
    "avgDiscountPercentage": 12.3,
    "totalPotentialSavings": "₹45,680.75"
  },
  "execution_time_ms": 67
}

POST /api/v1/discounts

Create new discount configuration

URL: POST http://localhost:3000/api/v1/discounts

Authentication: Service-Level Required

Request Body:

json

{
  "partnerId": "partner_001",
  "fromWeight": 1.0,
  "toWeight": 10.0,
  "discountType": "percentage",
  "discountValue": 15.5,
  "description": "Bulk shipment discount for 1kg to 10kg - Q4 2025",
  "validFrom": "2025-07-17T00:00:00Z",
  "validTo": "2025-12-31T23:59:59Z",
  "status": true
}

Required Fields:

yaml

partnerId:
  type: string
  required: true
  description: Partner identifier
  example: "partner_001"
  comment: "Can be passed as query parameter (?partnerId=partner_001) or in request body"

fromWeight:
  type: number
  required: true
  minimum: 0.001
  maximum: 50000
  description: Minimum weight for discount (in kg)
  example: 0.5
  comment: "Weight range start. Must be less than toWeight."

toWeight:
  type: number
  required: true
  minimum: 0.001
  maximum: 50000
  description: Maximum weight for discount (in kg)
  example: 5.0
  comment: "Weight range end. Must be greater than fromWeight."

discountType:
  type: string
  required: true
  enum: ["flat", "percentage"]
  description: Type of discount calculation
  example: "percentage"
  comment: "flat = ₹ amount discount, percentage = % of total charges"

discountValue:
  type: number
  required: true
  minimum: 0.01
  description: Discount value
  example: 15.5
  comment: "For flat: amount in ₹, for percentage: % value (e.g., 15.5 for 15.5%)"

Validation Rules:

Weight ranges cannot overlap for the same partner
toWeight must be greater than fromWeight
validTo must be after validFrom (if both provided)
Discount value must be reasonable (≤ 100% for percentage, ≤ ₹10,000 for flat)

Response:

json

{
  "success": true,
  "data": {
    "id": 13,
    "partnerId": "partner_001",
    "fromWeight": 1.0,
    "toWeight": 10.0,
    "discountType": "percentage",
    "discountValue": 15.5,
    "description": "Bulk shipment discount for 1kg to 10kg - Q4 2025",
    "validFrom": "2025-07-17T00:00:00Z",
    "validTo": "2025-12-31T23:59:59Z",
    "status": true,
    "isCurrentlyValid": true,
    "createdAt": "2025-07-24T12:30:00.000Z",
    "applicabilityRules": {
      "weightRange": "1.0kg - 10.0kg",
      "validityPeriod": "Jul 17, 2025 - Dec 31, 2025",
      "estimatedMonthlyUsage": "~150 shipments"
    }
  },
  "execution_time_ms": 123
}

Status Codes:

201 - Discount created successfully
400 - Validation error or weight range overlap
401 - Authentication required
409 - Discount weight range overlaps with existing
500 - Internal server error

👥 Partner Data Retrieval APIs

GET /api/v1/partners/comprehensive-data

Get complete partner data

URL: GET http://localhost:3000/api/v1/partners/comprehensive-data

Authentication: Service-Level Required

Query Parameters:

yaml

# Primary Filter (Required for service-level auth)
partnerId:
  type: string
  required: false # Optional for admin access, required for service-level
  example: "partner_001"
  description: Partner identifier for service-level authentication
  comment: "REQUIRED when using service auth. Use ?partnerId=partner_001 format."

# Response Format Options (Optional)
format:
  type: string
  required: false # Optional - defaults to 'standard'
  enum: ["minimal", "standard", "detailed"]
  default: "standard"
  example: "detailed"
  description: Response detail level
  comment: "minimal=IDs only, standard=basic info, detailed=full data with stats"

# Include Options (Optional)
includeStatistics:
  type: boolean
  required: false # Optional - defaults to true
  default: true
  example: true
  description: Include performance statistics
  comment: "Adds shipment volumes, success rates, delivery times"

includeMetadata:
  type: boolean
  required: false # Optional - defaults to true
  default: true
  example: true
  description: Include metadata information
  comment: "Adds cache info, sync status, data versions"

includeInactive:
  type: boolean
  required: false # Optional - defaults to false
  default: false
  example: false
  description: Include inactive/disabled data
  comment: "Set true to include inactive zones, services, charges"

Response:

json

{
  "success": true,
  "data": {
    "partnerId": "partner_001",
    "partnerName": "Express Logistics",
    "status": "ACTIVE",
    "lastUpdated": "2025-07-24T10:30:00.000Z",

    "zones": {
      "success": true,
      "total": 5,
      "active": 4,
      "data": [
        {
          "id": 5,
          "name": "Mumbai Central Zone",
          "status": "ACTIVE",
          "pincodeCount": 250,
          "serviceCount": 3,
          "coverage": "Maharashtra Central"
        }
      ]
    },

    "packages": {
      "success": true,
      "total": 8,
      "active": 7,
      "data": [
        {
          "id": 12,
          "packageName": "Standard Package",
          "maxWeight": 5000,
          "baseCharge": 80.0,
          "status": "ACTIVE"
        }
      ]
    },

    "services": {
      "success": true,
      "total": 6,
      "active": 5,
      "data": [
        {
          "serviceTypeId": 1,
          "serviceTypeName": "EXPRESS",
          "displayName": "Express Delivery",
          "isAvailable": true,
          "customCharge": 60.0
        }
      ]
    },

    "charges": {
      "success": true,
      "customerCharges": {
        "total": 15,
        "active": 12,
        "data": [
          {
            "id": 1,
            "type": "fsc",
            "chargeType": "percentage",
            "value": 3.5,
            "status": true
          }
        ]
      },
      "distanceCharges": {
        "total": 10,
        "active": 8,
        "data": [
          {
            "id": 1,
            "distanceFrom": 0,
            "distanceTo": 10,
            "charge": 50.0,
            "chargeType": "flat"
          }
        ]
      }
    },

    "discounts": {
      "success": true,
      "total": 12,
      "active": 10,
      "validDiscounts": 8,
      "data": [
        {
          "id": 1,
          "discountType": "percentage",
          "discountValue": 15.0,
          "fromWeight": 1.0,
          "toWeight": 10.0,
          "isCurrentlyValid": true
        }
      ]
    },

    "statistics": {
      "totalShipments": 15420,
      "monthlyVolume": 2340,
      "averageDeliveryTime": 36.5,
      "successRate": 98.2,
      "avgMonthlyRevenue": "₹2,45,600",
      "topRoutes": [
        { "route": "Mumbai-Delhi", "shipments": 450 },
        { "route": "Delhi-Bangalore", "shipments": 380 }
      ]
    },

    "metadata": {
      "lastSync": "2025-07-24T10:30:00.000Z",
      "dataVersion": "v1.2.3",
      "cacheExpiry": "2025-07-24T12:30:00.000Z",
      "dataCompleteness": {
        "zones": "100%",
        "packages": "100%",
        "services": "95%",
        "charges": "100%",
        "discounts": "90%"
      }
    }
  },
  "execution_time_ms": 567,
  "from_cache": true,
  "request_id": "comprehensive_1753357999960"
}

Authentication Examples:

bash

# Service-level access
GET /api/v1/partners/comprehensive-data?partnerId=partner_001
Headers:
  x-service-id: TESTING_1
  x-timestamp: 1753357991
  x-signature: abc123...

# Alternative URL path (also works)
GET /api/v1/partners/comprehensive-data/partner_001
Headers: (same as above)

Status Codes:

200 - Data retrieved successfully
400 - Invalid partnerId or parameters
401 - Authentication failed or missing partnerId for service auth
404 - Partner not found
500 - Internal server error

GET /api/v1/partner-packages/{partnerId}

Get packages for specific partner

URL: GET http://localhost:3000/api/v1/partner-packages/partner_001

Authentication: Service-Level Required (via mainSystemRateLimit)

Path Parameters:

yaml

partnerId:
  type: string
  required: true
  pattern: "^[a-zA-Z0-9_-]{3,50}$"
  example: "partner_001"
  description: Partner identifier
  comment: "Must match format: letters, numbers, hyphens, underscores"

Query Parameters:

yaml

# Package Type Filters (Optional)
includeCharges:
  type: boolean
  required: false # Optional - defaults to true
  default: true
  example: true
  description: Include package charge data
  comment: "Basic package configurations and base charges"

includeWeightCharges:
  type: boolean
  required: false # Optional - defaults to true
  default: true
  example: true
  description: Include weight charge data
  comment: "Zone-specific weight-based charges"

# Display Options (Optional)
includeZoneMapping:
  type: boolean
  required: false # Optional - defaults to true
  default: true
  example: true
  description: Include zone mapping information
  comment: "Shows fromZone and toZone names instead of just IDs"

sortBy:
  type: string
  required: false # Optional - defaults to 'createdAt'
  enum: ["packageId", "packageName", "createdAt"]
  default: "createdAt"
  example: "packageName"
  description: Sort packages by field
  comment: "packageId for PackageWeightCharge, packageName for PackageCharge"

# Pagination (Optional)
page:
  type: integer
  required: false # Optional - defaults to 1
  minimum: 1
  default: 1
  example: 1

limit:
  type: integer
  required: false # Optional - defaults to 50
  minimum: 1
  maximum: 100
  default: 50
  example: 20

Response:

json

{
  "success": true,
  "data": {
    "partnerId": "partner_001",
    "partnerName": "Express Logistics",
    "packages": [
      {
        "id": 1,
        "packageId": "STD_PKG_001",
        "packageName": "Standard Package",
        "baseWeight": 1.5,
        "baseCharge": 65.0,
        "addonWeight": 0.5,
        "addonCharge": 22.0,
        "fromZoneId": 1,
        "toZoneId": 3,
        "status": true,
        "createdAt": "2025-07-15T09:49:22.491Z",
        "zoneMapping": {
          "fromZone": "Delhi Metro Zone",
          "toZone": "Mumbai Metro Zone"
        },
        "applicability": "zone_specific"
      },
      {
        "id": 2,
        "packageId": "EXP_PKG_001",
        "packageName": "Express Package",
        "baseWeight": 2.0,
        "baseCharge": 85.0,
        "addonWeight": 0.5,
        "addonCharge": 28.0,
        "fromZoneId": null,
        "toZoneId": null,
        "status": true,
        "createdAt": "2025-07-15T09:49:23.138Z",
        "zoneMapping": null,
        "applicability": "general"
      }
    ],
    "summary": {
      "totalPackages": 8,
      "activePackages": 7,
      "generalPackages": 3,
      "zoneSpecificPackages": 5,
      "avgBaseCharge": 74.5,
      "weightRangeSupported": "0.1kg - 50kg"
    },
    "partnerCache": {
      "partnerId": "partner_001",
      "isActive": true,
      "lastUpdated": "2025-07-24T10:30:00.000Z"
    }
  },
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 8,
    "totalPages": 1,
    "hasNext": false,
    "hasPrev": false
  },
  "execution_time_ms": 178,
  "from_cache": false,
  "request_id": "packages_1753357999960"
}

Status Codes:

200 - Packages retrieved successfully
400 - Invalid partnerId format
401 - Authentication failed
404 - Partner not found
500 - Internal server error

🚀 Partner Availability & Assignment APIs

POST /api/v1/partners/availability/check

Check partner availability

URL: POST http://localhost:3000/api/v1/partners/availability/check

Authentication: Service-Level Required

Request Body:

json

{
  "pickupPincode": "110001",
  "deliveryPincode": "400001",
  "weight": 2500,
  "shipmentType": "B2C",
  "paymentType": "COD",
  "serviceRequirements": ["PICKUP", "DELIVERY", "COD"],
  "partnerId": "partner_001",
  "urgency": "STANDARD",
  "declaredValue": 3500,
  "maxDeliveryTime": 48,
  "preferredServices": ["EXPRESS"],
  "excludePartners": ["partner_002"]
}

Required Fields:

yaml

pickupPincode:
  type: string
  required: true
  pattern: "^[0-9]{6}$"
  example: "110001"
  comment: "Must be valid 6-digit Indian pincode"

deliveryPincode:
  type: string
  required: true
  pattern: "^[0-9]{6}$"
  example: "400001"
  comment: "Must be valid 6-digit Indian pincode"

weight:
  type: number
  required: true
  minimum: 1
  maximum: 50000
  example: 2500
  description: Weight in grams
  comment: "1g to 50kg supported. Used for charge calculation."

shipmentType:
  type: string
  required: true
  enum: ["B2B", "B2C"]
  example: "B2C"
  comment: "B2B=Business to Business, B2C=Business to Customer"

paymentType:
  type: string
  required: true
  enum: ["COD", "PREPAID"]
  example: "COD"
  comment: "COD=Cash on Delivery, PREPAID=Payment in advance"

serviceRequirements:
  type: array
  required: true
  items:
    type: string
    enum: ["PICKUP", "DELIVERY", "COD", "PREPAID", "ODA", "HILL", "EXPRESS"]
  example: ["PICKUP", "DELIVERY", "COD"]
  comment: "PICKUP and DELIVERY are typically mandatory for most shipments"

Response:

json

{
  "success": true,
  "data": {
    "checkType": "specific_partner",
    "isAvailable": true,
    "confidence": 95,
    "partnerId": "partner_001",
    "partnerName": "Express Logistics",

    "coverage": {
      "pickup": {
        "pincode": "110001",
        "area": "Connaught Place",
        "city": "New Delhi",
        "zone": "North Delhi Zone",
        "isServiced": true,
        "serviceType": "PICKUP"
      },
      "delivery": {
        "pincode": "400001",
        "area": "Fort",
        "city": "Mumbai",
        "zone": "Mumbai Central Zone",
        "isServiced": true,
        "serviceType": "DELIVERY"
      }
    },

    "services": {
      "required": ["PICKUP", "DELIVERY", "COD"],
      "matched": ["PICKUP", "DELIVERY", "COD"],
      "available": ["PICKUP", "DELIVERY", "COD", "EXPRESS", "INSURANCE"],
      "unavailable": [],
      "matchPercentage": 100
    },

    "estimates": {
      "totalCost": 285.5,
      "deliveryTime": {
        "hours": 36,
        "deliveryDate": "2025-07-26T18:00:00.000Z",
        "description": "24-48 hours"
      },
      "breakdown": {
        "baseCharge": 120.0,
        "weightCharge": 85.0,
        "codCharge": 25.0,
        "fuelSurcharge": 10.5,
        "taxes": 45.0
      }
    },

    "capabilities": {
      "maxWeight": 50000,
      "maxDimensions": "200x200x200 cm",
      "maxCodAmount": 100000,
      "supportedPaymentTypes": ["COD", "PREPAID"],
      "cutoffTime": "18:00",
      "weekendDelivery": true,
      "sameDay": false
    },

    "restrictions": {
      "weightLimits": "50kg max",
      "valueLimits": "₹1,00,000 COD max",
      "areaRestrictions": [],
      "timeRestrictions": "No Sunday pickup"
    }
  },
  "execution_time_ms": 234,
  "check_id": "avail_1753357999960"
}

Alternative Response - When No partnerId (Find All Available Partners):

json

{
  "success": true,
  "data": {
    "checkType": "find_all_available",
    "availablePartners": [
      {
        "partnerId": "partner_001",
        "partnerName": "Express Logistics",
        "confidence": 95,
        "estimatedCost": 285.5,
        "estimatedDelivery": "24-48 hours",
        "serviceMatch": 100,
        "capabilities": ["EXPRESS", "COD", "INSURANCE"]
      },
      {
        "partnerId": "partner_002",
        "partnerName": "Fast Courier",
        "confidence": 88,
        "estimatedCost": 295.0,
        "estimatedDelivery": "48-72 hours",
        "serviceMatch": 100,
        "capabilities": ["STANDARD", "COD"]
      }
    ],
    "summary": {
      "totalChecked": 5,
      "availableCount": 2,
      "bestOption": "partner_001",
      "avgCost": 290.25,
      "fastestDelivery": "24-48 hours"
    }
  },
  "execution_time_ms": 445
}

Status Codes:

200 - Availability check successful
400 - Invalid request parameters
401 - Authentication failed
404 - Pincodes not found in system
422 - No partners available for route
500 - Availability check error

POST /api/v1/shipment-assignment/assign

Assign shipment to partner

URL: POST http://localhost:3000/api/v1/shipment-assignment/assign

Authentication: Service-Level Required

Request Body:

json

{
  "shipmentDetails": {
    "shipmentId": "SH_1721123456789",
    "fromPincode": "110001",
    "toPincode": "400001",
    "weight": 2500,
    "declaredValue": 3500,
    "shipmentType": "B2C",
    "paymentType": "COD",
    "serviceTypes": ["PICKUP", "DELIVERY", "EXPRESS", "COD"],
    "urgency": "EXPRESS"
  },

  "assignmentPreferences": {
    "assignmentStrategy": "BEST_MATCH"
  },

  "options": {
    "includePartnerDetails": true,
    "includeCostEstimate": true
  }
}

Required Fields:

yaml

shipmentDetails.shipmentId:
  type: string
  required: true
  pattern: "^[a-zA-Z0-9_-]+$"
  example: "SH_1721123456789"
  comment: "Unique shipment identifier. Supports alphanumeric, hyphens, underscores."

shipmentDetails.serviceTypes:
  type: array
  required: true
  items:
    type: string
    enum: ["PICKUP", "DELIVERY", "EXPRESS", "COD", "PREPAID", "INSURANCE"]
  example: ["PICKUP", "DELIVERY", "EXPRESS", "COD"]
  comment: "PICKUP and DELIVERY are MANDATORY. Add other services as needed."

assignmentPreferences.assignmentStrategy:
  type: string
  required: true
  enum: ["BEST_MATCH", "FASTEST", "CHEAPEST", "MOST_RELIABLE", "BALANCED"]
  example: "BEST_MATCH"
  comment: "BEST_MATCH recommended for optimal balance of cost, speed, reliability."

Response:

json

{
  "success": true,
  "data": {
    "success": true,
    "assignment": {
      "assignmentId": "ASG_1753356951709_a964e92d",
      "shipmentId": "SH_1721123456789",
      "partnerId": "partner_001",
      "partnerName": "Express Logistics",
      "status": "ASSIGNED",
      "assignedAt": "2025-07-24T11:35:51.710Z",

      "estimates": {
        "pickupDate": "2025-07-25T10:00:00.000Z",
        "deliveryDate": "2025-07-26T18:00:00.000Z",
        "deliveryWindow": "24-48 hours",
        "totalCost": 285.5
      },

      "partnerContact": {
        "name": "Partner Operations",
        "phone": "+91-9876543200",
        "email": "ops@expresslogistics.com",
        "trackingUrl": "https://track.expresslogistics.com"
      },

      "tracking": {
        "trackingNumber": "TRK_EXP_1721123456789",
        "trackingUrl": "https://track.expresslogistics.com/TRK_EXP_1721123456789",
        "statusUpdates": "SMS and Email enabled"
      },

      "costBreakdown": {
        "baseCharge": 120.0,
        "weightCharge": 85.0,
        "codCharge": 25.0,
        "expressCharge": 30.0,
        "fuelSurcharge": 10.5,
        "taxes": 15.0,
        "total": 285.5
      }
    },
    "error": null,
    "metadata": {
      "assignmentId": "ASG_1753356951709_a964e92d",
      "processingTime": 1,
      "timestamp": "2025-07-24T11:35:51.710Z"
    }
  },
  "metadata": {
    "requestId": "req_1753356951709",
    "processingTime": 189,
    "timestamp": "2025-07-24T11:35:51.710Z",
    "version": "1.0.0"
  }
}

Error Response - No Capable Partners:

json

{
  "success": true,
  "data": {
    "success": false,
    "assignment": null,
    "error": {
      "code": "NO_CAPABLE_PARTNERS",
      "message": "No partners found that can handle this shipment",
      "details": [
        "No partner covers route: 110001 → 400001",
        "Required services not available: EXPRESS + COD",
        "Weight exceeds partner limits: 2.5kg"
      ],
      "suggestions": [
        "Try STANDARD service instead of EXPRESS",
        "Consider splitting shipment if weight is high",
        "Check if pincodes are correct"
      ]
    },
    "metadata": {
      "partnersChecked": 5,
      "failureReasons": {
        "no_route_coverage": 3,
        "service_unavailable": 2,
        "weight_exceeded": 1
      }
    }
  }
}

Status Codes:

200 - Request processed (check data.success for assignment result)
400 - Invalid assignment parameters
401 - Authentication failed
422 - Business logic validation failed
500 - Assignment system error

💰 Charge Calculation APIs

POST /api/v1/shipments/calculate-charges

Shipment charge calculation

URL: POST http://localhost:3000/api/v1/shipments/calculate-charges

Authentication: Service-Level Required

Request Body:

json

{
  "partnerId": "partner_001",
  "pickupPincode": "110001",
  "deliveryPincode": "400001",
  "weight": 2500,
  "shipmentType": "B2C",
  "paymentType": "COD",
  "declaredValue": 3500,
  "serviceRequirements": ["PICKUP", "DELIVERY", "COD"],
  "customerType": "RETAIL",
  "packageDimensions": {
    "length": 30,
    "width": 20,
    "height": 15
  },
  "specialRequirements": ["FRAGILE"],
  "deliveryInstructions": "Call before delivery"
}

Required Fields:

yaml

partnerId:
  type: string
  required: true
  example: "partner_001"
  comment: "Partner to calculate charges for. Must be active partner."

pickupPincode:
  type: string
  required: true
  pattern: "^[0-9]{6}$"
  example: "110001"
  comment: "Valid 6-digit Indian pincode for pickup location."

deliveryPincode:
  type: string
  required: true
  pattern: "^[0-9]{6}$"
  example: "400001"
  comment: "Valid 6-digit Indian pincode for delivery location."

weight:
  type: number
  required: true
  minimum: 1
  maximum: 50000
  example: 2500
  description: Weight in grams
  comment: "1g to 50kg supported. Primary factor for charge calculation."

shipmentType:
  type: string
  required: true
  enum: ["B2B", "B2C"]
  example: "B2C"
  comment: "Affects pricing and service availability."

paymentType:
  type: string
  required: true
  enum: ["COD", "PREPAID"]
  example: "COD"
  comment: "COD may have additional charges. PREPAID often gets discounts."

Optional Fields with Defaults:

yaml

declaredValue:
  type: number
  required: false
  minimum: 0
  maximum: 1000000
  default: 0
  example: 3500
  comment: "Used for insurance calculation. ₹0 means no insurance."

serviceRequirements:
  type: array
  required: false
  items:
    type: string
    enum: ["PICKUP", "DELIVERY", "COD", "PREPAID", "ODA", "HILL"]
  default: []
  example: ["PICKUP", "DELIVERY"]
  comment: "Additional services required. May affect availability and cost."

customerType:
  type: string
  required: false
  enum: ["RETAIL", "CORPORATE", "ENTERPRISE", "SME"]
  default: "RETAIL"
  example: "RETAIL"
  comment: "May affect pricing tiers and discount eligibility."

Response:

json

{
  "success": true,
  "data": {
    "calculationId": "calc_1753357999960",
    "available": true,
    "partner": {
      "partnerId": "partner_001",
      "name": "Express Logistics",
      "isActive": true
    },
    "shipment": {
      "pickupPincode": "110001",
      "deliveryPincode": "400001",
      "weight": 2500,
      "shipmentType": "B2C",
      "paymentType": "COD",
      "declaredValue": 3500
    },

    "coverage": {
      "pickupCovered": true,
      "deliveryCovered": true,
      "estimatedDistance": 1150.5,
      "estimatedTime": "24-48 hours",
      "availableServices": ["PICKUP", "DELIVERY", "COD", "EXPRESS"]
    },

    "charges": {
      "weightCharge": 85.5,
      "distanceCharge": 45.0,
      "fscCharge": 10.5,
      "codCharge": 25.0,
      "docketCharge": 15.0,
      "insuranceCharge": 17.5,
      "otherCharges": 12.0,
      "subtotal": 210.5,
      "discountAmount": 21.05,
      "taxableAmount": 189.45,
      "gstAmount": 34.1,
      "totalAmount": 223.55
    },

    "discountsApplied": [
      {
        "discountId": 1,
        "description": "Bulk shipment discount",
        "discountType": "percentage",
        "discountValue": 10.0,
        "savedAmount": 21.05
      }
    ],

    "serviceDetails": {
      "availableUrgencyLevels": ["STANDARD", "EXPRESS"],
      "cutoffTimes": {
        "STANDARD": "20:00",
        "EXPRESS": "18:00"
      },
      "deliveryWindows": {
        "STANDARD": "48-72 hours",
        "EXPRESS": "24-48 hours"
      }
    },

    "calculationDetails": {
      "weightSlab": "2-3 kg",
      "distanceSlab": "1000-1500 km",
      "applicableZones": "North Delhi → Mumbai Central",
      "rateCardVersion": "v2.1.0",
      "calculatedAt": "2025-07-24T12:30:00.000Z"
    }
  },
  "execution_time_ms": 234,
  "from_cache": false,
  "request_id": "charge_calc_1753357999960"
}

Response - Service Not Available:

json

{
  "success": true,
  "data": {
    "available": false,
    "partner": {
      "partnerId": "partner_001",
      "name": "Express Logistics",
      "isActive": true
    },
    "coverage": {
      "pickupCovered": true,
      "deliveryCovered": false,
      "reason": "Delivery location not in partner's service area"
    },
    "alternatives": [
      {
        "suggestion": "Try nearby pincodes: 400002, 400003",
        "action": "Change delivery pincode"
      },
      {
        "suggestion": "Use partner_002 for this route",
        "action": "Switch partner"
      }
    ]
  },
  "execution_time_ms": 145
}

Status Codes:

200 - Calculation completed (check data.available for service availability)
400 - Invalid request parameters
401 - Authentication failed
404 - Partner not found or pincodes invalid
500 - Calculation error

🔍 Common Query Examples & Testing

Authentication Examples

Service-Level Authentication (Main System)

bash

# Generate signature for service authentication
SERVICE_ID="TESTING_1"
TIMESTAMP=$(date +%s)
METHOD="GET"
URL="/api/v1/cities?stateIds=1&limit=5"
SIGNATURE=$(echo -n "${METHOD}${URL}${TIMESTAMP}" | openssl dgst -sha256 -hmac "service_secret_here" -binary | base64)

curl -X GET "http://localhost:3000${URL}" \
  -H "x-service-id: ${SERVICE_ID}" \
  -H "x-timestamp: ${TIMESTAMP}" \
  -H "x-signature: ${SIGNATURE}"

Partner-Level Authentication

bash

# Generate signature for partner authentication
PARTNER_ID="partner_001"
TIMESTAMP=$(date +%s)
METHOD="GET"
URL="/api/v1/partner-packages/${PARTNER_ID}"
SIGNATURE=$(echo -n "${METHOD}${URL}${TIMESTAMP}" | openssl dgst -sha256 -hmac "partner_secret_here" -binary | base64)

curl -X GET "http://localhost:3000${URL}" \
  -H "x-partner-id: ${PARTNER_ID}" \
  -H "x-timestamp: ${TIMESTAMP}" \
  -H "x-signature: ${SIGNATURE}"

Common API Usage Patterns

Zone Creation Workflow

bash

# 1. Get states
GET /api/v1/pincodes/states?includeCount=true

# 2. Get cities for selected states
GET /api/v1/cities?stateIds=1,8&includeState=true

# 3. Get areas for selected cities
GET /api/v1/areas?cityIds=1,115&includeCity=true&includeState=true

# 4. Get pincodes for selected areas (if needed)
GET /api/v1/pincodes/search?city=Mumbai&type=urban

Partner Data Retrieval

bash

# Get comprehensive partner data
GET /api/v1/partners/comprehensive-data?partnerId=partner_001&format=detailed

# Get specific partner components
GET /api/v1/partner-packages/partner_001?includeZoneMapping=true
GET /api/v1/partner-charges/partner_001?chargeType=all
GET /api/v1/partner-discounts/partner_001?validOnly=true

Charge Calculation Flow

bash

# 1. Check partner availability
POST /api/v1/partners/availability/check
Body: {"pickupPincode": "110001", "deliveryPincode": "400001", ...}

# 2. Calculate charges
POST /api/v1/shipments/calculate-charges
Body: {"partnerId": "partner_001", "pickupPincode": "110001", ...}

# 3. Assign shipment
POST /api/v1/shipment-assignment/assign
Body: {"shipmentDetails": {...}, "assignmentPreferences": {...}}

Error Handling Examples

Authentication Errors

json

{
  "success": false,
  "error": {
    "code": "AUTH_ERROR",
    "message": "Authentication failed",
    "details": "Missing required authentication headers"
  },
  "request_id": "req_1753357999960",
  "execution_time_ms": 2
}

Validation Errors

json

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": [
      {
        "field": "partnerId",
        "message": "partnerId is required as query parameter for service-level access",
        "code": "any.required"
      }
    ],
    "field_count": 1
  },
  "request_id": "req_1753357999960",
  "execution_time_ms": 3
}

Business Logic Errors

json

{
  "success": true,
  "data": {
    "success": false,
    "assignment": null,
    "error": {
      "code": "NO_CAPABLE_PARTNERS",
      "message": "No partners found that can handle this shipment",
      "details": ["Route not covered", "Required services unavailable"]
    }
  }
}

📚 Schema Definitions & Types

Common Types

yaml

PincodePattern:
  type: string
  pattern: "^[0-9]{6}$"
  example: "110001"
  comment: "Must be valid 6-digit Indian pincode"

PartnerId:
  type: string
  pattern: "^[a-zA-Z0-9_-]{3,50}$"
  example: "partner_001"
  comment: "Alphanumeric with hyphens/underscores, 3-50 chars"

Timestamp:
  type: string
  format: date-time
  example: "2025-07-24T12:30:00.000Z"
  comment: "ISO 8601 format with timezone"

Currency:
  type: number
  format: float
  minimum: 0
  example: 125.50
  comment: "Amount in Indian Rupees (₹)"

Weight:
  type: number
  minimum: 1
  maximum: 50000
  description: Weight in grams
  example: 2500
  comment: "1g to 50kg range supported"

Enums

yaml

ShipmentType:
  type: string
  enum: ["B2B", "B2C"]
  comment: "B2B=Business to Business, B2C=Business to Consumer"

PaymentType:
  type: string
  enum: ["COD", "PREPAID"]
  comment: "COD=Cash on Delivery, PREPAID=Advance payment"

ServiceCategory:
  type: string
  enum: ["LOGISTICS", "PAYMENT", "LOCATION", "SPECIAL"]
  comment: "Service type categorization"

UrgencyLevel:
  type: string
  enum: ["STANDARD", "EXPRESS", "URGENT"]
  comment: "Delivery urgency classification"

ChargeType:
  type: string
  enum: ["flat", "percentage"]
  comment: "flat=Fixed ₹ amount, percentage=% of value"

DiscountType:
  type: string
  enum: ["flat", "percentage"]
  comment: "flat=Fixed ₹ discount, percentage=% discount"

Quick Start Guide - 15-minute setup
Authentication Guide - HMAC implementation details
Main System Flow - Complete integration workflows
API Examples - More request/response samples

🏷️ Change Log

Latest Updates (July 24, 2025):

✅ FIXED: Cities and Areas API cache key generation - now returns correct filtered results
✅ FIXED: Service-level authentication for comprehensive partner data APIs
✅ FIXED: Partner availability check logic - now supports "find all available partners"
✅ FIXED: Shipment assignment validation - supports hyphens/underscores in shipment IDs
✅ FIXED: Mandatory PICKUP/DELIVERY services requirement
✅ ENHANCED: Added comprehensive query parameter documentation with comments
✅ ENHANCED: Added detailed response examples with actual API outputs
✅ ENHANCED: Added authentication examples and common usage patterns
✅ ENHANCED: Added business logic error examples and handling guides

Performance Improvements:

Cache key generation now properly handles arrays and prevents collisions
Response times: 6-17ms for geographical APIs, 145-567ms for complex calculations
Fixed cache invalidation ensures fresh data when filtering

Breaking Changes: None - All changes are backward compatible

Complete and accurate API documentation for Partner Services microservice. All endpoints tested and verified with real responses. Cache issues fixed, authentication flows corrected, and comprehensive usage examples provided.

🛣️ API Routes Reference - Main System Integration ​

📋 Overview ​

🔐 Authentication Headers ​

Service-Level Authentication (Main System APIs) ​

Partner-Level Authentication (Partner-specific APIs) ​

🏥 System Health & Monitoring ​

GET /health ​

🌍 Geographical Data APIs ​

GET /api/v1/cities ​

GET /api/v1/areas ​

💰 Customer Charge Management APIs ​

GET /api/v1/customer-charges ​

POST /api/v1/customer-charges/bulk ​

🎯 Discount Management APIs ​

GET /api/v1/discounts ​

POST /api/v1/discounts ​

👥 Partner Data Retrieval APIs ​

GET /api/v1/partners/comprehensive-data ​

GET /api/v1/partner-packages/{partnerId} ​

🚀 Partner Availability & Assignment APIs ​

POST /api/v1/partners/availability/check ​

POST /api/v1/shipment-assignment/assign ​

💰 Charge Calculation APIs ​

POST /api/v1/shipments/calculate-charges ​

🔍 Common Query Examples & Testing ​

Authentication Examples ​

Service-Level Authentication (Main System) ​

Partner-Level Authentication ​

Common API Usage Patterns ​

Zone Creation Workflow ​

Partner Data Retrieval ​

Charge Calculation Flow ​

Error Handling Examples ​

Authentication Errors ​

Validation Errors ​

Business Logic Errors ​

📚 Schema Definitions & Types ​

Common Types ​

Enums ​

🔗 Related Documentation ​

🏷️ Change Log ​

🛣️ API Routes Reference - Main System Integration

📋 Overview

🔐 Authentication Headers

Service-Level Authentication (Main System APIs)

Partner-Level Authentication (Partner-specific APIs)

🏥 System Health & Monitoring

GET /health

🌍 Geographical Data APIs

GET /api/v1/cities

GET /api/v1/areas

💰 Customer Charge Management APIs

GET /api/v1/customer-charges

POST /api/v1/customer-charges/bulk

🎯 Discount Management APIs

GET /api/v1/discounts

POST /api/v1/discounts

👥 Partner Data Retrieval APIs

GET /api/v1/partners/comprehensive-data

GET /api/v1/partner-packages/{partnerId}

🚀 Partner Availability & Assignment APIs

POST /api/v1/partners/availability/check

POST /api/v1/shipment-assignment/assign

💰 Charge Calculation APIs

POST /api/v1/shipments/calculate-charges

🔍 Common Query Examples & Testing

Authentication Examples

Service-Level Authentication (Main System)

Partner-Level Authentication

Common API Usage Patterns

Zone Creation Workflow

Partner Data Retrieval

Charge Calculation Flow

Error Handling Examples

Authentication Errors

Validation Errors

Business Logic Errors

📚 Schema Definitions & Types

Common Types

Enums

🔗 Related Documentation

🏷️ Change Log