🔍 API Examples - Complete Request/Response Guide

📋 Overview

This guide provides complete, working examples for all major Partner Services API workflows. Each example includes full request/response details, error handling, and practical implementation tips.

Coverage:

✅ Authentication & Health Checks
✅ Partner Data Retrieval
✅ Zone Management Operations
✅ Shipment Assignment Workflow
✅ Charge Calculation Examples
✅ Error Handling Scenarios

🔐 Authentication Examples

Basic Health Check

Request:

http

GET /health HTTP/1.1
Host: partner-services.logistics.com

Response:

json

{
  "success": true,
  "status": "healthy",
  "timestamp": "2025-07-22T10:30:00.000Z",
  "services": {
    "database": "connected",
    "redis": "connected",
    "api": "operational"
  },
  "performance": {
    "responseTime": "42ms",
    "uptime": "7d 14h 32m 15s"
  },
  "version": "1.0.0"
}

Authenticated API Information

Request:

http

GET /api/v1 HTTP/1.1
Host: partner-services.logistics.com
Content-Type: application/json
x-partner-id: partner_demo_001
x-timestamp: 1642752000
x-signature: a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456

Response:

json

{
  "success": true,
  "message": "Partner Services API v1 - Welcome partner_demo_001",
  "partner": {
    "partnerId": "partner_demo_001",
    "name": "Demo Logistics Partner",
    "status": "ACTIVE",
    "apiAccess": "FULL"
  },
  "endpoints": {
    "health": "/health",
    "zones": "/api/v1/zones",
    "packages": "/api/v1/packages",
    "services": "/api/v1/service-types",
    "charges": "/api/v1/customer-charges",
    "discounts": "/api/v1/discounts",
    "shipments": "/api/v1/shipments",
    "partners": "/api/v1/partners",
    "pincodes": "/api/v1/pincodes",
    "comprehensive": "/api/v1/partners/comprehensive-data"
  },
  "rateLimit": {
    "tier": "TIER_1",
    "requestsPerMinute": 1000,
    "remaining": 999
  }
}

👥 Partner Data Retrieval Examples

Comprehensive Partner Data

Request:

http

GET /api/v1/partners/comprehensive-data?format=standard&includeStatistics=true HTTP/1.1
Host: partner-services.logistics.com
Content-Type: application/json
x-partner-id: partner_demo_001
x-timestamp: 1642752060
x-signature: b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456

Response:

json

