API Reference

REST API documentation for TL21 Warehouse Management System

Open Swagger UI

Overview

The TL21 Warehouse Management API provides secure RESTful endpoints for managing orders and warehouse operations.

Base URL https://localhost:7001/api

Authentication

ASP.NET Core Identity (Required)

Format

JSON (application/json)

Orders API Endpoints

Complete CRUD operations for managing orders in the warehouse system.

GET /api/orders Get All Orders

Retrieve a paginated list of orders with optional filtering.

Query Parameters

Parameter	Type	Required	Description
`status`	string	No	Filter by order status
`orderType`	string	No	Filter by order type
`pageNumber`	integer	No	Page number (default: 1)
`pageSize`	integer	No	Items per page (default: 10)

Response: 200 OK

[
  {
    "id": 1,
    "publicKey": "550e8400-e29b-41d4-a716-446655440000",
    "orderNumber": "ORD-2024-001",
    "orderType": "Sales",
    "status": "Pending",
    "customerName": "John Doe",
    "totalAmount": 1500.00,
    "createdAt": "2024-01-15T10:30:00Z"
  }
]

GET /api/orders/{id} Get Order by ID

Retrieve a specific order by its ID.

Path Parameters

Parameter	Type	Description
`id`	integer	Order ID

Responses

200 OK - Returns order object

404 Not Found - Order not found

401 Unauthorized - Authentication required

POST /api/orders Create New Order

Create a new order in the system.

Request Body

{
  "orderNumber": "ORD-2024-002",
  "orderType": "Sales",
  "status": "Pending",
  "customerName": "Jane Smith",
  "customerEmail": "jane.smith@example.com",
  "totalAmount": 2500.00,
  "warehouseId": 1,
  "priority": "P1"
}

Responses

201 Created - Order created successfully

400 Bad Request - Invalid data

401 Unauthorized - Authentication required

PUT /api/orders/{id} Update Order

Update an existing order with complete data.

Responses

204 No Content - Update successful

400 Bad Request - Invalid data

404 Not Found - Order not found

PATCH /api/orders/{id} Partial Update Order

Update specific fields of an order.

Request Body Example

{
  "status": "Delivered",
  "notes": "Package delivered successfully"
}

DELETE /api/orders/{id} Delete Order

Delete an order from the system.

Responses

204 No Content - Delete successful

404 Not Found - Order not found

GET /api/orders/statistics Get Order Statistics

Retrieve aggregated statistics about orders.

Response: 200 OK

{
  "totalOrders": 150,
  "pendingOrders": 25,
  "readyForPickup": 30,
  "onTrack": 40,
  "delivered": 50,
  "cancelled": 5,
  "totalRevenue": 125000.00,
  "averageOrderValue": 833.33
}

Shipments API Endpoints

Complete CRUD operations for managing shipments in the warehouse system.

GET /api/shipments Get All Shipments

Retrieve a paginated list of shipments with optional filtering.

Query Parameters

Parameter	Type	Required	Description
`status`	string	No	Filter by shipment status
`carrier`	string	No	Filter by carrier name
`orderId`	integer	No	Filter by order ID
`pageNumber`	integer	No	Page number (default: 1)
`pageSize`	integer	No	Items per page (default: 10)

Response: 200 OK

[
  {
    "id": 1,
    "publicKey": "650e8400-e29b-41d4-a716-446655440000",
    "shipmentNumber": "SHP-2024-001",
    "orderId": 1,
    "carrier": "FedEx",
    "trackingNumber": "1234567890",
    "status": "InTransit",
    "shippingCost": 45.00,
    "weight": 12.5,
    "createdAt": "2024-01-15T10:30:00Z"
  }
]

GET /api/shipments/{id} Get Shipment by ID

Retrieve a specific shipment by its ID.

Responses

200 OK - Returns shipment object

404 Not Found - Shipment not found

401 Unauthorized - Authentication required

GET /api/shipments/by-tracking/{trackingNumber} Get Shipment by Tracking Number

Retrieve a specific shipment by its tracking number.

Path Parameters

Parameter	Type	Description
`trackingNumber`	string	Shipment tracking number

POST /api/shipments Create New Shipment

Create a new shipment in the system.

Request Body

{
  "shipmentNumber": "SHP-2024-002",
  "orderId": 1,
  "carrier": "UPS",
  "trackingNumber": "9876543210",
  "status": "Preparing",
  "shippingCost": 55.00,
  "weight": 15.0,
  "sourceAddress": "123 Warehouse St",
  "destinationAddress": "456 Customer Ave",
  "isInternational": false
}

Responses

201 Created - Shipment created successfully

400 Bad Request - Invalid data

401 Unauthorized - Authentication required

PUT /api/shipments/{id} Update Shipment

Update an existing shipment with complete data.

Responses

204 No Content - Update successful

400 Bad Request - Invalid data

404 Not Found - Shipment not found

PATCH /api/shipments/{id} Partial Update Shipment

Update specific fields of a shipment.

Request Body Example

{
  "status": "Delivered",
  "actualDeliveryDate": "2024-01-20T14:30:00Z",
  "currentLeg": "Delivered"
}

DELETE /api/shipments/{id} Delete Shipment

Delete a shipment from the system.

Responses

204 No Content - Delete successful

404 Not Found - Shipment not found

GET /api/shipments/statistics Get Shipment Statistics

Retrieve aggregated statistics about shipments.

Response: 200 OK

{
  "totalShipments": 200,
  "preparing": 15,
  "shipped": 20,
  "inTransit": 50,
  "delivered": 110,
  "failed": 5,
  "totalShippingCost": 9500.00,
  "averageShippingCost": 47.50,
  "totalWeight": 2500.0,
  "averageWeight": 12.5,
  "internationalShipments": 25
}

Data Models

Order Status Values

Pending Order created but not processed
Ready for Pickup Ready to be picked up from warehouse
On Track Order in transit
Delivered Order delivered
Cancelled Order cancelled

Order Type Values

Sales - Sales order
Transfer - Transfer between warehouses
Return - Return order

Priority Values

P0 - Immediately (highest priority)
P1 - 30 days
P2 - 90 days

Shipment Status Values

Preparing Shipment is being prepared
Shipped Shipment has been dispatched
InTransit Shipment is in transit
Delivered Shipment delivered
Failed Shipment failed

Authentication & Security

All API endpoints require authentication using ASP.NET Core Identity. Users must be logged into the system to access the API.

Security Features

Authentication required for all endpoints
Input validation and model binding
SQL injection protection via Entity Framework
Concurrency control for updates
Comprehensive error logging

Error Handling

The API returns standard HTTP status codes and error messages in JSON format.

Common HTTP Status Codes

Code	Status	Description
200	OK	Request successful
201	Created	Resource created successfully
204	No Content	Request successful, no content to return
400	Bad Request	Invalid request data
401	Unauthorized	Authentication required
404	Not Found	Resource not found
409	Conflict	Concurrency error
500	Internal Server Error	Server error occurred