Locations - Metabox Inventory Service

Overview

Locations represent specific coordinates within warehouses for precise inventory tracking. Each location is defined by floor, row, section, and level coordinates with automatic sorting capabilities.

Create Location

Creates a new location within a warehouse with the specified coordinates.

POST /api/locations/create-location

Request Body

        {
  "ms_trace": [
    {
      "ms_signature": "location-create-req-123",
      "warning_count": 0
    }
  ],
  "data": {
    "floor": 1,
    "row": 5,
    "section": 12,
    "level": 2,
    "warehouse_id": 456
  }
}
    

Request Parameters

Field	Type	Required	Description
ms_trace	array	Required	Request tracing information
data.floor	integer	Required	Floor number (e.g., 1, 2, 3)
data.row	integer	Required	Row number within the floor
data.section	integer	Required	Section number within the row
data.level	integer	Required	Level/shelf number within the section
data.warehouse_id	integer	Required	ID of the warehouse this location belongs to

Sort Number Generation

The system automatically generates a sort_number for efficient ordering and searching:

        Format: [floor][level][padded_row][padded_section]

Example:
- Floor: 1, Level: 2, Row: 5, Section: 12
- Row padded to 3 digits: 005
- Section padded to 3 digits: 012
- Sort Number: 12005012
    

Response

Returns success status with created location data including the auto-generated sort_number. Exact response structure not verified from controller.

Location Coordinate System

Coordinate Hierarchy

Warehouse
├── Floor 1
│   ├── Row 1
│   │   ├── Section 1
│   │   │   ├── Level 1 (Ground shelf)
│   │   │   ├── Level 2 (Middle shelf)
│   │   │   └── Level 3 (Top shelf)
│   │   └── Section 2...
│   └── Row 2...
└── Floor 2...

Best Practices

Floor Numbers: Start from 1 for ground floor, 2 for first floor, etc.
Row Organization: Number rows sequentially within each floor
Section Numbering: Use consistent numbering across all rows
Level Heights: Level 1 = ground level, higher numbers = higher shelves

Location Relationships

Warehouse Association

Locations are associated with warehouses through a many-to-many relationship via the warehouse_locations pivot table.

Storage Unit Integration

Locations can be referenced in storage unit operations:

location_id_to_remove - Source location for moves
location_id_to_put - Destination location for moves

Service Implementation

Location creation is handled by the CreateLocation service class, which:

Validates coordinate uniqueness within the warehouse
Automatically calculates the sort number
Creates the location record
Establishes warehouse-location relationships

Error Responses

Validation Errors

Standard Laravel validation error responses may be returned for missing or invalid required fields. Exact formats not verified from controller code.

Business Logic Errors

Additional error responses may be returned for business rule violations such as duplicate locations or invalid warehouse references. Exact error formats not verified from controller code.

Usage Examples

Ground Level Storage

        {
  "floor": 1,
  "row": 1,
  "section": 1,
  "level": 1
}
    

High Bay Storage

        {
  "floor": 1,
  "row": 15,
  "section": 25,
  "level": 8
}
    

Multi-Floor Facility

        {
  "floor": 3,
  "row": 8,
  "section": 12,
  "level": 2
}
    