Shipments API

The Shipments API provides endpoints for managing shipments, tracking, and delivery operations.

Endpoints Overview

Method	Endpoint	Description
GET	/api/v1/shipments	List shipments
POST	/api/v1/shipments	Create shipment
GET	/api/v1/shipments/{shipmentId}	Get shipment
PUT	/api/v1/shipments/{shipmentId}	Update shipment
DELETE	/api/v1/shipments/{shipmentId}	Delete shipment
PATCH	/api/v1/shipments	Update shipment dates
GET	/api/v1/shipments/overview	Get shipment overview
GET	/api/v1/shipments/unassigned	Get unassigned shipments
POST	/api/v1/shipments/delete	Bulk delete shipments
GET	/api/v1/shipments/{shipmentId}/traces	Get shipment traces

List Shipments

Get a paginated list of shipments.

GET /api/v1/shipments

Query Parameters

Parameter	Type	Description
from	string	Start date filter
to	string	End date filter
customerGuid	uuid	Filter by customer
status	string	Filter by status
page	integer	Page number (default: 1)
perPage	integer	Items per page (default: 50)

Example Request

GET /api/v1/shipments?status=in_transit&page=1&perPage=25

Response

{
  "data": [
    {
      "guid": "shipment-uuid",
      "trackingNumber": "TRK123456789",
      "status": "in_transit",
      "customer": {
        "guid": "customer-uuid",
        "name": "John Doe"
      },
      "sender": {
        "name": "Warehouse A",
        "address": "123 Warehouse Rd"
      },
      "recipient": {
        "name": "John Doe",
        "address": "456 Main St"
      },
      "carrier": {
        "guid": "carrier-uuid",
        "name": "Express Delivery"
      },
      "createdAt": "2024-01-15T10:00:00Z"
    }
  ],
  "page": 1,
  "pageSize": 25,
  "totalCount": 200,
  "success": true
}

Create Shipment

Create a new shipment.

POST /api/v1/shipments

Request Body

{
  "customerId": "customer-uuid",
  "carrierId": "carrier-uuid",
  "sender": {
    "name": "Warehouse A",
    "street": "123 Warehouse Rd",
    "city": "City",
    "state": "State",
    "postalCode": "12345",
    "country": "Country",
    "phone": "+1234567890"
  },
  "recipient": {
    "name": "John Doe",
    "street": "456 Main St",
    "city": "Town",
    "state": "State",
    "postalCode": "67890",
    "country": "Country",
    "phone": "+0987654321"
  },
  "packages": [
    {
      "length": 30,
      "width": 20,
      "height": 15,
      "weight": 2.5
    }
  ],
  "serviceLevel": "standard",
  "instructions": "Leave at door"
}

Response

{
  "success": true
}

Get Shipment

Retrieve a specific shipment.

GET /api/v1/shipments/{shipmentId}

Path Parameters

Parameter	Type	Description
shipmentId	uuid	Shipment identifier

Response

{
  "data": {
    "guid": "shipment-uuid",
    "trackingNumber": "TRK123456789",
    "status": "in_transit",
    "customer": {
      "guid": "customer-uuid",
      "name": "John Doe",
      "email": "[email protected]"
    },
    "sender": {
      "name": "Warehouse A",
      "address": {
        "street": "123 Warehouse Rd",
        "city": "City",
        "state": "State",
        "postalCode": "12345"
      }
    },
    "recipient": {
      "name": "John Doe",
      "address": {
        "street": "456 Main St",
        "city": "Town",
        "state": "State",
        "postalCode": "67890"
      }
    },
    "packages": [
      {
        "length": 30,
        "width": 20,
        "height": 15,
        "weight": 2.5
      }
    ],
    "carrier": {
      "guid": "carrier-uuid",
      "name": "Express Delivery"
    },
    "serviceLevel": "standard",
    "estimatedDelivery": "2024-01-17T12:00:00Z",
    "createdAt": "2024-01-15T10:00:00Z",
    "updatedAt": "2024-01-15T14:30:00Z"
  },
  "success": true
}

Update Shipment

Update an existing shipment.

PUT /api/v1/shipments/{shipmentId}

Request Body

{
  "instructions": "Updated delivery instructions",
  "recipient": {
    "phone": "+1111111111"
  }
}

Response

{
  "data": {
    "guid": "shipment-uuid"
  },
  "success": true
}

Delete Shipment

Remove a shipment.

DELETE /api/v1/shipments/{shipmentId}

Response

{
  "success": true
}

Update Shipment Dates

Update collection or delivery dates.

PATCH /api/v1/shipments

Request Body

{
  "shipmentId": "shipment-uuid",
  "collectionDate": "2024-01-16T10:00:00Z",
  "deliveryDate": "2024-01-17T14:00:00Z"
}

Response

{
  "data": {
    "guid": "shipment-uuid"
  },
  "success": true
}

Get Shipment Overview

Get aggregate shipment statistics.

GET /api/v1/shipments/overview

Response

{
  "data": {
    "totalShipments": 1500,
    "inTransit": 120,
    "delivered": 1350,
    "exceptions": 15,
    "pending": 15,
    "onTimeRate": 0.95
  },
  "success": true
}

Get Unassigned Shipments

Get shipments not assigned to a dispatch.

GET /api/v1/shipments/unassigned

Response

{
  "data": [
    {
      "guid": "shipment-uuid",
      "trackingNumber": "TRK123456789",
      "status": "created",
      "recipient": {
        "name": "John Doe",
        "city": "Town"
      }
    }
  ],
  "success": true
}

Bulk Delete Shipments

Delete multiple shipments.

POST /api/v1/shipments/delete

Request Body

[
  { "guid": "shipment-uuid-1" },
  { "guid": "shipment-uuid-2" }
]

Response

{
  "data": [],
  "success": true
}

Get Shipment Traces

Get tracking activity history.

GET /api/v1/shipments/{shipmentId}/traces

Response

{
  "data": [
    {
      "timestamp": "2024-01-15T10:00:00Z",
      "status": "created",
      "description": "Shipment created",
      "location": null
    },
    {
      "timestamp": "2024-01-15T14:30:00Z",
      "status": "collected",
      "description": "Picked up by carrier",
      "location": "Warehouse A"
    },
    {
      "timestamp": "2024-01-16T08:00:00Z",
      "status": "in_transit",
      "description": "In transit to destination",
      "location": "Distribution Center B"
    }
  ],
  "success": true
}

Shipment Statuses

Status	Description
created	Shipment created
collected	Picked up by carrier
in_transit	Moving through network
out_for_delivery	On delivery vehicle
delivered	Successfully delivered
exception	Issue occurred
returned	Returned to sender
cancelled	Shipment cancelled

Error Responses

404 Not Found

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

400 Bad Request

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid shipment data"
  }
}