Warehouses API

Warehouse and location management endpoints.

Warehouses API

The Warehouses API provides endpoints for managing warehouse locations, capacity, and inventory distribution across multiple storage facilities.

Endpoints

GET /api/warehouses

Retrieve warehouses.

Query Parameters:

  • is_active (boolean): Filter by active status
  • page (number): Page number
  • limit (number): Items per page

Response:

{
  "data": [
    {
      "id": "wh_789",
      "name": "Main Warehouse",
      "code": "MAIN",
      "address": "123 Industrial Ave",
      "city": "Warehouse City",
      "state": "CA",
      "postal_code": "90210",
      "country": "US",
      "capacity_limit": 10000,
      "current_capacity": 7500,
      "utilization_rate": 75.0,
      "manager": {
        "id": "user_123",
        "name": "Jane Smith",
        "email": "jane.smith@example.com"
      },
      "is_active": true,
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-15T10:30:00Z"
    }
  ],
  "meta": {
    "total": 5,
    "page": 1,
    "limit": 20,
    "hasMore": false
  }
}

GET /api/warehouses/:id

Retrieve a specific warehouse by ID.

Response:

{
  "data": {
    "id": "wh_789",
    "name": "Main Warehouse",
    "code": "MAIN",
    "address": "123 Industrial Ave",
    "city": "Warehouse City",
    "state": "CA",
    "postal_code": "90210",
    "country": "US",
    "phone": "+1-555-0123",
    "email": "main@warehouse.com",
    "capacity_limit": 10000,
    "current_capacity": 7500,
    "utilization_rate": 75.0,
    "manager": {
      "id": "user_123",
      "name": "Jane Smith",
      "email": "jane.smith@example.com",
      "phone": "+1-555-0456"
    },
    "operating_hours": {
      "monday": "08:00-17:00",
      "tuesday": "08:00-17:00",
      "wednesday": "08:00-17:00",
      "thursday": "08:00-17:00",
      "friday": "08:00-17:00",
      "saturday": "09:00-13:00",
      "sunday": "closed"
    },
    "is_active": true,
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
}

POST /api/warehouses

Create a new warehouse.

Request Body:

{
  "name": "West Coast Warehouse",
  "code": "WEST",
  "address": "456 Storage Blvd",
  "city": "Los Angeles",
  "state": "CA",
  "postal_code": "90001",
  "country": "US",
  "phone": "+1-555-0789",
  "email": "west@warehouse.com",
  "capacity_limit": 5000,
  "manager_id": "user_456",
  "operating_hours": {
    "monday": "07:00-18:00",
    "tuesday": "07:00-18:00",
    "wednesday": "07:00-18:00",
    "thursday": "07:00-18:00",
    "friday": "07:00-18:00",
    "saturday": "08:00-14:00",
    "sunday": "closed"
  }
}

Response:

{
  "data": {
    "id": "wh_790",
    "name": "West Coast Warehouse",
    "code": "WEST",
    "address": "456 Storage Blvd",
    "city": "Los Angeles",
    "state": "CA",
    "postal_code": "90001",
    "country": "US",
    "capacity_limit": 5000,
    "current_capacity": 0,
    "utilization_rate": 0.0,
    "manager": {
      "id": "user_456",
      "name": "Bob Johnson",
      "email": "bob.johnson@example.com"
    },
    "is_active": true,
    "created_at": "2024-01-15T18:00:00Z",
    "updated_at": "2024-01-15T18:00:00Z"
  }
}

PUT /api/warehouses/:id

Update an existing warehouse.

Request Body:

{
  "name": "Updated Warehouse Name",
  "capacity_limit": 12000,
  "manager_id": "user_789",
  "is_active": true
}

Response:

{
  "data": {
    "id": "wh_789",
    "name": "Updated Warehouse Name",
    "capacity_limit": 12000,
    "manager": {
      "id": "user_789",
      "name": "Alice Brown",
      "email": "alice.brown@example.com"
    },
    "updated_at": "2024-01-15T18:30:00Z"
  }
}

GET /api/warehouses/:id/inventory

Get inventory levels for a specific warehouse.

Query Parameters:

  • low_stock (boolean): Show only low stock items
  • out_of_stock (boolean): Show only out of stock items
  • page (number): Page number
  • limit (number): Items per page

Response:

{
  "data": {
    "warehouse": {
      "id": "wh_789",
      "name": "Main Warehouse",
      "code": "MAIN"
    },
    "inventory": [
      {
        "product_id": "prod_123",
        "product_name": "Smart Widget",
        "sku": "SW-001",
        "quantity": 150,
        "available_quantity": 145,
        "reserved_quantity": 5,
        "reorder_point": 20,
        "max_stock_level": 500,
        "location": "A1-B2-S3",
        "last_counted": "2024-01-15T10:00:00Z",
        "status": "adequate"
      },
      {
        "product_id": "prod_124",
        "product_name": "Basic Widget",
        "sku": "BW-001",
        "quantity": 15,
        "available_quantity": 15,
        "reserved_quantity": 0,
        "reorder_point": 20,
        "max_stock_level": 200,
        "location": "A2-B1-S1",
        "last_counted": "2024-01-14T15:30:00Z",
        "status": "low_stock"
      }
    ],
    "summary": {
      "total_products": 1250,
      "total_quantity": 25000,
      "low_stock_products": 25,
      "out_of_stock_products": 5,
      "capacity_used": 7500,
      "capacity_available": 2500,
      "utilization_rate": 75.0
    }
  },
  "meta": {
    "total": 1250,
    "page": 1,
    "limit": 20,
    "hasMore": true
  }
}

GET /api/warehouses/:id/analytics

Get analytics data for a specific warehouse.

Query Parameters:

  • period (string): Time period (7d, 30d, 90d, 1y)

Response:

{
  "data": {
    "warehouse": {
      "id": "wh_789",
      "name": "Main Warehouse"
    },
    "overview": {
      "total_products": 1250,
      "total_stock_value": 275000.00,
      "capacity_utilization": 75.0,
      "turnover_rate": 4.2
    },
    "movements": {
      "stock_in": 5000,
      "stock_out": 4500,
      "net_movement": 500,
      "adjustments": 50
    },
    "performance": {
      "order_fulfillment_rate": 98.5,
      "avg_pick_time": 12.5,
      "accuracy_rate": 99.2
    },
    "alerts": {
      "low_stock_items": 25,
      "out_of_stock_items": 5,
      "overstock_items": 3,
      "expiring_items": 0
    }
  }
}

POST /api/warehouses/:id/cycle-count

Initiate a cycle count for warehouse inventory.

Request Body:

{
  "count_type": "full",
  "product_ids": ["prod_123", "prod_124"],
  "locations": ["A1", "A2"],
  "scheduled_date": "2024-01-20T09:00:00Z",
  "assigned_to": "user_123",
  "notes": "Monthly cycle count"
}

Count Types:

  • full: Count all products in warehouse
  • partial: Count specific products/locations
  • abc: Count based on ABC classification
  • random: Random sample count

Response:

{
  "data": {
    "id": "cc_001",
    "warehouse_id": "wh_789",
    "count_type": "partial",
    "status": "scheduled",
    "scheduled_date": "2024-01-20T09:00:00Z",
    "assigned_to": {
      "id": "user_123",
      "name": "John Doe"
    },
    "products_to_count": 2,
    "locations_to_count": 2,
    "created_at": "2024-01-15T19:00:00Z"
  }
}