Quick start

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

Follow this sequence to make your first device and order queries:

Prepare account → Log in → Confirm Group → List devices → List orders → Read order detail → Log out

1. Prepare your account and environment

Before you begin, have these details ready:

• An account with Third Party API Login enabled and at least one assigned Group.
• Your Login Name and password.
• The Group and devices you want to query. To try the order requests, use a device with existing orders.

For account setup, see Create an API user and Assign a group.

The following cURL examples use Bash syntax (Linux, macOS, WSL or Git Bash). Replace the uppercase example values before running. All requests use HTTPS. The -i option displays HTTP response headers so you can check transport status as well as the JSON business code.

Copy the environment's {GATEWAY_HOST} value from the Overview. It includes /v8, with no scheme or trailing slash. Set it once in the same shell used for the remaining steps:

GATEWAY_HOST='REPLACE_WITH_GATEWAY_HOST_FROM_OVERVIEW'

Replace the account, token and device placeholders with your own values.

2. Log in and save the access token

Use the account's Login Name as username, not its display name. Supply its password as a JSON string; do not pre-hash it. Encode any special characters using normal JSON escaping. No Token header is needed for Log in.

curl --silent --show-error -i --request POST \
  "https://${GATEWAY_HOST}/polarstar-auth/auth/third-api/token" \
  --header 'Content-Type: application/json' \
  --header 'X-Locale: en' \
  --data-raw '{"username":"YOUR_LOGIN_NAME","password":"YOUR_PASSWORD"}'

Check the HTTP status, then require code: 200 and a non-null data object. Read:

Field	What to do
data.accessToken	Save the complete value for authenticated requests
data.groupId	Check the selected Group before making queries
data.switchableGroups	Find the intended Group by name and use its actual groupId
data.expiresIn	Store the absolute Unix expiration timestamp in milliseconds; this is not a number of seconds remaining

Paste data.accessToken into a shell variable. Send the raw value in third-api-token, without a Bearer prefix:

ACCESS_TOKEN='PASTE_ACCESS_TOKEN_FROM_LOGIN'

Keep passwords and tokens private. Do not commit filled-in examples or share unredacted terminal output. The response may include refreshToken, but this version has no available refresh endpoint; log in again after expiry.

3. Confirm or switch the current Group

If data.groupId already identifies the intended Group, skip this request. Otherwise, copy a groupId from data.switchableGroups and call Switch group:

curl --silent --show-error -i --request POST \
  "https://${GATEWAY_HOST}/polarstar-auth/auth/third-api/switchGroup" \
  --header 'Content-Type: application/json' \
  --header 'X-Locale: en' \
  --header "third-api-token: ${ACCESS_TOKEN}" \
  --data-raw '{"groupId":"GROUP_ID_FROM_SWITCHABLE_GROUPS"}'

Require code: 200, confirm the returned data.groupId, and replace the token before continuing:

ACCESS_TOKEN='PASTE_ACCESS_TOKEN_FROM_SWITCH_GROUP'

Choose a Group from switchableGroups. A groupId filter on a device query does not change the selected Group.

Requests using the same account share a session and selected Group. Logging in again replaces the previous session. Finish requests for one Group before switching, and share token updates across workers.

4. List devices

Call List devices with {} to query without additional filters. Pagination belongs in the URL query string:

curl --silent --show-error -i --request POST \
  "https://${GATEWAY_HOST}/third-center-web/openapi/v1/phamboxDevice/devicePage?current=1&size=10" \
  --header 'Content-Type: application/json' \
  --header 'X-Locale: en' \
  --header "third-api-token: ${ACCESS_TOKEN}" \
  --data-raw '{}'

On success, data contains total, current, size and records. Read device codes from data.records[].deviceCode. Choose one of the expected devices and use its actual code in step 5.

• If records is empty, check the selected Group and its assigned kiosks before continuing.
• For more pages, increment current, keep the same filters and Group, and use total to determine whether more results remain. An empty page ends the current traversal. Results may change between requests.

5. Query orders for that device

Call List orders. deviceCode is required; current and size remain URL parameters, while the device filter belongs in the JSON body:

curl --silent --show-error -i --request POST \
  "https://${GATEWAY_HOST}/third-center-web/openapi/v1/phamboxOrder/queryOrderList?current=1&size=10" \
  --header 'Content-Type: application/json' \
  --header 'X-Locale: en' \
  --header "third-api-token: ${ACCESS_TOKEN}" \
  --data-raw '{"deviceCode":"DEVICE_CODE_FROM_DEVICE_LIST","includeHistory":false}'

Require code: 200 and read data.records, not data.list. Each request queries one device within the current scope.

• includeHistory: false queries current orders. Set it to true if you also need archived historical orders.
• Empty records can mean that the device has no matching orders; it is not by itself an authentication failure. Confirm the device and history setting. If there is no order, skip step 6.
• Use current, size and total to page through results as in step 4.
• Select a record with a non-empty tradeNo. This field is the external trade number and becomes tradeNoOut in the detail request. orderId is not a trade number.

6. Read the selected order's detail

Use the selected record's external trade number with Order detail:

curl --silent --show-error -i --request POST \
  "https://${GATEWAY_HOST}/third-center-web/openapi/v1/phamboxOrder/orderDetail" \
  --header 'Content-Type: application/json' \
  --header 'X-Locale: en' \
  --header "third-api-token: ${ACCESS_TOKEN}" \
  --data-raw '{"tradeNoOut":"TRADE_NO_FROM_ORDER_LIST"}'

Alternatively, provide tradeNoIn if the platform has supplied the internal trade number. At least one of tradeNoIn or tradeNoOut must be non-empty. Keep the same Group selected while fetching the detail.

Require code: 200 and non-null data before reading fields. An unknown trade number is a business error. Check that data.deviceCode matches the device you selected. The detail response uses detailList for line items; order-list records use detailVOList.

Read the order's currency; order amounts are integer minor units (for USD, 1299 means $12.99). Fields such as cardNumber, phone and shipment error descriptions may be null.

7. End the session and handle renewal

After finishing this walkthrough, call Log out using the latest token. No request body is required:

curl --silent --show-error -i --request POST \
  "https://${GATEWAY_HOST}/polarstar-auth/auth/third-api/logout" \
  --header 'Content-Type: application/json' \
  --header 'X-Locale: en' \
  --header "third-api-token: ${ACCESS_TOKEN}"

Successful logout returns code: 200 with data: null. Clear the saved token. In a running integration, reuse the token until renewal is needed; do not log in and out for every device request. After logging in again, recheck the selected Group before resuming, since login applies the default Group selection again.

Troubleshooting your first request

Always check both HTTP status and JSON code. A business failure can arrive with HTTP 200 and data: null; do not continue the workflow with missing IDs or a missing token.

Symptom	Check next
Login reports incorrect credentials	Use Login Name and the original account password; do not send a pre-hashed password
API access is not enabled	Ask your API contact to enable Third Party API Login for the account
No Group is assigned	Ask your API contact to assign an active Group
Invalid or expired token (code: -4)	Check the raw third-api-token header, expiry, and whether another process logged in or logged out with the same account; coordinate a fresh login and restore the intended Group
Group or device permission error	Choose a Group from switchableGroups and a device returned by its device list
Empty device or order page	Check the selected Group, assigned devices, filters, pagination and the order history setting
HTTP 404 or an HTML response	Check the gateway value, exactly one /v8, service path and HTTP method

See the endpoint pages for full field descriptions and the Overview for common headers and error handling.