🛣️ API Routes Reference - Main System Integration

📋 Overview

Complete reference of all Partner Services API routes that the main system needs to use. This guide provides a quick-scan format for developers to understand what APIs are available and their current implementation status.

Base URL: http://localhost:3000/api/v1
Authentication: HMAC SHA-256 (see Authentication Guide)
Current Status: 100% Implemented | All Critical APIs Operational

---

🏥 System Health & Information

Method	Route	Description	Status	Priority
GET	/health	Enhanced system health check with components	✅ Active	🔴 Critical
GET	/health/ready	Kubernetes readiness probe	✅ Active	🔴 Critical
GET	/health/live	Kubernetes liveness probe	✅ Active	🔴 Critical
GET	/api/v1	API version information	✅ Active	🟡 Medium

---

🌍 Geographical Data APIs

Public Access (No Authentication)

Method	Route	Description	Status	Priority
GET	/api/v1/pincodes/states	Get states with pincode counts & search	✅ Active	🟡 Medium

Service-Level Authentication Required

Method	Route	Description	Status	Priority
GET	/api/v1/cities	Cities with comprehensive filtering	✅ Active	🔴 Critical
GET	/api/v1/areas	Areas with city/state filtering	✅ Active	🔴 Critical
GET	/api/v1/pincodes/search	Advanced pincode search with filters	✅ Active	🔴 Critical
GET	/api/v1/pincodes/:pincode	Specific pincode details with hierarchy	✅ Active	🔴 Critical
GET	/api/v1/pincodes/:pincode/hierarchy	Complete geographical hierarchy for pincode	✅ Active	🟡 Medium

Cache Fixes Applied:

• ✅ Cache key generation for array parameters
• ✅ Proper filtering now returns correct results
• ✅ Response times: 6-17ms for geographical queries
• ✅ Cache invalidation properly handles state/city filters

---

🗺️ Zone Management APIs

Service-Level Authentication Required

Method	Route	Description	Status	Priority
GET	/api/v1/zones	Get all zones (main system access)	✅ Active	🔴 Critical
POST	/api/v1/zones	Create new zone	✅ Active	🔴 Critical

---

🔧 Service Type Management

Service-Level Authentication Required

Method	Route	Description	Status	Priority
GET	/api/v1/service-types	Get all service types	✅ Active	🔴 Critical
POST	/api/v1/service-types	Create new service type	✅ Active	🔴 Critical

---

📦 Package Management APIs

Service-Level Authentication Required

Method	Route	Description	Status	Priority
GET	/api/v1/packages/charges	Get package charges with filtering	✅ Active	🔴 Critical
POST	/api/v1/packages/charges	Create new package charge	✅ Active	🔴 Critical
POST	/api/v1/packages/charges/bulk	Create multiple package charges	✅ Active	🟡 Medium

---

💰 Customer Charge Management APIs

Service-Level Authentication Required

Method	Route	Description	Status	Priority
GET	/api/v1/customer-charges	Get customer charge configurations	✅ Active	🔴 Critical
POST	/api/v1/customer-charges	Create new customer charge	✅ Active	🔴 Critical
POST	/api/v1/customer-charges/bulk	Create multiple customer charges	✅ Active	🟡 Medium

Enhancements:

• ✅ Added partner-specific charge filtering
• ✅ Enhanced charge type categorization (FSC, COD, Insurance)
• ✅ Improved response with summary statistics

---

🎯 Discount Management APIs

Service-Level Authentication Required

Method	Route	Description	Status	Priority
GET	/api/v1/discounts	Get discount configurations with filtering	✅ Active	🔴 Critical
POST	/api/v1/discounts	Create new discount configuration	✅ Active	🔴 Critical
PUT	/api/v1/discounts/:id	Update existing discount	✅ Active	🟡 Medium
DELETE	/api/v1/discounts/:id	Delete discount	✅ Active	🟡 Medium
POST	/api/v1/discounts/bulk	Create multiple discounts	✅ Active	🟡 Medium

