Items Endpoints: Catalog Inquiry & RFID Tag Resolution

The items API exposes the warehouse item catalog and its bin-level stock data. The inquiry endpoints return results even when stock is zero or negative — this is by design so operators can locate items that have been over-issued or await a receipt. The ItemNo field carries the ERP item code (e.g., ITEM-0042) and is the primary lookup key across all warehouse operations; it is not an internal auto-generated surrogate ID. All endpoints on this page require a valid session token and a company context header. Required headers for all endpoints:

Authorization: Bearer <token>
X-Company-Id: <company-guid>

GET /api/items/inquiry

Searches the item catalog and returns paginated summaries with per-bin stock quantities. The search parameter matches against item number, description, or bin code. When both itemNo and binCode are provided by the caller, itemNo takes precedence as the effective search term. Method & path: GET /api/items/inquiry
Auth required: Yes

Query parameters

string

Free-text search term. Matched against ItemNo, item description, and BinCode. Either itemNo or binCode are resolved to this parameter client-side before the request is sent.

PageNumber

integer

required

1-based page number.

PageSize

integer

required

Number of records per page. Recommended maximum: 50.

Response — 200 OK

Returns a PagedResponse<ItemSummaryDto>.

{
  "pageNumber": 1,
  "pageSize": 20,
  "totalRecords": 142,
  "totalPages": 8,
  "data": [
    {
      "itemNo": "ITEM-0042",
      "locationCode": "WH-MAIN",
      "totalQty": 350.00,
      "binQuantities": [
        {
          "companyId": "9c8b7a6f-...",
          "itemId": "a1b2c3d4-...",
          "itemNo": "ITEM-0042",
          "itemDescription": "Bolt M8 x 30mm",
          "itemUOM": "EA",
          "itemType": "INVENTORY",
          "itemIsActive": true,
          "isLotTracked": false,
          "isSerialTracked": false,
          "isExpirationTracked": false,
          "unitWeight": 0.012,
          "unitVolume": null,
          "binId": "b9c8d7e6-...",
          "binCode": "A-01-02",
          "binDescription": "Rack A, Bay 1, Shelf 2",
          "binType": "PICK",
          "binIsActive": true,
          "isBlocked": false,
          "allowPicking": true,
          "allowPutaway": false,
          "stockQty": 350.00
        }
      ]
    }
  ],
  "hasPrevious": false,
  "hasNext": true
}

pageNumber

integer

Current page number.

pageSize

integer

Records per page as requested.

totalRecords

integer

Total number of matching records across all pages.

totalPages

integer

Total number of pages.

hasPrevious

boolean

Whether a previous page exists.

hasNext

boolean

Whether a next page exists.

data

array

Array of ItemSummaryDto objects.

Show ItemSummaryDto

itemNo

string

ERP item code. This is the canonical identifier used across all warehouse documents — not an internal UUID.

locationCode

string

Warehouse location code the stock figures relate to.

totalQty

decimal

Sum of stockQty across all bins for this item in the location. Can be zero or negative.

binQuantities

array

Per-bin stock breakdown. Each entry is an ItemInquiryDto.

Show ItemInquiryDto

companyId

string

Company identifier for this stock record.

itemId

string

Internal UUID of the item.

itemNo

string

ERP item code.

itemDescription

string

Item display name.

itemUOM

string

Unit of measure code, e.g. EA, KG, BOX.

itemType

string

Item classification, e.g. INVENTORY, SERVICE.

itemIsActive

boolean

Whether the item is active in the catalog.

isLotTracked

boolean

Item requires a lot number on all movements.

isSerialTracked

boolean

Item requires a serial number on all movements.

isExpirationTracked

boolean

Item tracks expiration dates.

unitWeight

decimal | null

Weight per unit in the tenant’s configured weight unit.

unitVolume

decimal | null

Volume per unit in the tenant’s configured volume unit.

binId

string

Internal UUID of the bin.

binCode

string

Bin code, e.g. A-01-02.

binDescription

string

Human-readable bin label.

binType

string

Bin classification, e.g. PICK, BULK, RECEIVE.

binIsActive

boolean

Whether the bin is active for operations.

isBlocked

boolean

Bin is blocked — no movements allowed.

allowPicking

boolean

Picking is permitted from this bin.

allowPutaway

boolean

Putaway is permitted into this bin.

stockQty

decimal

Current on-hand quantity in this bin. May be zero or negative.

Example

curl "https://your-server/api/items/inquiry?search=ITEM-0042&PageNumber=1&PageSize=20" \
  -H "Authorization: Bearer <token>" \
  -H "X-Company-Id: 9c8b7a6f-1234-5678-abcd-ef0123456789"