{
  "success": true,
  "data": {
    "partner": {
      "partnerId": "partner_demo_001",
      "name": "Demo Logistics Partner",
      "status": "ACTIVE",
      "joinedDate": "2024-01-15T00:00:00.000Z",
      "lastUpdated": "2025-07-22T08:15:30.000Z",
      "contact": {
        "email": "api@demologistics.com",
        "phone": "+91-11-12345678"
      },
      "configuration": {
        "completeness": 95,
        "lastReview": "2025-07-20T10:00:00.000Z"
      }
    },
    "zones": {
      "total": 15,
      "active": 13,
      "data": [
        {
          "id": "ZN001",
          "name": "Delhi NCR Zone",
          "status": true,
          "coverage": {
            "states": 2,
            "cities": 8,
            "areas": 45,
            "pincodes": 225
          },
          "services": {
            "pickup": true,
            "delivery": true,
            "cod": true,
            "prepaid": true
          },
          "performance": {
            "averageDeliveryTime": "24-48 hours",
            "successRate": 98.5
          }
        }
      ],
      "coverage": {
        "totalStates": 12,
        "totalCities": 156,
        "totalPincodes": 12500,
        "serviceability": "85% of India"
      }
    },
    "packages": {
      "packageCharges": {
        "total": 8,
        "active": 7,
        "types": ["DOCUMENT", "PARCEL", "FRAGILE", "BULK"]
      },
      "weightCharges": {
        "total": 15,
        "active": 12,
        "ranges": [
          {
            "range": "0-500g",
            "baseCharge": 40.0,
            "perKgCharge": 0
          },
          {
            "range": "500g-10kg",
            "baseCharge": 50.0,
            "perKgCharge": 15.0
          }
        ]
      }
    },
    "services": {
      "serviceTypes": {
        "total": 6,
        "active": 5,
        "available": [
          {
            "id": "SV001",
            "name": "Standard Delivery",
            "status": "ACTIVE",
            "deliveryTime": "24-48 hours",
            "coverage": "95%"
          },
          {
            "id": "SV002",
            "name": "Express Delivery",
            "status": "ACTIVE",
            "deliveryTime": "12-24 hours",
            "coverage": "80%"
          }
        ]
      },
      "availability": {
        "pickup": true,
        "delivery": true,
        "cod": true,
        "prepaid": true,
        "insurance": true,
        "tracking": true
      },
      "specialServices": ["WHITE_GLOVE", "INSTALLATION", "FRAGILE_HANDLING"]
    },
    "charges": {
      "customerCharges": {
        "total": 25,
        "active": 22,
        "categories": [
          "WEIGHT_BASED",
          "DISTANCE_BASED",
          "VALUE_BASED",
          "SPECIAL_HANDLING"
        ]
      },
      "distanceCharges": {
        "total": 10,
        "active": 8,
        "zones": [
          {
            "zone": "LOCAL",
            "range": "0-25 km",
            "charge": 25.0
          },
          {
            "zone": "REGIONAL",
            "range": "25-500 km",
            "charge": 50.0
          }
        ]
      },
      "surcharges": [
        {
          "type": "FSC",
          "name": "Fuel Surcharge",
          "rate": "15%",
          "status": "ACTIVE"
        },
        {
          "type": "COD",
          "name": "Cash on Delivery",
          "rate": "2% or min ₹25",
          "status": "ACTIVE"
        }
      ]
    },
    "discounts": {
      "discounts": {
        "total": 12,
        "active": 10,
        "categories": ["WEIGHT_BASED", "VALUE_BASED", "VOLUME_BASED", "LOYALTY"]
      },
      "totalSavings": 1256800.5,
      "topDiscounts": [
        {
          "id": "DS001",
          "name": "Bulk Shipment Discount",
          "type": "WEIGHT_BASED",
          "value": "10% off",
          "applied": 1205,
          "savings": 456780.25
        }
      ]
    },
    "performance": {
      "lastMonth": {
        "shipments": 12500,
        "revenue": "₹25,68,500",
        "averageOrderValue": "₹205.48",
        "successRate": "98.2%"
      },
      "metrics": {
        "averageResponseTime": "145ms",
        "apiSuccessRate": "99.8%",
        "uptime": "99.95%",
        "customerSatisfaction": 4.7
      }
    },
    "compliance": {
      "certifications": ["ISO 9001", "ISO 27001"],
      "insurance": "₹50 Lakh coverage",
      "licenses": ["GST", "PAN", "FSSAI"],
      "auditScore": 94
    }
  },
  "metadata": {
    "generatedAt": "2025-07-22T10:30:00.000Z",
    "validUntil": "2025-07-22T11:30:00.000Z",
    "dataFreshness": "real-time",
    "cacheStatus": "MISS"
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193

Partner Zones Specific

Request:

http

GET /api/v1/partner-zones/partner_demo_001?includeGeography=true&includeServices=true HTTP/1.1
Host: partner-services.logistics.com
Content-Type: application/json
x-partner-id: partner_demo_001
x-timestamp: 1642752120
x-signature: c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456

Response:

json

{
  "success": true,
  "data": {
    "partnerId": "partner_demo_001",
    "zones": [
      {
        "id": "ZN001",
        "name": "Delhi NCR Zone",
        "description": "Delhi National Capital Region coverage",
        "status": true,
        "geography": {
          "states": [
            {
              "id": "ST001",
              "name": "Delhi",
              "cities": [
                {
                  "id": "CT001",
                  "name": "New Delhi",
                  "areas": [
                    {
                      "id": "AR001",
                      "name": "Connaught Place",
                      "pincodes": ["110001", "110002"]
                    }
                  ]
                }
              ]
            }
          ]
        },
        "services": [
          {
            "serviceTypeId": "SV001",
            "serviceTypeName": "Standard Delivery",
            "isAvailable": true,
            "baseCharge": 50.0,
            "customCharges": {
              "expressDelivery": 25.0,
              "whiteGlove": 100.0
            },
            "configuration": {
              "cutoffTime": "18:00",
              "deliveryWindow": "24-48 hours",
              "maxWeight": 50000,
              "restrictions": []
            }
          }
        ],
        "coverage": {
          "totalPincodes": 225,
          "serviceablePincodes": 220,
          "coveragePercentage": 97.8
        },
        "performance": {
          "averageDeliveryTime": 36.5,
          "onTimeDelivery": 96.2,
          "successRate": 98.5,
          "customerRating": 4.6
        },
        "createdAt": "2024-02-15T10:00:00.000Z",
        "updatedAt": "2025-07-20T15:30:00.000Z"
      }
    ],
    "summary": {
      "totalZones": 15,
      "activeZones": 13,
      "totalCoverage": {
        "states": 12,
        "cities": 156,
        "areas": 1245,
        "pincodes": 12500
      },
      "serviceMetrics": {
        "averageDeliveryTime": "32.4 hours",
        "overallSuccessRate": "98.2%",
        "customerSatisfaction": 4.7
      }
    }
  }
}

🗺️ Zone Management Examples

Create Zone with Complete Configuration

Request:

http

POST /api/v1/zones HTTP/1.1
Host: partner-services.logistics.com
Content-Type: application/json
x-partner-id: partner_demo_001
x-timestamp: 1642752180
x-signature: d4e5f6789012345678901234567890abcdef1234567890abcdef123456

{
  "name": "Mumbai West Zone",
  "description": "Western Mumbai business and residential areas",
  "status": true,
  "geographical": {
    "states": ["ST002"],
    "cities": ["CT015", "CT016"],
    "areas": ["AR101", "AR102", "AR103"],
    "pincodes": ["400001", "400002", "400003", "400004", "400005"]
  },
  "services": [
    {
      "serviceTypeId": "SV001",
      "isAvailable": true,
      "baseCharge": 60.0,
      "customCharges": {
        "expressDelivery": 30.0,
        "sameDay": 100.0,
        "whiteGlove": 150.0
      },
      "additionalInfo": {
        "cutoffTime": "17:00",
        "deliveryWindow": "24-48 hours",
        "maxWeight": 50000,
        "restrictions": ["hazardous"],
        "specialInstructions": "Call before delivery"
      }
    },
    {
      "serviceTypeId": "SV002",
      "isAvailable": true,
      "baseCharge": 80.0,
      "customCharges": {
        "priority": 50.0
      },
      "additionalInfo": {
        "cutoffTime": "15:00",
        "deliveryWindow": "12-24 hours",
        "maxWeight": 25000
      }
    }
  ],
  "operationalDetails": {
    "operatingHours": {
      "monday": "09:00-18:00",
      "tuesday": "09:00-18:00",
      "wednesday": "09:00-18:00",
      "thursday": "09:00-18:00",
      "friday": "09:00-18:00",
      "saturday": "09:00-14:00",
      "sunday": "CLOSED"
    },
    "capacity": {
      "maxDailyShipments": 500,
      "maxWeightPerDay": 25000000
    },
    "specialHandling": ["FRAGILE", "ELECTRONICS", "DOCUMENTS"]
  }
}

Response:

json

{
  "success": true,
  "message": "Zone created successfully with complete configuration",
  "data": {
    "id": "ZN046",
    "name": "Mumbai West Zone",
    "status": true,
    "createdAt": "2025-07-22T10:35:00.000Z",
    "updatedAt": "2025-07-22T10:35:00.000Z",
    "assignmentResults": {
      "geographical": {
        "states": { "assigned": 1, "failed": 0 },
        "cities": { "assigned": 2, "failed": 0 },
        "areas": { "assigned": 3, "failed": 0 },
        "pincodes": { "assigned": 5, "failed": 0 }
      },
      "services": {
        "total": 2,
        "assigned": 2,
        "failed": 0,
        "details": [
          {
            "serviceTypeId": "SV001",
            "status": "ASSIGNED",
            "configuration": "COMPLETE"
          },
          {
            "serviceTypeId": "SV002",
            "status": "ASSIGNED",
            "configuration": "COMPLETE"
          }
        ]
      }
    },
    "coverage": {
      "estimatedPincodes": 5,
      "estimatedPopulation": 2500000,
      "coverageArea": "125 sq km"
    },
    "validation": {
      "geographicalConsistency": "PASSED",
      "serviceCompatibility": "PASSED",
      "chargeValidation": "PASSED",
      "operationalFeasibility": "PASSED"
    },
    "nextSteps": [
      "Zone is now active and accepting shipments",
      "Monitor performance metrics for first 30 days",
      "Consider expanding coverage based on demand"
    ]
  }
}

Bulk Zone Assignment

Request:

http

POST /api/v1/zones/ZN046/assign/pincodes HTTP/1.1
Host: partner-services.logistics.com
Content-Type: application/json
x-partner-id: partner_demo_001
x-timestamp: 1642752240
x-signature: e5f6789012345678901234567890abcdef1234567890abcdef123456

{
  "pincodes": [
    "400006", "400007", "400008", "400009", "400010",
    "400011", "400012", "400013", "400014", "400015",
    "400016", "400017", "400018", "400019", "400020"
  ],
  "options": {
    "validateGeography": true,
    "skipDuplicates": true,
    "autoCreateMissing": false,
    "notifyOnCompletion": true
  },
  "bulkOperation": {
    "batchSize": 50,
    "maxRetries": 3,
    "continueOnError": true
  }
}

Response:

json

{
  "success": true,
  "message": "Bulk pincode assignment completed",
  "data": {
    "zoneId": "ZN046",
    "zoneName": "Mumbai West Zone",
    "operation": {
      "operationId": "BLK_20250722_001",
      "startedAt": "2025-07-22T10:36:00.000Z",
      "completedAt": "2025-07-22T10:36:15.000Z",
      "duration": "15.2 seconds"
    },
    "results": {
      "total": 15,
      "successful": 13,
      "failed": 2,
      "skipped": 0,
      "breakdown": {
        "assigned": 13,
        "alreadyExists": 0,
        "invalid": 2,
        "geographyMismatch": 0
      }
    },
    "successful": [
      {
        "pincode": "400006",
        "status": "ASSIGNED",
        "area": "Bandra West",
        "city": "Mumbai",
        "state": "Maharashtra"
      },
      {
        "pincode": "400007",
        "status": "ASSIGNED",
        "area": "Bandra East",
        "city": "Mumbai",
        "state": "Maharashtra"
      }
    ],
    "failed": [
      {
        "pincode": "400099",
        "status": "FAILED",
        "reason": "INVALID_PINCODE",
        "details": "Pincode does not exist in database"
      },
      {
        "pincode": "400098",
        "status": "FAILED",
        "reason": "GEOGRAPHY_MISMATCH",
        "details": "Pincode belongs to different geographical region"
      }
    ],
    "updatedCoverage": {
      "totalPincodes": 18,
      "newPincodes": 13,
      "coverageIncrease": "38.5%",
      "estimatedPopulationIncrease": 650000
    }
  }
}

📦 Shipment Assignment Examples

Partner Availability Check

Request:

http

POST /api/v1/partners/availability/check HTTP/1.1
Host: partner-services.logistics.com
Content-Type: application/json
x-partner-id: partner_demo_001
x-timestamp: 1642752300
x-signature: f6789012345678901234567890abcdef1234567890abcdef123456

{
  "pickupPincode": "110001",
  "deliveryPincode": "400001",
  "weight": 2500,
  "dimensions": {
    "length": 30,
    "width": 25,
    "height": 15
  },
  "shipmentType": "B2C",
  "paymentType": "COD",
  "declaredValue": 3500,
  "serviceRequirements": ["PICKUP", "DELIVERY", "COD", "TRACKING"],
  "urgency": "STANDARD",
  "specialInstructions": "Handle with care - electronics",
  "preferredDeliveryDate": "2025-07-25",
  "deliveryTimeSlot": "10:00-14:00"
}

Response:

json

{
  "success": true,
  "data": {
    "isAvailable": true,
    "confidence": 95,
    "partnerId": "partner_demo_001",
    "availability": {
      "overall": "AVAILABLE",
      "reasons": [
        "Partner has coverage for both pincodes",
        "All required services are available",
        "Adequate capacity for requested date",
        "Weight within acceptable limits"
      ]
    },
    "coverage": {
      "pickup": {
        "available": true,
        "zone": "ZN001",
        "zoneName": "Delhi NCR Zone",
        "confidence": 98,
        "estimatedPickupTime": "2025-07-23T10:00:00.000Z",
        "cutoffTime": "2025-07-22T18:00:00.000Z",
        "serviceWindow": "09:00-18:00"
      },
      "delivery": {
        "available": true,
        "zone": "ZN046",
        "zoneName": "Mumbai West Zone",
        "confidence": 92,
        "estimatedDeliveryTime": "2025-07-25T12:00:00.000Z",
        "deliveryWindow": "10:00-14:00",
        "alternativeSlots": ["14:00-18:00", "2025-07-26T10:00-14:00"]
      }
    },
    "services": {
      "matched": ["PICKUP", "DELIVERY", "COD", "TRACKING"],
      "available": [
        "PICKUP",
        "DELIVERY",
        "COD",
        "PREPAID",
        "TRACKING",
        "INSURANCE",
        "SMS_UPDATES",
        "EMAIL_UPDATES"
      ],
      "unavailable": [],
      "additionalOptions": [
        {
          "service": "EXPRESS_DELIVERY",
          "available": true,
          "additionalCost": 50.0,
          "timeSaving": "12-24 hours"
        },
        {
          "service": "WHITE_GLOVE",
          "available": true,
          "additionalCost": 150.0,
          "description": "Specialized electronics handling"
        }
      ]
    },
    "capacity": {
      "currentLoad": "72%",
      "canAccept": true,
      "availableSlots": {
        "pickup": ["2025-07-23T10:00", "2025-07-23T14:00"],
        "delivery": ["2025-07-25T10:00", "2025-07-25T14:00"]
      },
      "limitations": []
    },
    "transit": {
      "estimatedTransitTime": "48-72 hours",
      "route": "Delhi → Mumbai",
      "distance": 1437.5,
      "transportMode": "SURFACE",
      "waypoints": ["Gurgaon Hub", "Jaipur Hub", "Mumbai Hub"]
    },
    "constraints": [],
    "recommendations": [
      "Consider express delivery for faster transit",
      "Add insurance for high-value electronics",
      "Confirm recipient availability for COD collection"
    ],
    "pricing": {
      "estimatedCharges": {
        "baseCharge": 75.0,
        "weightCharge": 52.5,
        "distanceCharge": 50.0,
        "codCharge": 70.0,
        "estimatedTotal": 247.5
      },
      "note": "Final charges will be calculated during shipment creation"
    }
  }
}

Comprehensive Charge Calculation

Request:

http

POST /api/v1/shipments/calculate-charges HTTP/1.1
Host: partner-services.logistics.com
Content-Type: application/json
x-partner-id: partner_demo_001
x-timestamp: 1642752360
x-signature: 6789012345678901234567890abcdef1234567890abcdef123456

{
  "partnerId": "partner_demo_001",
  "pickupPincode": "110001",
  "deliveryPincode": "400001",
  "weight": 2500,
  "dimensions": {
    "length": 30,
    "width": 25,
    "height": 15
  },
  "shipmentType": "B2C",
  "paymentType": "COD",
  "declaredValue": 3500,
  "packageType": "ELECTRONICS",
  "serviceRequirements": ["PICKUP", "DELIVERY", "COD", "TRACKING", "INSURANCE"],
  "additionalServices": ["EXPRESS_DELIVERY", "FRAGILE_HANDLING"],
  "volumetricWeight": 2812.5,
  "actualWeight": 2500,
  "preferredDeliveryDate": "2025-07-25",
  "customerDetails": {
    "customerType": "PREMIUM",
    "loyaltyTier": "GOLD",
    "monthlyVolume": 150
  }
}

Response:

json

{
  "success": true,
  "data": {
    "available": true,
    "calculationId": "CALC_20250722_001",
    "partnerId": "partner_demo_001",
    "shipmentDetails": {
      "chargeableWeight": 2812.5,
      "weightType": "VOLUMETRIC",
      "packageCategory": "ELECTRONICS",
      "serviceLevel": "EXPRESS",
      "route": {
        "origin": "Delhi NCR Zone",
        "destination": "Mumbai West Zone",
        "distance": 1437.5,
        "transitTime": "24-36 hours"
      }
    },
    "charges": {
      "subtotal": 186.25,
      "baseCharge": 75.0,
      "weightCharge": 67.5,
      "distanceCharge": 50.0,
      "serviceCharges": {
        "expressDelivery": 50.0,
        "fragileHandling": 25.0,
        "tracking": 0.0,
        "insurance": 35.0
      },
      "surcharges": {
        "fscCharge": 18.63,
        "codCharge": 70.0,
        "fuelSurcharge": 15.75,
        "handlingCharge": 12.5
      },
      "discounts": {
        "loyaltyDiscount": -25.0,
        "volumeDiscount": -15.0,
        "premiumCustomerDiscount": -10.0,
        "totalDiscountAmount": -50.0
      },
      "taxes": {
        "gstRate": 18,
        "gstAmount": 36.95,
        "cgst": 18.48,
        "sgst": 18.47
      },
      "totalAmount": 273.08,
      "roundedAmount": 275.0
    },
    "breakdown": [
      {
        "component": "Base Charge",
        "description": "Minimum charge for B2C shipments",
        "calculation": "Fixed rate",
        "amount": 75.0,
        "category": "BASE"
      },
      {
        "component": "Weight Charge",
        "description": "Charge based on volumetric weight",
        "calculation": "2.8125 kg × ₹24/kg",
        "amount": 67.5,
        "category": "WEIGHT"
      },
      {
        "component": "Distance Charge",
        "description": "Long distance delivery charge",
        "calculation": "1437.5 km - Tier 3 zone",
        "amount": 50.0,
        "category": "DISTANCE"
      },
      {
        "component": "Express Delivery",
        "description": "24-36 hour delivery service",
        "calculation": "Express service premium",
        "amount": 50.0,
        "category": "SERVICE"
      },
      {
        "component": "COD Charge",
        "description": "Cash on delivery processing",
        "calculation": "₹3500 × 2% (min ₹25)",
        "amount": 70.0,
        "category": "SURCHARGE"
      },
      {
        "component": "Insurance",
        "description": "Declared value coverage",
        "calculation": "₹3500 × 1% (min ₹35)",
        "amount": 35.0,
        "category": "SERVICE"
      },
      {
        "component": "Loyalty Discount",
        "description": "Gold tier customer discount",
        "calculation": "10% on base charges",
        "amount": -25.0,
        "category": "DISCOUNT"
      },
      {
        "component": "GST",
        "description": "Goods and Services Tax",
        "calculation": "₹205.25 × 18%",
        "amount": 36.95,
        "category": "TAX"
      }
    ],
    "alternatives": [
      {
        "serviceLevel": "STANDARD",
        "transitTime": "48-72 hours",
        "totalAmount": 225.0,
        "savings": 50.0,
        "description": "Standard delivery option"
      },
      {
        "serviceLevel": "PREMIUM",
        "transitTime": "12-24 hours",
        "totalAmount": 350.0,
        "additional": 75.0,
        "description": "Same-day delivery available"
      }
    ],
    "metadata": {
      "calculatedAt": "2025-07-22T10:39:00.000Z",
      "validUntil": "2025-07-22T18:39:00.000Z",
      "calculationVersion": "2.1.5",
      "appliedRules": [
        "VOLUMETRIC_WEIGHT_RULE",
        "EXPRESS_DELIVERY_SURCHARGE",
        "LOYALTY_DISCOUNT_GOLD",
        "COD_PERCENTAGE_RULE",
        "ELECTRONICS_INSURANCE_MANDATORY"
      ],
      "zone": {
        "pickup": "ZN001",
        "delivery": "ZN046"
      },
      "performance": {
        "calculationTime": "45ms",
        "rulesProcessed": 23,
        "discountsEvaluated": 8
      }
    },
    "warnings": [],
    "recommendations": [
      "Consider removing express delivery to save ₹50",
      "Fragile handling is recommended for electronics",
      "Insurance is mandatory for high-value items"
    ]
  }
}

Shipment Assignment

Request:

http

POST /api/v1/shipment-assignment/assign HTTP/1.1
Host: partner-services.logistics.com
Content-Type: application/json
x-partner-id: partner_demo_001
x-timestamp: 1642752420
x-signature: 789012345678901234567890abcdef1234567890abcdef123456

{
  "shipmentDetails": {
    "shipmentId": "SHP_20250722_001",
    "pickupPincode": "110001",
    "deliveryPincode": "400001",
    "weight": 2500,
    "dimensions": {
      "length": 30,
      "width": 25,
      "height": 15
    },
    "shipmentType": "B2C",
    "paymentType": "COD",
    "declaredValue": 3500,
    "packageType": "ELECTRONICS",
    "assignedPartnerId": "partner_demo_001",
    "serviceRequirements": ["PICKUP", "DELIVERY", "COD", "TRACKING", "INSURANCE"],
    "additionalServices": ["EXPRESS_DELIVERY", "FRAGILE_HANDLING"],
    "specialInstructions": "Handle with care - electronics item",
    "preferredDeliveryDate": "2025-07-25",
    "deliveryTimeSlot": "10:00-14:00"
  },
  "customerDetails": {
    "sender": {
      "name": "TechStore Delhi",
      "phone": "+91-98765-43210",
      "email": "orders@techstore.com",
      "address": {
        "line1": "123 Connaught Place",
        "line2": "Near Metro Station",
        "city": "New Delhi",
        "state": "Delhi",
        "pincode": "110001"
      }
    },
    "recipient": {
      "name": "Rahul Kumar",
      "phone": "+91-87654-32109",
      "email": "rahul.kumar@email.com",
      "address": {
        "line1": "456 Bandra West",
        "line2": "Near Linking Road",
        "city": "Mumbai",
        "state": "Maharashtra",
        "pincode": "400001"
      }
    }
  },
  "assignmentPreferences": {
    "assignmentStrategy": "MANUAL_SELECTION",
    "selectedPartner": "partner_demo_001",
    "priority": "COST_OPTIMIZED",
    "allowAlternatives": false
  },
  "options": {
    "includeChargeEstimate": true,
    "includeTransitTime": true,
    "createTrackingNumber": true,
    "sendNotifications": true,
    "createAssignmentRecord": true,
    "autoConfirmAssignment": true
  }
}

Response:

json

{
  "success": true,
  "message": "Shipment assigned successfully to partner",
  "data": {
    "assignment": {
      "assignmentId": "ASG_20250722_001",
      "shipmentId": "SHP_20250722_001",
      "partnerId": "partner_demo_001",
      "partnerName": "Demo Logistics Partner",
      "status": "ASSIGNED",
      "assignedAt": "2025-07-22T10:42:00.000Z",
      "confirmedAt": "2025-07-22T10:42:05.000Z",
      "assignmentType": "MANUAL_SELECTION",
      "priority": "COST_OPTIMIZED"
    },
    "timeline": {
      "estimatedPickup": "2025-07-23T10:00:00.000Z",
      "estimatedDelivery": "2025-07-25T12:00:00.000Z",
      "transitTime": "50 hours",
      "deliveryWindow": "10:00-14:00",
      "milestones": [
        {
          "event": "PICKUP_SCHEDULED",
          "estimatedTime": "2025-07-23T10:00:00.000Z",
          "description": "Pickup from TechStore Delhi"
        },
        {
          "event": "IN_TRANSIT",
          "estimatedTime": "2025-07-23T18:00:00.000Z",
          "description": "Shipment in transit to Mumbai"
        },
        {
          "event": "OUT_FOR_DELIVERY",
          "estimatedTime": "2025-07-25T09:00:00.000Z",
          "description": "Out for delivery in Mumbai"
        },
        {
          "event": "DELIVERED",
          "estimatedTime": "2025-07-25T12:00:00.000Z",
          "description": "Delivered to recipient"
        }
      ]
    },
    "charges": {
      "totalAmount": 275.0,
      "calculationId": "CALC_20250722_001",
      "breakdown": {
        "baseCharges": 192.5,
        "serviceCharges": 110.0,
        "surcharges": 116.88,
        "discounts": -50.0,
        "taxes": 36.95
      },
      "paymentTerms": {
        "method": "COD",
        "collectionAmount": 3500.0,
        "remittanceAmount": 3225.0,
        "partnerCommission": 275.0
      }
    },
    "tracking": {
      "trackingNumber": "TRK987654321",
      "trackingUrl": "https://track.demologistics.com/TRK987654321",
      "internalTrackingId": "INT_20250722_001",
      "qrCode": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
      "notificationPreferences": {
        "sms": true,
        "email": true,
        "whatsapp": false
      }
    },
    "operationalDetails": {
      "pickupHub": "Delhi NCR Hub",
      "deliveryHub": "Mumbai West Hub",
      "route": "DEL → GGN → JAI → MUM",
      "vehicleType": "MINI_TRUCK",
      "handlingInstructions": [
        "FRAGILE_HANDLING",
        "ELECTRONICS_CARE",
        "COD_COLLECTION_REQUIRED"
      ]
    },
    "compliance": {
      "documentsRequired": [
        "Invoice copy",
        "Delivery receipt",
        "COD collection receipt"
      ],
      "insuranceCoverage": {
        "amount": 3500.0,
        "policyNumber": "INS_20250722_001",
        "validUntil": "2025-08-22T23:59:59.000Z"
      }
    },
    "notifications": {
      "sent": [
        {
          "type": "ASSIGNMENT_CONFIRMATION",
          "recipient": "TechStore Delhi",
          "method": "EMAIL",
          "status": "SENT",
          "sentAt": "2025-07-22T10:42:10.000Z"
        },
        {
          "type": "PICKUP_SCHEDULED",
          "recipient": "TechStore Delhi",
          "method": "SMS",
          "status": "SENT",
          "sentAt": "2025-07-22T10:42:12.000Z"
        }
      ],
      "pending": [
        {
          "type": "DELIVERY_NOTIFICATION",
          "recipient": "Rahul Kumar",
          "method": "SMS",
          "scheduledFor": "2025-07-25T09:00:00.000Z"
        }
      ]
    },
    "nextSteps": [
      "Partner will receive assignment notification within 5 minutes",
      "Pickup will be scheduled for tomorrow 10:00 AM",
      "Customer will receive tracking details via SMS and email",
      "COD amount will be collected upon delivery",
      "Delivery confirmation will be sent to all parties"
    ],
    "supportContact": {
      "partnerSupport": "+91-80-12345678",
      "customerCare": "+91-80-87654321",
      "emailSupport": "support@demologistics.com",
      "trackingSupport": "track@demologistics.com"
    }
  }
}

❌ Error Response Examples

Authentication Failure

Request:

http

GET /api/v1/zones HTTP/1.1
Host: partner-services.logistics.com
Content-Type: application/json
x-partner-id: invalid_partner
x-timestamp: 1642752480
x-signature: invalid_signature_123456

Response:

json

{
  "success": false,
  "error": {
    "code": "AUTHENTICATION_FAILED",
    "message": "Invalid HMAC signature or partner credentials",
    "details": {
      "reason": "SIGNATURE_MISMATCH",
      "partnerId": "invalid_partner",
      "timestamp": 1642752480,
      "expectedSignature": "Expected valid HMAC-SHA256 signature",
      "providedSignature": "invalid_signature_123456"
    },
    "timestamp": "2025-07-22T10:48:00.000Z",
    "requestId": "req_20250722_error_001",
    "documentation": "https://docs.partner-services.com/authentication",
    "supportContact": "support@partner-services.com"
  },
  "statusCode": 401
}

Rate Limit Exceeded

Response:

json

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Request rate limit exceeded for your tier",
    "details": {
      "tier": "TIER_1",
      "limit": 1000,
      "window": "60 seconds",
      "resetTime": "2025-07-22T10:49:00.000Z",
      "retryAfter": 15
    },
    "timestamp": "2025-07-22T10:48:30.000Z",
    "requestId": "req_20250722_error_002"
  },
  "statusCode": 429,
  "headers": {
    "X-RateLimit-Limit": "1000",
    "X-RateLimit-Remaining": "0",
    "X-RateLimit-Reset": "1642752540",
    "Retry-After": "15"
  }
}

