🛣️ API Routes Reference - Partner Services 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: https://your-api-domain.com
Authentication: HMAC SHA-256 (see Authentication Guide)
Current Status: 100% Implemented | 51 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 Management

Method	Route	Description	Status	Priority
`GET`	`/api/v1/pincodes/states`	Get all states with pincode counts	✅ Active	🔴 Critical
`GET`	`/api/v1/cities`	Get cities with comprehensive filtering	✅ Active	🔴 Critical
`GET`	`/api/v1/areas`	Get areas with comprehensive filtering	✅ Active	🔴 Critical
`GET`	`/api/v1/pincodes/search`	Advanced pincode search with filters	✅ Active	🔴 Critical
`GET`	`/api/v1/pincodes/{pincode}`	Get specific pincode details	✅ Active	🔴 Critical
`GET`	`/api/v1/pincodes/{pincode}/hierarchy`	Get geographical hierarchy for pincode	✅ Active	🟡 Medium

🗺️ Zone Management

Method	Route	Description	Status	Priority
`GET`	`/api/v1/zones`	Get all zones (main system)	✅ Active	🔴 Critical
`POST`	`/api/v1/zones`	Create new zone	✅ Active	🔴 Critical
`PUT`	`/api/v1/zones/{id}`	Update existing zone	✅ Active	🟡 Medium
`DELETE`	`/api/v1/zones/{id}`	Delete zone	✅ Active	🟡 Medium

⚙️ Service Type Management

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	🟡 Medium
`PUT`	`/api/v1/service-types/{type}`	Update existing service	✅ Active	🟡 Medium
`DELETE`	`/api/v1/service-types/{type}`	Delete service type	✅ Active	🟡 Medium

📦 Package Management

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 config	✅ Active	🔴 Critical
`POST`	`/api/v1/packages/charges/bulk`	Create multiple package charges	✅ Active	🟡 Medium
`PUT`	`/api/v1/packages/charges/{id}`	Update package charge config	✅ Active	🟡 Medium
`DELETE`	`/api/v1/packages/charges/{id}`	Delete package charge config	✅ Active	🟡 Medium
`PUT`	`/api/v1/packages/weight-charges/{id}`	Update package weight charge config	✅ Active	🟡 Medium
`DELETE`	`/api/v1/packages/weight-charges/{id}`	Delete package weight charge config	✅ Active	🟡 Medium

💰 Customer Charge Management

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 config	✅ Active	🔴 Critical
`POST`	`/api/v1/customer-charges/bulk`	Create multiple customer charges	✅ Active	🟡 Medium
`PUT`	`/api/v1/customer-charges/{id}`	Update customer charge config	✅ Active	🟡 Medium
`DELETE`	`/api/v1/customer-charges/{id}`	Delete customer charge config	✅ Active	🟡 Medium

🎯 Discount Management

Method	Route	Description	Status	Priority
`GET`	`/api/v1/discounts`	Get discount configurations	✅ Active	🔴 Critical
`POST`	`/api/v1/discounts`	Create new discount config	✅ Active	🔴 Critical
`POST`	`/api/v1/discounts/bulk`	Create multiple discounts	✅ Active	🟡 Medium
`PUT`	`/api/v1/discounts/{id}`	Update existing discount	✅ Active	🟡 Medium
`DELETE`	`/api/v1/discounts/{id}`	Delete discount	✅ Active	🟡 Medium

👥 Partner Data Retrieval

Method	Route	Description	Status	Priority
`GET`	`/api/v1/partner-packages/{id}`	Get packages for specific partner	✅ Active	🔴 Critical
`GET`	`/api/v1/partner-charges/{id}`	Get charges for specific partner	✅ Active	🔴 Critical
`GET`	`/api/v1/partner-discounts/{id}`	Get discounts for specific partner	✅ Active	🔴 Critical
`GET`	`/api/v1/partner-services/{id}`	Get services for specific partner	✅ Active	🔴 Critical
`GET`	`/api/v1/partners/bulk-data`	Bulk partner data retrieval	✅ Active	🔴 Critical

🧮 Charge Calculation

Method	Route	Description	Status	Priority
`POST`	`/api/v1/surcharge-calculation/{id}/calculate`	Comprehensive charge calculation	✅ Active	🔴 Critical
`POST`	`/api/v1/shipments/calculate-charges`	Shipment charge calculation (service)	✅ Active	🔴 Critical
`POST`	`/api/v1/partners/availability/batch-charges`	Batch availability with charge estimates	✅ Active	🔴 Critical

🔧 Partner Data Management

Method	Route	Description	Status	Priority
`GET`	`/api/v1/partner-zones/{id}`	Get partner zones	✅ Active	🔴 Critical
`GET`	`/api/v1/partners/comprehensive-data/{id}`	Get complete partner data	✅ Active	🔴 Critical

📍 Partner Availability & Assignment

Method	Route	Description	Status	Priority
`POST`	`/api/v1/partners/availability/check`	Check partner availability	✅ Active	🔴 Critical
`POST`	`/api/v1/partners/availability/batch-with-charges`	Batch partner availability with charge calculation	✅ Active	🔴 Critical
`POST`	`/api/v1/shipment-assignment/assign`	Assign shipment to partner with tracking	✅ Active	🔴 Critical
`POST`	`/api/v1/shipment-assignment/rank-partners`	Rank and compare partners for optimal selection	✅ Active	🔴 Critical
`POST`	`/api/v1/shipment-assignment/bulk-assign`	Bulk shipment assignment processing	✅ Active	🔴 Critical

📊 Summary Statistics