GET /api/items/products-inquiry

Returns a broader product-level inquiry with optional location and stock-only filters. Designed for the product browser screen where operators need a location-aware view of available stock. The response type is ProductInquiryPageDto, which carries a flat items array (not the nested binQuantities structure of GET /api/items/inquiry) together with summary totals. Method & path: GET /api/items/products-inquiry
Auth required: Yes

Query parameters

string

Free-text search term matched against item number and description.

locationCode

string

Filter results to a specific warehouse location code.

hasStockOnly

boolean

When true, returns only items with positive on-hand quantity. Defaults to false.

pageNumber

integer

required

1-based page number.

pageSize

integer

required

Number of records per page.

Response — 200 OK

Returns a ProductInquiryPageDto.

{
  "pageNumber": 1,
  "pageSize": 20,
  "totalRecords": 58,
  "totalPages": 3,
  "totalQuantity": 4820.0,
  "quantityLabel": "Cantidad",
  "items": [
    {
      "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
      "itemNo": "ITEM-0042",
      "description": "Bolt M8 x 30mm",
      "alternateItemNo": null,
      "barcode": "7890001234567",
      "unitOfMeasure": "EA",
      "secondaryUnitOfMeasure": null,
      "isActive": true,
      "allowNegativeAvailable": false,
      "status": "Active",
      "defaultLocationCode": "WH-MAIN",
      "shelfCode": null,
      "locationCode": "WH-MAIN",
      "locationDescription": "Main Warehouse",
      "binCode": "A-01-02",
      "binDescription": "Rack A, Bay 1, Shelf 2",
      "quantity": 350.0,
      "quantityType": "OnHand",
      "asOfUtc": "2024-06-30T08:00:00Z"
    }
  ]
}

pageNumber

integer

Current page number.

pageSize

integer

Records per page as requested.

totalRecords

integer

Total matching records across all pages.

totalPages

integer

Total number of pages.

totalQuantity

decimal

Sum of quantity across all matching records on the current page.

quantityLabel

string

Label for the quantity column, localised by the server. Defaults to "Cantidad".

items

array

Array of ProductInquiryRowDto objects.

Show ProductInquiryRowDto

guid | null

Internal item UUID.

itemNo

string

ERP item code.

description

string | null

Item display name.

alternateItemNo

string | null

Alternate item lookup code.

barcode

string | null

Primary barcode value.

unitOfMeasure

string | null

Default unit of measure code.

secondaryUnitOfMeasure

string | null

Secondary unit of measure, if applicable.

isActive

boolean | null

Whether the item is active in the catalog.

allowNegativeAvailable

boolean | null

Item can be processed even when available quantity is negative.

status

string | null

Item status description.

defaultLocationCode

string | null

Default warehouse location for this item.

shelfCode

string | null

Shelf or aisle code within the location.

locationCode

string | null

Warehouse location code for this stock record.

locationDescription

string | null

Human-readable location name.

binCode

string | null

Bin code for this stock record.

binDescription

string | null

Human-readable bin label.

quantity

decimal | null

Current stock quantity in this bin/location.

quantityType

string | null

Describes what the quantity represents, e.g. "OnHand", "Available".

asOfUtc

datetime | null

UTC timestamp indicating when the quantity snapshot was taken.

Example

curl "https://your-server/api/items/products-inquiry?search=bolt&locationCode=WH-MAIN&hasStockOnly=true&pageNumber=1&pageSize=20" \
  -H "Authorization: Bearer <token>" \
  -H "X-Company-Id: 9c8b7a6f-1234-5678-abcd-ef0123456789"

GET /api/items/products-locations

Returns the list of warehouse locations available as filter options for the product inquiry screen. The response identifies the default location so the UI can pre-select it when the view loads. Method & path: GET /api/items/products-locations
Auth required: Yes

Response — 200 OK

Returns a ProductLocationListDto.

{
  "defaultLocationCode": "WH-MAIN",
  "locations": [
    {
      "locationCode": "WH-MAIN",
      "locationDescription": "Main Warehouse",
      "isDefaultSelection": true
    },
    {
      "locationCode": "WH-B",
      "locationDescription": "Annex Warehouse B",
      "isDefaultSelection": false
    }
  ]
}

defaultLocationCode

string | null

Location code that should be pre-selected in the UI filter. null if no default is configured.

locations

array

List of ProductLocationOptionDto objects representing available locations.

Show ProductLocationOptionDto

locationCode

string

Warehouse location code, e.g. WH-MAIN.

locationDescription

