Dispatch API

The Dispatch API provides endpoints for managing dispatch operations and delivery coordination.

Endpoints Overview

Method	Endpoint	Description
GET	/api/dispatch/overview	Get dispatch overview
POST	/api/dispatch	Create dispatch
GET	/api/dispatch/{id}	Get dispatch
PUT	/api/dispatch	Update dispatch
DELETE	/api/dispatch/{id}	Delete dispatch
POST	/api/dispatch/remove-shipment	Remove shipment from dispatch
GET	/api/dispatch/in-shipment/{id}	Get dispatch by shipment
GET	/api/route/{id}	Get route details
GET	/api/route/timeline/{id}	Get route timeline

Get Dispatch Overview

Get aggregate dispatch statistics.

GET /api/dispatch/overview

Response

{
  "data": {
    "totalDispatches": 25,
    "activeDispatches": 8,
    "completedToday": 12,
    "pendingDeliveries": 45,
    "driversActive": 8,
    "onTimeRate": 0.94
  },
  "success": true
}

Create Dispatch

Create a new dispatch.

POST /api/dispatch

Request Body

{
  "name": "Morning Route A",
  "driverId": "driver-uuid",
  "vehicleId": "vehicle-uuid",
  "plannedDate": "2024-01-16T08:00:00Z",
  "shipmentIds": [
    "shipment-uuid-1",
    "shipment-uuid-2",
    "shipment-uuid-3"
  ],
  "notes": "Priority deliveries first"
}

Response

{
  "data": {
    "guid": "dispatch-uuid",
    "name": "Morning Route A",
    "status": "draft",
    "plannedDate": "2024-01-16T08:00:00Z",
    "shipmentCount": 3
  },
  "success": true
}

Get Dispatch

Retrieve a specific dispatch.

GET /api/dispatch/{id}

Path Parameters

Parameter	Type	Description
id	uuid	Dispatch identifier

Response

{
  "data": {
    "guid": "dispatch-uuid",
    "name": "Morning Route A",
    "status": "in_progress",
    "driver": {
      "guid": "driver-uuid",
      "name": "John Driver"
    },
    "vehicle": {
      "guid": "vehicle-uuid",
      "name": "Van 001"
    },
    "plannedDate": "2024-01-16T08:00:00Z",
    "startedAt": "2024-01-16T08:15:00Z",
    "shipments": [
      {
        "guid": "shipment-uuid-1",
        "trackingNumber": "TRK001",
        "status": "delivered",
        "deliveredAt": "2024-01-16T09:30:00Z"
      },
      {
        "guid": "shipment-uuid-2",
        "trackingNumber": "TRK002",
        "status": "out_for_delivery",
        "estimatedArrival": "2024-01-16T10:15:00Z"
      }
    ],
    "progress": {
      "completed": 1,
      "total": 3,
      "percentage": 33.3
    }
  },
  "success": true
}

Update Dispatch

Update an existing dispatch.

PUT /api/dispatch

Request Body

{
  "guid": "dispatch-uuid",
  "name": "Morning Route A (Updated)",
  "driverId": "driver-uuid",
  "vehicleId": "vehicle-uuid",
  "notes": "Updated notes"
}

Response

{
  "data": {
    "guid": "dispatch-uuid",
    "name": "Morning Route A (Updated)"
  },
  "success": true
}

Delete Dispatch

Remove a dispatch.

DELETE /api/dispatch/{id}

Response

{
  "success": true
}

Remove Shipment from Dispatch

Remove a shipment from a dispatch.

POST /api/dispatch/remove-shipment

Request Body

{
  "dispatchId": "dispatch-uuid",
  "shipmentId": "shipment-uuid"
}

Response

{
  "success": true
}

Get Dispatch by Shipment

Find which dispatch contains a shipment.

GET /api/dispatch/in-shipment/{id}

Path Parameters

Parameter	Type	Description
id	uuid	Shipment identifier

Response

{
  "data": {
    "guid": "dispatch-uuid",
    "name": "Morning Route A",
    "status": "in_progress"
  },
  "success": true
}

Get Route Details

Get route information for a dispatch.

GET /api/route/{id}

Response

{
  "data": {
    "guid": "route-uuid",
    "dispatchId": "dispatch-uuid",
    "stops": [
      {
        "sequence": 1,
        "shipmentId": "shipment-uuid-1",
        "address": "123 First St",
        "estimatedArrival": "2024-01-16T09:00:00Z",
        "status": "completed"
      },
      {
        "sequence": 2,
        "shipmentId": "shipment-uuid-2",
        "address": "456 Second St",
        "estimatedArrival": "2024-01-16T10:00:00Z",
        "status": "pending"
      }
    ],
    "totalDistance": 45.5,
    "estimatedDuration": "2h 30m"
  },
  "success": true
}

Get Route Timeline

Get timeline view of a route.

GET /api/route/timeline/{id}

Response

{
  "data": {
    "routeId": "route-uuid",
    "events": [
      {
        "time": "08:00",
        "type": "departure",
        "location": "Warehouse",
        "status": "completed"
      },
      {
        "time": "09:00",
        "type": "delivery",
        "location": "123 First St",
        "status": "completed"
      },
      {
        "time": "10:00",
        "type": "delivery",
        "location": "456 Second St",
        "status": "in_progress"
      },
      {
        "time": "11:00",
        "type": "delivery",
        "location": "789 Third St",
        "status": "pending"
      },
      {
        "time": "12:00",
        "type": "return",
        "location": "Warehouse",
        "status": "pending"
      }
    ]
  },
  "success": true
}

Dispatch Statuses

Status	Description
draft	Being planned
ready	Ready to start
in_progress	Deliveries underway
completed	All deliveries done
cancelled	Dispatch cancelled

Error Responses

404 Not Found

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Dispatch not found"
  }
}

400 Bad Request

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Cannot remove shipment from active dispatch"
  }
}