Zone Management Guide

This guide covers the complete process of managing delivery zones and geographical coverage in the logistics system.

Zone Management Flow

graph TD
    A[Zone Management] --> B[Create Zone]
    B --> C[Configure Coverage]
    C --> D[Set Service Types]
    D --> E[Define Charges]
    E --> F[Set Restrictions]
    F --> G[Activate Zone]

    H[Monitoring] --> I[Update Coverage]
    I --> J[Adjust Services]
    J --> K[Modify Charges]

Creating Zones

Basic Zone Creation

const zoneData = {
  name: "Metropolitan Zone",
  code: "METRO_001",
  description: "Major metropolitan areas with express delivery",
  type: "URBAN",
  status: "ACTIVE",
};

const zone = await client.zones.create(zoneData);

Geographical Coverage

const coverage = {
  zoneId: zone.id,
  geography: {
    states: ["Maharashtra", "Gujarat"],
    cities: ["Mumbai", "Pune", "Ahmedabad"],
    excludedAreas: ["Industrial Zone"],
    pincodes: {
      ranges: [
        { start: "400001", end: "400099" },
        { start: "380001", end: "380015" },
      ],
      excluded: ["400012", "400013"], // Restricted areas
    },
  },
};

await client.zones.setCoverage(coverage);

Service Configuration

Adding Services to Zone

const zoneServices = {
  zoneId: zone.id,
  services: [
    {
      type: "EXPRESS",
      sla: {
        deliveryTime: "24h",
        pickupTime: "2h",
      },
      restrictions: {
        maxWeight: 20,
        maxVolume: 100,
        codLimit: 50000,
      },
    },
    {
      type: "STANDARD",
      sla: {
        deliveryTime: "72h",
        pickupTime: "24h",
      },
      restrictions: {
        maxWeight: 50,
        maxVolume: 200,
        codLimit: 100000,
      },
    },
  ],
};

await client.zones.configureServices(zoneServices);

Charge Configuration

Setting Zone-specific Charges

const zoneCharges = {
  zoneId: zone.id,
  charges: {
    base: {
      EXPRESS: 100,
      STANDARD: 50,
    },
    weightSlabs: [
      { upTo: 5, EXPRESS: 50, STANDARD: 30 },
      { upTo: 10, EXPRESS: 100, STANDARD: 60 },
      { upTo: 20, EXPRESS: 200, STANDARD: 120 },
    ],
    surcharges: {
      remoteArea: "20%",
      festive: "10%",
      fuel: "5%",
    },
  },
};

await client.zones.setCharges(zoneCharges);

Zone Restrictions

Setting Operational Restrictions

const restrictions = {
  zoneId: zone.id,
  operational: {
    timing: {
      weekdays: "09:00-18:00",
      weekends: "10:00-16:00",
      holidays: "CLOSED",
    },
    blackoutDates: ["2024-12-25", "2024-12-31"],
    volumeLimit: {
      daily: 1000,
      perPickup: 50,
    },
  },
  shipment: {
    dimensions: {
      maxLength: 100,
      maxWidth: 50,
      maxHeight: 50,
      maxWeight: 20,
    },
    restrictions: ["NO_DANGEROUS_GOODS", "NO_PERISHABLES"],
  },
};

await client.zones.setRestrictions(restrictions);

Zone Monitoring

Fetching Zone Performance

const performance = await client.zones.getPerformance(zoneId, {
  timeframe: "LAST_30_DAYS",
  metrics: [
    "DELIVERY_SUCCESS_RATE",
    "AVERAGE_DELIVERY_TIME",
    "VOLUME_UTILIZATION",
  ],
});

Real-time Zone Status

const status = await client.zones.getStatus(zoneId);

if (status.isOperational) {
  console.log("Zone is operational");
  console.log("Current utilization:", status.utilization);
  console.log("Active shipments:", status.activeShipments);
} else {
  console.log("Zone is non-operational");
  console.log("Reason:", status.reason);
}

Zone Updates

Updating Zone Coverage

const coverageUpdate = {
  zoneId: zone.id,
  addPincodes: ["400100", "400101"],
  removePincodes: ["400012"],
  addCities: ["Thane"],
  removeCities: [],
};

await client.zones.updateCoverage(coverageUpdate);

Updating Service Configuration

const serviceUpdate = {
  zoneId: zone.id,
  serviceType: "EXPRESS",
  updates: {
    sla: { deliveryTime: "12h" },
    restrictions: { maxWeight: 25 },
  },
};

await client.zones.updateService(serviceUpdate);

Best Practices

1. Zone Planning

   • Plan zones based on operational capacity
   • Consider geographical proximity
   • Account for future expansion

2. Service Configuration

   • Set realistic SLAs
   • Configure appropriate restrictions
   • Regular performance monitoring

3. Charge Management

   • Regular market rate analysis
   • Zone-specific cost factors
   • Seasonal adjustments

4. Monitoring and Optimization

   • Regular performance review
   • Proactive capacity planning
   • Dynamic restriction updates

Error Handling

try {
  await client.zones.update(zoneUpdate);
} catch (error) {
  switch (error.code) {
    case "ZONE_NOT_FOUND":
      console.error("Zone does not exist:", error.details);
      break;
    case "INVALID_COVERAGE":
      console.error("Invalid coverage update:", error.details);
      break;
    case "SERVICE_CONFLICT":
      console.error("Service configuration conflict:", error.details);
      break;
    default:
      console.error("Zone update failed:", error);
  }
}

Next Steps

1. Set up Partner Configuration
2. Configure Shipment Assignment
3. View API Reference