Fixes Applied:

• ✅ Partner-specific discount filtering
• ✅ Added weight range validation to prevent overlaps
• ✅ Enhanced validity period checking
• ✅ Added comprehensive discount analytics

---

👥 Partner Data Retrieval APIs

Service-Level Authentication Required

Method	Route	Description	Status	Priority
GET	/api/v1/partners/comprehensive-data	Get complete partner data	✅ Active	🔴 Critical
GET	/api/v1/partner-packages/:partnerId	Get packages for partner	✅ Active	🔴 Critical

Partner-Level Authentication Required

Method	Route	Description	Status	Priority
GET	/api/v1/partner-charges/:partnerId	Get charges for specific partner	✅ Active	🔴 Critical
GET	/api/v1/partner-discounts/:partnerId	Get discounts for specific partner	✅ Active	🔴 Critical
GET	/api/v1/partner-services/:partnerId	Get services for specific partner	✅ Active	🔴 Critical
GET	/api/v1/partner-zones/:partnerId	Get partner zones	✅ Active	🔴 Critical

---

💰 Charge Calculation APIs

Partner-Level Authentication Required

Method	Route	Description	Status	Priority
POST	/api/v1/surcharge-calculation/:partnerId/calculate	Comprehensive charge calculation	✅ Active	🔴 Critical

Service-Level Authentication Required

Method	Route	Description	Status	Priority
POST	/api/v1/shipments/calculate-charges	Shipment charge calculation	✅ Active	🔴 Critical

---

🚀 Partner Availability & Assignment APIs

Service-Level Authentication Required

Method	Route	Description	Status	Priority
POST	/api/v1/partners/availability/check	Check partner availability	✅ Active	🔴 Critical
POST	/api/v1/shipment-assignment/assign	Assign shipment to partner	✅ Active	🔴 Critical

---

📋 Quick Testing Examples

Health Check

curl -X GET "http://localhost:3000/health"

States Data (Public)

curl -X GET "http://localhost:3000/api/v1/pincodes/states?search=Maharashtra&limit=10"

Cities Search (Service Auth)

curl -X GET "http://localhost:3000/api/v1/cities?stateIds=1,2&includeState=true&limit=20" \
  -H "x-service-id: TESTING_1" \
  -H "x-timestamp: $(date +%s)" \
  -H "x-signature: your_service_signature"

Partner Data (Service Auth)

curl -X GET "http://localhost:3000/api/v1/partners/comprehensive-data?partnerId=partner_001" \
  -H "x-service-id: TESTING_1" \
  -H "x-timestamp: $(date +%s)" \
  -H "x-signature: your_service_signature"

Charge Calculation (Service Auth)

curl -X POST "http://localhost:3000/api/v1/shipments/calculate-charges" \
  -H "Content-Type: application/json" \
  -H "x-service-id: TESTING_1" \
  -H "x-timestamp: $(date +%s)" \
  -H "x-signature: your_service_signature" \
  -d '{
    "partnerId": "partner_001",
    "pickupPincode": "110001",
    "deliveryPincode": "400001",
    "weight": 2500,
    "shipmentType": "B2C",
    "paymentType": "COD",
    "declaredValue": 3500
  }'

Partner Availability Check (Service Auth)

curl -X POST "http://localhost:3000/api/v1/partners/availability/check" \
  -H "Content-Type: application/json" \
  -H "x-service-id: TESTING_1" \
  -H "x-timestamp: $(date +%s)" \
  -H "x-signature: your_service_signature" \
  -d '{
    "pickupPincode": "110001",
    "deliveryPincode": "400001",
    "weight": 2500,
    "shipmentType": "B2C",
    "paymentType": "COD",
    "serviceRequirements": ["PICKUP", "DELIVERY", "COD"]
  }'

Shipment Assignment (Service Auth)

