Overview

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

Connect your integration to VendBoard dashboard metrics, devices, and orders. Follow the Quick start from account setup through your first device and order queries. For account setup, see Create an API user and Assign a group.

Documentation version: 1.1.0 · API version: v1

Examples: All identifiers, accounts, tokens, and amounts shown here are illustrative.

Item	Description
Document Version	1.1.0
Target Audience	Developers and testers for integrating systems
Data Format	`application/json; charset=UTF-8`

I. Domain and Request Header Parameters

Unified API Request Domain

Endpoint pages use https://{GATEWAY_HOST}/... so the environment address is defined in one place.

Setting	Production value
Domain	`api.vendboard.us`
Gateway path prefix	`/v8`
`{GATEWAY_HOST}`	`api.vendboard.us/v8`
Full base URL	`https://api.vendboard.us/v8/`

Replace {GATEWAY_HOST} with api.vendboard.us/v8, without a scheme or trailing slash. Include /v8 once.

For example, this template:

https://{GATEWAY_HOST}/polarstar-auth/auth/third-api/switchGroup

resolves to:

https://api.vendboard.us/v8/polarstar-auth/auth/third-api/switchGroup

Full Request URL = https:// + {GATEWAY_HOST} + / + Service Path + API Path

Type	Service Path	Description
Authentication APIs	`polarstar-auth/auth/third-api`	Login, switch group, logout
Business APIs	`third-center-web/openapi/v1`	OpenAPI business functions (e.g., Dashboard)

URL Examples:

POST https://{GATEWAY_HOST}/polarstar-auth/auth/third-api/token
POST https://{GATEWAY_HOST}/third-center-web/openapi/v1/phamboxDashboard/summary

Request Headers

Use these request headers; optional headers and authentication exceptions are noted below:

Content-Type: Fixed as application/json.
X-Locale: Language for response messages; en (English) is recommended. If omitted, the msg field is returned in the platform's default language.
third-api-token: Access token. The value is the accessToken returned by the login API.

Not required for the Login API (token).
Mandatory for Switch Group, Logout, and all Business APIs.
After successfully switching groups, the value in the header must be immediately updated with the newly returned accessToken.

Example request headers for authenticated endpoints:

Content-Type: application/json
X-Locale: en
third-api-token: EXAMPLE_TOKEN_NOT_VALID

Example request headers for the login endpoint:

Content-Type: application/json
X-Locale: en

II. Standardized Response Format

Response Structure

Field	Type	Description
`code`	Integer	Business status code; `200` indicates success
`msg`	String	Informational message; language determined by `X-Locale`
`enMsg`	String / null	English message when available; may be `null` on success or failure
`data`	Object / Array / null / String	Success payloads use the endpoint-specific object, array or null shape. Error payloads may also be a message string or an array of validation messages; do not deserialize them as success data.

Null and empty responses

Check both the HTTP status and code before using data. Do not assume that an HTTP 200 response has a non-null payload, or that data: null always means failure.

Response case	Shape of `data`
Successful logout	`null`
Best-selling product with no matching sales or no visible devices	`null`
Sales by device or device aisle hierarchy with no results	`[]`
Device profile with no results	`{ "list": [] }`
A paginated query with no results	An object containing `total: 0` and `records: []`
Business or authentication error	May be a message string or `null`; use `code` and the error message to determine the outcome
Request validation error	May contain an array of validation-message strings
Invalid JSON or a system / downstream error	May contain a diagnostic string; never parse it as a successful endpoint payload

For other object responses, check for a non-null payload before reading fields. An unknown order is a business error; do not rely on a successful null response as a general not-found convention. Individual fields may also be nullable, as indicated by string / null or double / null in their parameter tables. On a non-success code, ignore the endpoint's success schema and handle the error first.

Except for rare system exceptions, the HTTP status code remains 200 even upon failure; success or failure must be determined by checking the code.

Success Example:

{
	"code": 200,
	"msg": "success",
	"enMsg": null,
	"data": {}
}

Failure Example (Invalid Token):

{
	"code": -4,
	"msg": "Token is incorrect or invalid,please login again",
	"enMsg": "Token is incorrect or invalid,please login again",
	"data": "Token is incorrect or invalid,please login again"
}

