Best-selling product

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 details of the single best-selling product within a specified time range (Top 1 by sales volume).
• Data scope follows the user identity and selected groupId in the token (visible device set).
• Optional deviceCode narrows statistics to one device; when omitted, all visible devices are included.

Request URL

• https://{GATEWAY_HOST}/third-center-web/openapi/v1/phamboxDashboard/bestSeller

Request Method

• POST

Request Headers

Header	Required	Description
Content-Type	Yes	application/json
third-api-token	Yes	OpenAPI access token
X-Locale	No	Recommended: en

Parameters

Send a JSON object as the request body. When using only defaults, send {}; optional fields do not make the body optional.

Request Body:

Parameter Name	Required	Type	Description
startTimestamp	No	long	Statistics start time (millisecond timestamp). Default: first day of the current month at 00:00:00 in the statistics service's effective timezone. Supply explicit bounds; see time handling
endTimestamp	No	long	Statistics end time (millisecond timestamp). Default: current time
deviceCode	No	string	Device code. When omitted, query across all visible devices; when provided, query only that device (must be within the caller's visible scope)

Response Example

{
  "code": 200,
  "msg": "success",
  "enMsg": null,
  "data": {
    "goodsId": "goods-001",
    "productName": "Vitamin C 500mg",
    "imageUrl": "https://example.com/images/vitamin-c.jpg",
    "quantitySold": 512,
    "averagePrice": 9.99,
    "defaultPrice": 10.99
  }
}

Response Parameter Description

Response data: object or null on success. null means there are no matching sales or the visible device scope is empty.

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:

Parameter Name	Type	Description
goodsId	string	Product ID
productName	string	Product name
imageUrl	string / null	Product image URL; may be null when product metadata or an image is unavailable
quantitySold	long	Quantity sold
averagePrice	double	Average selling price (USD, major currency unit; pay amount / quantity sold)
defaultPrice	double	Default / retail price (USD, major currency unit)

Remarks

• Ranking is by sales volume descending; this endpoint returns only the Top 1 product.
• goodsId and sku are not applied as filters by this endpoint. Use Top products for those filters.
• When there is no sale in the range, or the visible device scope is empty, data may be null.
• If deviceCode is outside the caller's visible scope, the request fails with a business permission error.