Validation Error

Request:

http

POST /api/v1/shipments/calculate-charges HTTP/1.1
Host: partner-services.logistics.com
Content-Type: application/json
x-partner-id: partner_demo_001
x-timestamp: 1642752540
x-signature: valid_signature_123456

{
  "pickupPincode": "invalid",
  "deliveryPincode": "400001",
  "weight": -100,
  "shipmentType": "INVALID_TYPE"
}

Response:

json

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": {
      "validationErrors": [
        {
          "field": "pickupPincode",
          "value": "invalid",
          "issue": "Must be a valid 6-digit pincode",
          "expectedFormat": "NNNNNN (6 digits)"
        },
        {
          "field": "weight",
          "value": -100,
          "issue": "Weight must be greater than 0",
          "constraints": {
            "min": 1,
            "max": 50000,
            "unit": "grams"
          }
        },
        {
          "field": "shipmentType",
          "value": "INVALID_TYPE",
          "issue": "Invalid shipment type",
          "allowedValues": ["B2B", "B2C", "C2C"]
        }
      ],
      "errorCount": 3,
      "validFields": ["deliveryPincode"]
    },
    "timestamp": "2025-07-22T10:49:00.000Z",
    "requestId": "req_20250722_error_003"
  },
  "statusCode": 400
}