curl -X POST "http://localhost:3000/api/v1/shipment-assignment/assign" \
  -H "Content-Type: application/json" \
  -H "x-service-id: TESTING_1" \
  -H "x-timestamp: $(date +%s)" \
  -H "x-signature: your_service_signature" \
  -d '{
    "shipmentDetails": {
      "shipmentId": "SH_1721123456789",
      "fromPincode": "110001",
      "toPincode": "400001",
      "weight": 2500,
      "shipmentType": "B2C",
      "paymentType": "COD",
      "serviceTypes": ["PICKUP", "DELIVERY", "EXPRESS", "COD"]
    },
    "assignmentPreferences": {
      "assignmentStrategy": "BEST_MATCH"
    }
  }'

---

⚡ Key Integration Points

For Main System Integration:

1. Geographical APIs - Use /cities, /areas, /pincodes/search for location services
2. Partner Data - Use /partners/comprehensive-data for complete partner information
3. Availability Check - Use /partners/availability/check before assignment
4. Charge Calculation - Use service-level /shipments/calculate-charges for estimates
5. Assignment - Use /shipment-assignment/assign for final partner assignment

For Partner Integration:

1. Zone Data - Use /partner-zones/:partnerId for coverage information
2. Charges - Use /partner-charges/:partnerId for all charge configurations
3. Services - Use /partner-services/:partnerId for available services
4. Calculation - Use /surcharge-calculation/:partnerId/calculate for precise pricing

---

🔐 Authentication Summary

Service-Level (x-service-id)

• All main system APIs
• Zone management
• Service types
• Partner comprehensive data ✅ Active
• Availability checks
• Shipment assignments
• Charge calculations ✅ Active

Partner-Level (x-partner-id)

• Partner-specific data retrieval
• Partner charge calculations
• Partner zone access

Public (No Auth)

• Basic health checks
• State listings

---

🏷️ Recent Fixes & Enhancements (July 24, 2025)

Critical Fixes Applied:

1. 🔧 Cache System

   • Cities and Areas APIs now return correct filtered results
   • Cache key generation for array parameters
   • Improved performance: 6-17ms response times

2. 🔐 Authentication

   • Service-level auth now works for partner comprehensive data
   • Partner packages endpoint accepts service authentication
   • Better error messages for missing authentication

3. ⚙️ Business Logic

   • Partner availability check supports "find all available partners"
   • Shipment assignment accepts hyphens/underscores in IDs
   • PICKUP and DELIVERY services are now mandatory

4. 🚀 Middleware

   • Charge calculation middleware order corrected
   • Authentication now works properly for all endpoints

Performance Improvements:

• Response Times: 6-17ms for geographical APIs, 145-567ms for complex calculations
• Cache Efficiency: Proper key generation prevents cache collisions
• Error Handling: Enhanced with specific error codes and suggestions

Breaking Changes:

None - All changes are backward compatible

---

🔗 Related Documentation

• Complete API Reference - Full endpoint specifications with examples
• Quick Start Guide - 15-minute setup
• Authentication Guide - HMAC implementation
• Main System Flow - Complete workflows

---

🎯 Integration Checklist

Before Integration:

• [ ] Review authentication setup (HMAC SHA-256)
• [ ] Test health endpoints for connectivity
• [ ] Verify service credentials and signatures

Core Integration Steps:

• [ ] Implement geographical data fetching (cities/areas with cache support)
• [ ] Setup partner data retrieval (comprehensive-data API)
• [ ] Integrate availability checking (with "find all available" support)
• [ ] Implement charge calculation (with proper authentication)
• [ ] Setup shipment assignment

Post-Integration Testing:

• [ ] Test cache performance on geographical APIs
• [ ] Verify all authentication flows work correctly
• [ ] Test error handling for edge cases
• [ ] Validate assignment flow with different service requirements

---

Quick reference for Partner Services API routes. For detailed specifications, see Complete API Reference. All critical fixes applied - July 24, 2025