Device profile

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 overview / profile information for a single device (online status, running status, stock, cabinet door status, etc.)
• 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/deviceProfile

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": {
    "list": [
      {
        "deviceId": "dev-001",
        "deviceCode": "KIOSK-001",
        "deviceName": "Lobby Kiosk A",
        "isRunning": 1,
        "isOnline": 1,
        "isGoodsMerge": 0,
        "totalCurrStock": 120,
        "cabinets": [
          {
            "cabinetCode": 0,
            "doorStatus": 0
          }
        ]
      }
    ]
  }
}

Response Parameter Description

Response data: object containing a list array on success. An empty result is { "list": [] }, not a top-level array.

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:

Parameter Name	Type	Description
list	array	Device profile list (normally 0 or 1 item for a single-device query)
list[].deviceId	string	Device ID
list[].deviceCode	string	Device code
list[].deviceName	string	Device name
list[].isRunning	int	1 within its configured operating schedule (also the default when no schedule exists), 0 outside it; not the device-list business status
list[].isOnline	int / null	Main-controller online flag, normally 1 online / 0 offline; see the missing-telemetry limitation below
list[].isGoodsMerge	int / null	Goods merge: 1 enabled, 0 disabled; may be null when settings are absent
list[].totalCurrStock	long / null	Total current stock; may be null when no stock aggregate is available
list[].cabinets	array / null	Cabinet list; may be null when operational telemetry is absent
list[].cabinets[].cabinetCode	int	Zero-based cabinet code; the first cabinet is 0
list[].cabinets[].doorStatus	int	Door status (1 open, 0 closed)

Notes

• Online status: isOnline defaults to 1 when no operational record exists and may be null when a record has no online flag. To check connectivity, use List devices or Online devices, which count missing online flags as offline.
• 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).