Service Unavailable

Response:

json

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_COVERAGE",
    "message": "Partner does not have coverage for requested route",
    "details": {
      "partnerId": "partner_demo_001",
      "pickupPincode": "110001",
      "deliveryPincode": "999999",
      "coverage": {
        "pickup": {
          "available": true,
          "zone": "ZN001"
        },
        "delivery": {
          "available": false,
          "reason": "PINCODE_NOT_SERVICEABLE",
          "suggestedAlternatives": ["999998", "999997"]
        }
      },
      "recommendations": [
        "Check alternative delivery pincodes nearby",
        "Consider using different partner for this route",
        "Contact support for coverage expansion requests"
      ]
    },
    "timestamp": "2025-07-22T10:49:30.000Z",
    "requestId": "req_20250722_error_004"
  },
  "statusCode": 422
}

🧪 Testing & Debugging Examples

Debug Information Request

Request:

http

GET /api/v1/debug/partner-info?includeConfig=true&includeMetrics=true HTTP/1.1
Host: partner-services.logistics.com
Content-Type: application/json
x-partner-id: partner_demo_001
x-timestamp: 1642752600
x-signature: debug_signature_123456

Response:

json

{
  "success": true,
  "debug": true,
  "data": {
    "partner": {
      "partnerId": "partner_demo_001",
      "status": "ACTIVE",
      "tier": "PREMIUM",
      "apiAccess": "FULL",
      "lastActivity": "2025-07-22T10:49:45.000Z"
    },
    "configuration": {
      "rateLimits": {
        "tier": "TIER_1",
        "requestsPerMinute": 1000,
        "burstLimit": 50
      },
      "features": [
        "COMPREHENSIVE_DATA_ACCESS",
        "BULK_OPERATIONS",
        "PREMIUM_SUPPORT",
        "ADVANCED_ANALYTICS"
      ],
      "integrations": [
        "MAIN_SYSTEM_API",
        "WEBHOOK_NOTIFICATIONS",
        "REAL_TIME_TRACKING"
      ]
    },
    "metrics": {
      "last24Hours": {
        "totalRequests": 2547,
        "successfulRequests": 2523,
        "failedRequests": 24,
        "successRate": "99.06%",
        "averageResponseTime": "145ms"
      },
      "popularEndpoints": [
        {
          "endpoint": "/shipments/calculate-charges",
          "requests": 1205,
          "percentage": "47.3%"
        },
        {
          "endpoint": "/partners/availability/check",
          "requests": 867,
          "percentage": "34.0%"
        }
      ]
    },
    "systemStatus": {
      "services": {
        "api": "OPERATIONAL",
        "database": "OPERATIONAL",
        "cache": "OPERATIONAL",
        "notifications": "OPERATIONAL"
      },
      "performance": {
        "cpuUsage": "23%",
        "memoryUsage": "45%",
        "diskUsage": "67%"
      }
    }
  }
}