Category	Total APIs	Active	Critical	Medium
System Health & Information	3	3	2	1
Geographical Data	6	6	5	1
Zone Management	4	4	2	2
Service Type Management	4	4	1	3
Package Management	7	7	2	5
Customer Charge Management	5	5	2	3
Discount Management	5	5	2	3
Partner Data Retrieval	5	5	5	0
Charge Calculation	3	3	3	0
Partner Data Management	2	2	2	0
Partner Availability	4	4	4	0
TOTAL	51	51	34	17

🚀 Authentication & Rate Limits

Authentication Types:

Service-Level: For main system operations (29 APIs)
Partner-Level: For partner-specific data (16 APIs)
Public: No authentication required (3 APIs)

Rate Limits:

Service-Level: 1000 requests/minute
Partner-Level: 100 requests/minute
Public: 60 requests/minute

Error Response Codes:

200/201 - Success
400 - Bad Request
401 - Authentication Failed
403 - Forbidden/Not Authorized
404 - Resource Not Found
429 - Rate Limit Exceeded
500 - Internal Server Error

📋 Quick Testing Examples

Health Check

bash

curl -X GET "https://your-api-domain.com/health"

States Data (Service Auth)

bash

curl -X GET "https://your-api-domain.com/api/v1/pincodes/states?search=Maharashtra&limit=10" \
  -H "x-service-id: MAIN_SYSTEM" \
  -H "x-timestamp: $(date +%s)" \
  -H "x-signature: your_service_signature"

Charge Calculation (Service Auth)

bash

curl -X POST "https://your-api-domain.com/api/v1/shipments/calculate-charges" \
  -H "Content-Type: application/json" \
  -H "x-service-id: MAIN_SYSTEM" \
  -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)

bash

curl -X POST "https://your-api-domain.com/api/v1/partners/availability/check" \
  -H "Content-Type: application/json" \
  -H "x-service-id: MAIN_SYSTEM" \
  -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)

bash

curl -X POST "https://your-api-domain.com/api/v1/shipment-assignment/assign" \
  -H "Content-Type: application/json" \
  -H "x-service-id: MAIN_SYSTEM" \
  -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", "COD"]
    },
    "assignmentPreferences": {
      "assignmentStrategy": "BEST_MATCH"
    }
  }'

⚡ Key Integration Points

For Main System Integration:

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

For Partner Integration:

Zone Data - Use /partner-zones/{partnerId} for coverage information
Charges - Use /partner-charges/{partnerId} for all charge configurations
Services - Use /partner-services/{partnerId} for available services
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:

🔧 Cache System
- Cities and Areas APIs now return correct filtered results
- Cache key generation for array parameters
- Improved performance: 6-17ms response times
🔐 Authentication
- Service-level auth now works for partner comprehensive data
- Partner packages endpoint accepts service authentication
- Better error messages for missing authentication
⚙️ Business Logic
- Partner availability check supports "find all available partners"
- Shipment assignment accepts hyphens/underscores in IDs
- PICKUP and DELIVERY services are now mandatory
🚀 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

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

Complete API Reference - Detailed endpoint documentation with examples
Authentication Guide - HMAC implementation
Error Handling - Error codes and handling
Quick Start Guide - Getting started tutorial

Last Updated: January 25, 2025
API Version: v1.0.0
Status: Production Ready - 54+ APIs Operational

🛣️ API Routes Reference - Partner Services Integration ​

📋 Overview ​

🏥 System Health & Information ​

🌍 Geographical Data Management ​

🗺️ Zone Management ​

⚙️ Service Type Management ​

📦 Package Management ​

💰 Customer Charge Management ​

🎯 Discount Management ​

👥 Partner Data Retrieval ​

🧮 Charge Calculation ​

🔧 Partner Data Management ​

📍 Partner Availability & Assignment ​

📊 Summary Statistics ​

🚀 Authentication & Rate Limits ​

Authentication Types: ​

Rate Limits: ​

Error Response Codes: ​

📋 Quick Testing Examples ​

Health Check ​

States Data (Service Auth) ​

Charge Calculation (Service Auth) ​

Partner Availability Check (Service Auth) ​

Shipment Assignment (Service Auth) ​

⚡ Key Integration Points ​

For Main System Integration: ​

For Partner Integration: ​

🔐 Authentication Summary ​

Service-Level (x-service-id) ​

Partner-Level (x-partner-id) ​

Public (No Auth) ​

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

Critical Fixes Applied: ​

Performance Improvements: ​

Breaking Changes: ​

🔗 Related Documentation ​

🎯 Integration Checklist ​

Before Integration: ​

Core Integration Steps: ​

Post-Integration Testing: ​

🔗 Related Documentation ​

🛣️ API Routes Reference - Partner Services Integration

📋 Overview

🏥 System Health & Information

🌍 Geographical Data Management

🗺️ Zone Management

⚙️ Service Type Management

📦 Package Management

💰 Customer Charge Management

🎯 Discount Management

👥 Partner Data Retrieval

🧮 Charge Calculation

🔧 Partner Data Management

📍 Partner Availability & Assignment

📊 Summary Statistics

🚀 Authentication & Rate Limits

Authentication Types:

Rate Limits:

Error Response Codes:

📋 Quick Testing Examples

Health Check

States Data (Service Auth)

Charge Calculation (Service Auth)

Partner Availability Check (Service Auth)

Shipment Assignment (Service Auth)

⚡ Key Integration Points

For Main System Integration:

For Partner Integration:

🔐 Authentication Summary

Service-Level (x-service-id)

Partner-Level (x-partner-id)

Public (No Auth)

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

Critical Fixes Applied:

Performance Improvements:

Breaking Changes:

🔗 Related Documentation

🎯 Integration Checklist

Before Integration:

Core Integration Steps:

Post-Integration Testing:

🔗 Related Documentation