Device aisles

Applies to: API integrators with third-party API access.

Use Content-Type: application/json and optionally X-Locale: en. The third-api-token header is required. See common headers and error handling.

Brief Description

• Query aisle hierarchy information for a single device (cabinets / layers / aisles)
• deviceCode is required; only one device can be queried per request
• Data scope follows the user identity and groupId associated with the Token; the device must be within the current permission scope

Request URL

• https://{GATEWAY_HOST}/third-center-web/openapi/v1/phamboxDevice/deviceInfo

Request Method

• POST

Header

Parameter Name	Required	Type	Description
third-api-token	Yes	string	Access token obtained from the login interface

Parameters

Request Body:

Parameter Name	Required	Type	Description
deviceCode	Yes	string	Device code (single device only)

Response Example

{
  "code": 200,
  "msg": "success",
  "enMsg": null,
  "data": [
    {
      "deviceId": "dev-001",
      "deviceCode": "KIOSK-001",
      "deviceName": "Lobby Kiosk A",
      "cabinetTotal": 1,
      "layerTotal": 5,
      "aisleTotal": 40,
      "cabinets": [],
      "cabinetAttrList": []
    }
  ]
}

Response Parameter Description

Response data: An array on success, normally containing zero or one device. An empty result is [].

Errors: data may be null, a string or an array of messages. Check the HTTP status and code before reading success data. See error handling.

Response (data is an array; normally 0 or 1 item for a single-device query):

Parameter Name	Type	Description
deviceId	string	Device ID
deviceCode	string	Device code
deviceName	string	Device name
cabinetTotal	int	Number of cabinets
layerTotal	int	Total number of layers across cabinets
aisleTotal	int	Total number of aisles
cabinets	array	Cabinet hierarchy details; see the nested fields below
cabinetAttrList	array / null	Model-specific cabinet attributes; see the extension-data note below

Cabinet and layer fields

The following paths are relative to one device in data[].

Field	Type	Description
cabinets[].code	int	Zero-based cabinet number
cabinets[].layerCount	int	Number of layers in this cabinet
cabinets[].doorStatus	int / null	1 open / 0 closed when populated; null when unavailable. Use Device profile for door telemetry
cabinets[].layers	array	Layers belonging to the cabinet
cabinets[].layers[].layer	string	Layer label, such as A
cabinets[].layers[].aisleCount	int	Number of aisles in the layer
cabinets[].layers[].aisles	array	Aisle objects, described below

Aisle fields

These fields belong to each data[].cabinets[].layers[].aisles[] object. Optional product metadata, settings and extension values can be null or absent; the types below describe non-null values. Handle fields independently rather than requiring every field for every device model.

Field	Type	Description
id	string	Aisle record ID
cabinet	int	Zero-based cabinet number
layer	string	Layer label
code	string	Full aisle code, such as 0-A0
showName	string	Aisle display name
shippingMode	int	Device shipment-mode code; values depend on the supported model
ctrlBoard	int	Controller-board number
ctrlCmd	int	Controller command value; informational in this query API
measurement	int	Measurement code: 0 pieces, 1 weight in grams; preserve other codes and confirm their unit
price	int	Actual selling price in the product currency's minor units
showPrice	int	Display price in minor units
maxStock	int	Capacity in the configured measurement unit
currStock	int	Available stock after subtracting cached stock reservations; may differ from a raw inventory total
order	int	Configured sort value; do not assume the returned arrays are sorted by it
status	int	Aisle status; 1 indicates normal
remark	string	Aisle remark
isHot	int	Hot-item flag as stored by the device configuration
isCombine	int	Combined aisle flag: 0 no / 1 yes
isEnable	boolean	Whether the aisle is enabled; JSON boolean, not an integer flag
isBroken	boolean	Whether the aisle is marked faulty; JSON boolean
goodsId	string	Assigned product ID
goodsName	string	Product name
goodsCode	string	Product code
goodsCustomCode	string	Custom product code
barcode	string	Product barcode / SKU
currency	string	Product currency code used for aisle prices
imgUrl	string	Product image URL
thumbnailUrl	string	Product thumbnail URL
weight	int	Product weight in its configured measurement convention
recognitionWeight	int	Weight-recognition value, when calculated; do not assume it equals stock
packType	string	Packaging type
expirationTimestamp	long	Product expiration timestamp in milliseconds
warningDay	int	Expiration warning lead time in days
goodsDescription	string	Product description
goodsRemark	string	Product remark
goodsTypeList	array	Product categories; each item contains string fields id, code and name
goodsExtendObject	object	Product-specific extension data; keys depend on product configuration

Model-specific extension data

cabinetAttrList contains JSON values configured on the device model, passed through without a fixed OpenAPI item schema. It can be empty or null. goodsExtendObject likewise has configuration-specific keys. Preserve or ignore unrecognized keys; obtain the intended model's field and unit definitions from the platform operator before depending on an extension. These extensions are not a replacement for the cabinet/layer/aisle fields above.

Notes

• If deviceCode is missing or blank, the API returns a business error.
• If the device is not within the current Token group permission scope, the API returns a business error (phambox.scope.deviceNotInScope).