🎯 Complete Integration Example

End-to-End Workflow

javascript

// Complete integration workflow example
async function completeIntegrationExample() {
  const auth = new PartnerServicesAuth(config);

  try {
    console.log("🚀 Starting complete integration example...");

    // Step 1: Health check
    console.log("1️⃣ Checking system health...");
    const health = await auth.makeRequest("GET", "/health");
    console.log("✅ System healthy:", health.status);

    // Step 2: Get partner data
    console.log("2️⃣ Fetching partner data...");
    const partnerData = await auth.makeRequest(
      "GET",
      "/partners/comprehensive-data?format=standard"
    );
    console.log(
      `✅ Partner data loaded: ${partnerData.data.zones.total} zones`
    );

    // Step 3: Check availability
    console.log("3️⃣ Checking shipment availability...");
    const availability = await auth.makeRequest(
      "POST",
      "/partners/availability/check",
      {
        pickupPincode: "110001",
        deliveryPincode: "400001",
        weight: 2500,
        shipmentType: "B2C",
        paymentType: "COD",
      }
    );
    console.log(
      `✅ Availability: ${availability.data.isAvailable} (${availability.data.confidence}%)`
    );

    // Step 4: Calculate charges
    console.log("4️⃣ Calculating charges...");
    const charges = await auth.makeRequest(
      "POST",
      "/shipments/calculate-charges",
      {
        partnerId: config.partnerId,
        pickupPincode: "110001",
        deliveryPincode: "400001",
        weight: 2500,
        shipmentType: "B2C",
        paymentType: "COD",
        declaredValue: 3500,
      }
    );
    console.log(`✅ Charges calculated: ₹${charges.data.charges.totalAmount}`);

    // Step 5: Create assignment
    console.log("5️⃣ Creating shipment assignment...");
    const assignment = await auth.makeRequest(
      "POST",
      "/shipment-assignment/assign",
      {
        shipmentDetails: {
          shipmentId: "TEST_" + Date.now(),
          pickupPincode: "110001",
          deliveryPincode: "400001",
          weight: 2500,
          shipmentType: "B2C",
          paymentType: "COD",
          declaredValue: 3500,
          assignedPartnerId: config.partnerId,
        },
        assignmentPreferences: {
          assignmentStrategy: "MANUAL_SELECTION",
          selectedPartner: config.partnerId,
        },
        options: {
          includeChargeEstimate: true,
          includeTransitTime: true,
          createTrackingNumber: true,
        },
      }
    );
    console.log(
      `✅ Assignment created: ${assignment.data.assignment.assignmentId}`
    );
    console.log(`📦 Tracking: ${assignment.data.tracking.trackingNumber}`);

    console.log("🎉 Complete integration example finished successfully!");

    return {
      health,
      partnerData,
      availability,
      charges,
      assignment,
    };
  } catch (error) {
    console.error("❌ Integration example failed:", error.message);
    throw error;
  }
}