Error Code Explanation

HTTP Status Codes vs. `body.code`

HTTP	`body.code`	Description
200	200	Success
200	Not 200	Business/Authentication failure
404	0	Path not found
500	500	System exception

Common Codes

Code	Meaning	`msg` Example (`X-Locale: en`)
200	Success	success
-1	Business exception
-2	Incorrect username or password	User name or password is wrong.
-3	Missing authentication header on some authentication paths	Request head doesnot have token
-4	Invalid or expired token	Token is incorrect or invalid,please login again
500	System error	system error

Common Business Errors (`code` = -1)

Scenario	`msg` Example (`X-Locale: en`)
Third-party API permission not enabled	Third-party API access is not enabled for this account. Please contact the platform operator.
No Group assigned to the API account	Current user is not bound to any group, login denied
Invalid or unbound `groupId`	Group does not exist or has been deactivated
Insufficient data permissions	Requested device/group is not within your permission scope

III. Authentication Details

Integrators must use the system user account assigned by the platform. API calls can only be made after the operator has enabled Third-party API permissions for the account.

Integration Workflow

Call the Login API to obtain the accessToken and switchableGroups (list of switchable groups).
Include the third-api-token in the request header when calling business APIs.
When necessary, select a target group from switchableGroups and call the Switch Group API; call the Logout API when the session ends.

Groups and data scope

Use the API account provided for your integration. It needs third-party API access and an assigned Group.

Queries use your selected Group and the filters sent with each request. The login response contains the selected groupId and available switchableGroups. Use Switch group to select another Group, then use the returned access token for subsequent requests.

Request bodies and pagination

All documented endpoints use POST. Send a JSON object for every endpoint except Log out and Online devices, which take no body. If all body fields are optional and you want defaults, send {} rather than an empty HTTP body. A JSON null body is not a substitute for an object. Login and single-device queries still require their listed fields.

For paginated endpoints, send current and size in the URL query string; both default to 1 and 10, respectively. Use positive integers. Supported filters are listed on each endpoint page.

Time values and statistics boundaries

Request fields ending in Timestamp, device activity timestamps and expiresIn are Unix timestamps in milliseconds. expiresIn is an absolute expiry time.
Dashboard defaults to the first day of the current month at midnight through now. Send explicit start/end timestamps for a specific range, with start no later than end. Calendar days use the statistics timezone; confirm that timezone with your API contact.
Sales trend returns daily yyyy-MM-dd labels and fills dates without sales with zero. Supply both comparison bounds to request a comparison period.
Order fields such as tradeStartTime, payEndTime, payEndDate and shipmentTime are date strings. Examples use yyyy-MM-dd HH:mm:ss, including payEndDate. These strings contain no timezone offset; confirm the format and timezone for your API environment.
Payment and shipment times may be null when the corresponding event has not occurred. Handle missing optional metadata without treating it as an authentication failure.

Currency and amount units

Dashboard monetary statistics use USD. Dashboard fields such as sales-trend amount, averagePrice, defaultPrice, and product price use dollars (major currency units). KPI value remains a formatted string; count and percentage KPIs are not monetary values. Device-aisle price and showPrice are integer minor units in the product's currency, unlike Dashboard product prices.

Order amount fields such as totalAmount and payAmount use integer minor currency units. For USD, 1299 means $12.99. Read the order's currency field when interpreting order amounts; do not mix order cents with dashboard dollars.

Token Validity

Configuration Item	Default Value	Description
Access Token Validity	7,200 seconds (2 hours)	Subject to the actual environment
`expiresIn`	Millisecond timestamp	Absolute expiration time of the token

There is no refresh endpoint in this version. Log in again after expiry and reselect your Group if needed.

I. Domain and Request Header Parameters​

Unified API Request Domain​

Request Headers​

II. Standardized Response Format​

Response Structure​

Null and empty responses​

Error Code Explanation​

HTTP Status Codes vs. body.code​

Common Codes​

Common Business Errors (code = -1)​

III. Authentication Details​

Integration Workflow​

Groups and data scope​

Request bodies and pagination​

Time values and statistics boundaries​

Currency and amount units​

Token Validity​