string | null

Human-readable location name.

isDefaultSelection

boolean

Whether this location is the pre-selected default.

Example

curl "https://your-server/api/items/products-locations" \
  -H "Authorization: Bearer <token>" \
  -H "X-Company-Id: 9c8b7a6f-1234-5678-abcd-ef0123456789"

GET /api/items/

Returns the full detail record for a single item by its internal UUID. Method & path: GET /api/items/{id}
Auth required: Yes

Path parameters

guid

required

Internal UUID of the item.

Response — 200 OK

Returns an ItemDetailApiDto.

{
  "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "itemNo": "ITEM-0042",
  "description": "Bolt M8 x 30mm",
  "uom": "EA",
  "baseUOM": "EA",
  "salesUOM": "BOX",
  "purchaseUOM": "BOX",
  "part_No": "BLT-M8-30",
  "alternative_Code": "ALT-042",
  "conversionFactor": 100.0,
  "isActive": true,
  "itemType": "INVENTORY",
  "barcode": "7890001234567",
  "altBarcode": null,
  "isLotTracked": false,
  "isSerialTracked": false,
  "isExpirationTracked": false,
  "allowNegativeAvailable": false,
  "unitWeight": 0.012,
  "unitVolume": null,
  "categoryCode": "HARDWARE",
  "brand": "FastFix",
  "abcClass": "A",
  "accountingCollection": null,
  "branchCode": null,
  "costingMethod": "AVERAGE",
  "createdBy": "[email protected]",
  "createdAt": "2023-01-15T08:00:00Z",
  "updatedBy": null,
  "updatedAt": null,
  "quantityOnHand": 350.0,
  "qtyOnPurchOrder": 200.0,
  "qtyOnSalesOrder": 50.0,
  "qtyAvailable": 300.0,
  "qtyOnProdOrder": 0.0,
  "stockoutWarning": false,
  "images": [
    {
      "id": "img-uuid",
      "url": "https://cdn.acme.com/items/bolt-m8.jpg",
      "isPrimary": true
    }
  ]
}

guid

Internal item UUID.

itemNo

string

ERP item code.

description

string | null

Item display name.

uom

string | null

Default unit of measure.

baseUOM

string | null

Base unit of measure for conversions.

salesUOM

string | null

Unit used on sales orders.

purchaseUOM

string | null

Unit used on purchase orders.

part_No

string | null

Manufacturer or supplier part number.

alternative_Code

string | null

Alternative lookup code.

conversionFactor

decimal | null

Conversion factor between base UOM and sales/purchase UOM.

isActive

boolean

Whether the item is active in the catalog.

itemType

string | null

Item classification type.

barcode

string | null

Primary barcode value.

altBarcode

string | null

Alternate barcode value.

isLotTracked

boolean

Lot number required on movements.

isSerialTracked

boolean

Serial number required on movements.

isExpirationTracked

boolean

Expiration date tracked.

allowNegativeAvailable

boolean

Item may be processed even when available quantity is negative.

unitWeight

decimal | null

Weight per unit.

unitVolume

decimal | null

Volume per unit.

categoryCode

string | null

Item category.

brand

string | null

Brand name.

abcClass

string | null

ABC classification (A / B / C).

accountingCollection

string | null

Accounting grouping code.

branchCode

string | null

Branch assignment code.

costingMethod

string | null

Inventory costing method, e.g. AVERAGE, FIFO.

createdBy

string

Email of user who created the record.

createdAt

datetime

UTC timestamp of record creation.

updatedBy

string | null

Email of user who last updated the record.

updatedAt

datetime | null

UTC timestamp of last update.

quantityOnHand

decimal

Current on-hand quantity across all bins.

qtyOnPurchOrder

decimal

Quantity committed on open purchase orders.

qtyOnSalesOrder

decimal

Quantity committed on open sales orders.

qtyAvailable

decimal

Available quantity = on-hand minus committed.

qtyOnProdOrder

decimal

Quantity committed on open production orders.

stockoutWarning

boolean

Server has flagged this item as at risk of stockout.

images

array

List of item images.

Show ItemImageApiDto

guid

Image record UUID.

url

string

Full URL to the image resource.

isPrimary

boolean

Whether this is the primary display image.

Returns 404 Not Found when no item with the given ID exists.

Example

curl "https://your-server/api/items/a1b2c3d4-5678-90ab-cdef-1234567890ab" \
  -H "Authorization: Bearer <token>" \
  -H "X-Company-Id: 9c8b7a6f-1234-5678-abcd-ef0123456789"

GET /api/items/by-itemno/