// Run the complete example
completeIntegrationExample()
  .then((results) => {
    console.log("✅ All systems operational and integrated!");
  })
  .catch((error) => {
    console.error("❌ Integration failed:", error);
  });

Authentication Guide - HMAC implementation details
Main System Flow - Complete workflow integration
API Reference - Full endpoint documentation
Error Handling - Error management strategies

These examples provide complete, production-ready code for integrating with Partner Services APIs! 🔍

🔍 API Examples - Complete Request/Response Guide ​

📋 Overview ​

🔐 Authentication Examples ​

Basic Health Check ​

Authenticated API Information ​

👥 Partner Data Retrieval Examples ​

Comprehensive Partner Data ​

Partner Zones Specific ​

🗺️ Zone Management Examples ​

Create Zone with Complete Configuration ​

Bulk Zone Assignment ​

📦 Shipment Assignment Examples ​

Partner Availability Check ​

Comprehensive Charge Calculation ​

Shipment Assignment ​

❌ Error Response Examples ​

Authentication Failure ​

Rate Limit Exceeded ​

Validation Error ​

Service Unavailable ​

🧪 Testing & Debugging Examples ​

Debug Information Request ​

🎯 Complete Integration Example ​

End-to-End Workflow ​

📚 Related Documentation ​

🔍 API Examples - Complete Request/Response Guide

📋 Overview

🔐 Authentication Examples

Basic Health Check

Authenticated API Information

👥 Partner Data Retrieval Examples

Comprehensive Partner Data

Partner Zones Specific

🗺️ Zone Management Examples

Create Zone with Complete Configuration

Bulk Zone Assignment

📦 Shipment Assignment Examples

Partner Availability Check

Comprehensive Charge Calculation

Shipment Assignment

❌ Error Response Examples

Authentication Failure

Rate Limit Exceeded

Validation Error

Service Unavailable

🧪 Testing & Debugging Examples

Debug Information Request

🎯 Complete Integration Example

End-to-End Workflow

📚 Related Documentation