Shipment Assignment Guide

This guide covers the process of assigning shipments to partners and managing the delivery workflow.

Assignment Flow

graph TD
    A[Create Shipment] --> B[Validate Details]
    B --> C[Find Partners]
    C --> D[Calculate Charges]
    D --> E[Rank Partners]
    E --> F[Select Partner]
    F --> G[Confirm Assignment]
    G --> H[Track Status]

Creating Shipments

Basic Shipment Creation

const shipment = {
  reference: "SHIP123456",
  type: "B2C",
  priority: "STANDARD",
  pickup: {
    address: "123 Sender Street",
    city: "Mumbai",
    pincode: "400001",
    contact: {
      name: "John Sender",
      phone: "+91-9876543210",
    },
  },
  delivery: {
    address: "456 Receiver Road",
    city: "Delhi",
    pincode: "110001",
    contact: {
      name: "Jane Receiver",
      phone: "+91-9876543211",
    },
  },
  package: {
    weight: 5.5,
    dimensions: {
      length: 30,
      width: 20,
      height: 15,
    },
    items: [
      {
        name: "Laptop",
        quantity: 1,
        value: 50000,
      },
    ],
  },
  payment: {
    type: "COD",
    amount: 50000,
  },
};

const createdShipment = await client.shipments.create(shipment);

Finding Available Partners

Partner Search

const partnerSearch = {
  shipmentId: createdShipment.id,
  criteria: {
    serviceType: "STANDARD",
    maxTransitTime: "72h",
    specialHandling: ["FRAGILE"],
    preferences: {
      preferredPartners: ["partner_123", "partner_456"],
      excludedPartners: ["partner_789"],
    },
  },
};

const availablePartners = await client.shipments.findPartners(partnerSearch);

Charge Calculation

const charges = await client.shipments.calculateCharges({
  shipmentId: createdShipment.id,
  partners: availablePartners.map((p) => p.partnerId),
});

// Sort partners by cost
const sortedPartners = charges.partnerCharges.sort(
  (a, b) => a.totalCharge - b.totalCharge
);

Partner Selection

Automated Selection

const selection = {
  shipmentId: createdShipment.id,
  selectionCriteria: {
    strategy: "OPTIMAL",
    weights: {
      cost: 0.4,
      performance: 0.3,
      reliability: 0.3,
    },
  },
};

const selectedPartner = await client.shipments.selectPartner(selection);

Manual Selection

const manualSelection = {
  shipmentId: createdShipment.id,
  partnerId: "partner_123",
  reason: "CUSTOMER_PREFERENCE",
};

const assignment = await client.shipments.assignPartner(manualSelection);

Assignment Confirmation

Confirming Assignment

const confirmation = await client.shipments.confirmAssignment({
  shipmentId: createdShipment.id,
  assignmentId: assignment.id,
  details: {
    pickupSlot: "2024-02-21T14:00:00Z",
    specialInstructions: "Handle with care",
    documents: ["invoice_123.pdf"],
  },
});

Bulk Assignment

Processing Multiple Shipments

const bulkAssignment = {
  shipments: [
    { id: "SHIP123", partnerId: "partner_123" },
    { id: "SHIP124", partnerId: "partner_456" },
    { id: "SHIP125", partnerId: "partner_123" },
  ],
  options: {
    validateAll: true,
    rollbackOnError: true,
  },
};

const bulkResult = await client.shipments.bulkAssign(bulkAssignment);

Assignment Tracking

Tracking Assignment Status

const status = await client.shipments.getAssignmentStatus(shipmentId);

console.log("Assignment Status:", status.currentStatus);
console.log("Partner:", status.partner);
console.log("Timeline:", status.timeline);

Real-time Updates

client.shipments.subscribeToUpdates(shipmentId, (update) => {
  console.log("Status Update:", update.status);
  console.log("Location:", update.location);
  console.log("Timestamp:", update.timestamp);
});

Error Handling

Assignment Errors

try {
  await client.shipments.assignPartner(assignment);
} catch (error) {
  switch (error.code) {
    case "PARTNER_UNAVAILABLE":
      console.error("Selected partner is not available:", error.details);
      // Find alternative partner
      break;
    case "INVALID_ASSIGNMENT":
      console.error("Invalid assignment details:", error.details);
      // Validate assignment details
      break;
    case "CAPACITY_EXCEEDED":
      console.error("Partner capacity exceeded:", error.details);
      // Try different partner
      break;
    default:
      console.error("Assignment failed:", error);
  }
}

Best Practices

1. Partner Selection

   • Consider multiple factors (cost, performance, reliability)
   • Implement fallback options
   • Monitor partner performance

2. Assignment Strategy

   • Use automated selection for standard shipments
   • Manual selection for special cases
   • Implement proper validation

3. Error Handling

   • Graceful fallback mechanisms
   • Clear error messages
   • Proper logging

4. Performance Optimization

   • Use bulk operations when possible
   • Implement caching for partner data
   • Optimize API calls

Next Steps

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