Returns the full detail record for a single item looked up by its ERP item code. Functionally equivalent to GET /api/items/{id} but uses the human-readable ItemNo as the key, which is more convenient when scanning barcodes. Method & path: GET /api/items/by-itemno/{itemNo}
Auth required: Yes

Path parameters

itemNo

string

required

ERP item code. URL-encoded if it contains special characters.

Returns 404 Not Found when no item with the given ItemNo exists.

Example

curl "https://your-server/api/items/by-itemno/ITEM-0042" \
  -H "Authorization: Bearer <token>" \
  -H "X-Company-Id: 9c8b7a6f-1234-5678-abcd-ef0123456789"

GET /api/rfid/tags/resolve/

Resolves a scanned RFID EPC tag to its associated item, bin, and status information. Called by the handheld immediately after a tag is read to identify the item without requiring the operator to manually search the catalog.

When the EPC is not found, the server returns 404 with a structured JSON body (not a plain error string). The client reads the message field from that body and surfaces it to the operator. This allows the handheld to fall back to a manual GET /api/items/inquiry search if the tag is unregistered in the system.

Method & path: GET /api/rfid/tags/resolve/{epc}
Auth required: Yes

Path parameters

epc

string

required

The Electronic Product Code read from the RFID tag. URL-encoded.

Response — 200 OK

{
  "epc": "E2806894000050138372B6AA",
  "objectType": "ITEM",
  "status": "ACTIVE",
  "itemId": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "itemNo": "ITEM-0042",
  "itemDescription": "Bolt M8 x 30mm",
  "quantity": 1.0,
  "locationCode": "WH-MAIN",
  "binCode": "A-01-02",
  "isResolved": true,
  "isActive": true,
  "message": ""
}

epc

string

The EPC value that was resolved.

objectType

string

Type of object encoded in the tag, e.g. ITEM, PALLET.

status

string

Current tag status, e.g. ACTIVE, INACTIVE, UNKNOWN.

itemId

guid | null

Internal UUID of the associated item. null if the tag is not linked to an item.

itemNo

string

ERP item code of the associated item.

itemDescription

string

Item display name.

quantity

decimal

Quantity encoded in the tag, typically 1 for serialised items.

locationCode

string

Warehouse location where the tag was last registered.

binCode

string

Bin where the tag was last registered.

isResolved

boolean

true when the EPC was matched to a known item record.

isActive

boolean

true when the tag is active and usable for operations.

message

string

Human-readable status or error message. Populated with "RFID tag not found." on 404 responses.

Error conditions

Status	Condition
`404 Not Found`	EPC not registered in the system. Response body still contains a `RfidTagResolveDto` with `isResolved: false` and a `message` field.
`400 Bad Request`	`epc` parameter was empty or whitespace.

Example

curl "https://your-server/api/rfid/tags/resolve/E2806894000050138372B6AA" \
  -H "Authorization: Bearer <token>" \
  -H "X-Company-Id: 9c8b7a6f-1234-5678-abcd-ef0123456789"

API Endpoints

Services

Data Models

Items Endpoints: Catalog Inquiry & RFID Tag Resolution

GET /api/items/inquiry

Query parameters

Response — 200 OK

Example

GET /api/items/products-inquiry

Query parameters

Response — 200 OK

Example

GET /api/items/products-locations

Response — 200 OK

Example

GET /api/items/

Path parameters

Response — 200 OK

Example

GET /api/items/by-itemno/

Path parameters

Example

GET /api/rfid/tags/resolve/

Path parameters

Response — 200 OK

Error conditions

Example

Build docs developers (and LLMs) love

API Endpoints

Services

Data Models

Documentation Index

​GET /api/items/inquiry

​Query parameters

​Response — 200 OK

​Example

​GET /api/items/products-inquiry

​Query parameters

​Response — 200 OK

​Example

​GET /api/items/products-locations

​Response — 200 OK

​Example

​GET /api/items/

​Path parameters

​Response — 200 OK

​Example

​GET /api/items/by-itemno/

​Path parameters

​Example

​GET /api/rfid/tags/resolve/

​Path parameters

​Response — 200 OK

​Error conditions

​Example

Build docs developers (and LLMs) love

GET /api/items/inquiry

Query parameters

Response — 200 OK

Example

GET /api/items/products-inquiry

Query parameters

Response — 200 OK

Example

GET /api/items/products-locations

Response — 200 OK

Example

GET /api/items/

Path parameters

Response — 200 OK

Example

GET /api/items/by-itemno/

Path parameters

Example

GET /api/rfid/tags/resolve/

Path parameters

Response — 200 OK

Error conditions

Example