Getting Started

This page describes the common request rules for Open API v2: authentication, token use, retries, timestamps, coordinates, and rate-limit handling.

Base URLhttps://openapi.tftiot.com/v2/

Authentication Flow

Send a JSON body to POST /v2/auth/action with the getAccessToken action.

curl -X POST "https://openapi.tftiot.com/v2/auth/action" \
  -H "Content-Type: application/json" \
  -d '{
    "getAccessToken": {
      "account": "YOUR_ACCOUNT",
      "password-md5": "MD5_OF_PASSWORD",
      "client-type": "web",
      "client-id": "your-client-id"
    }
  }'

Field	Required	Description
`account`	Yes	Monitor account name.
`password-md5`	Yes	MD5 hash of the account password.
`client-type`	Recommended	Client category, for example `web` or `server`.
`client-id`	Recommended	Stable identifier for the calling client.

Device Identifiers

Many Open API v2 endpoints use a parameter or field named imei. In this documentation, imei means the API device identifier returned by GET /v2/devices as devices[].imei.

The Monitor web platform may display device_key as the customer-visible device number. That value can look like an IMEI to users, but Open API requests that require imei should use devices[].imei, not device_key, unless an endpoint explicitly documents otherwise.

Field	How to use it
`imei`	API device identifier. Use this value in request paths, query parameters, realtime messages, and request bodies named `imei`, `imeis`, or `devices`.
`device_key`	Customer-visible device number shown in the Monitor platform when available. Use it for display, search, or mapping in your own UI; do not use it as the Open API `imei` parameter unless specifically documented.
`config.name`	Device display name or alias. Use it for UI labels only.

GET /v2/devices?access-token=ACCESS_TOKEN

{
  "code": 0,
  "devices": [
    {
      "imei": "API_DEVICE_IDENTIFIER",
      "device_key": "CUSTOMER_VISIBLE_DEVICE_NUMBER",
      "config": {
        "name": "Vehicle A"
      }
    }
  ]
}

Token Use and Refresh

Use the returned access-token on authenticated v2 requests.

GET https://openapi.tftiot.com/v2/devices?limit=50&offset=0&access-token=ACCESS_TOKEN

If the API returns HTTP 403 with Invalid access-token., request a new token and retry the original request once. Avoid infinite retry loops.

Quick Test with Postman

Use the Postman Quick Test Kit to verify authentication, device access, current status, BLE sensor configuration reads, historical snapshots, alarm records, alarm policies, smart lock status/commands, and geofences before writing integration code. The kit is intentionally limited to Open API v2 and does not include old or internal endpoints.

Download: Monitor Open API v2 Postman Quick Test Kit (.zip)

Step	Action
1	Download and unzip the kit.
2	Import `monitor-openapi-v2.postman_collection.json` and `monitor-openapi-v2.postman_environment.json` into Postman.
3	Select the `Monitor Open API v2 Environment`.
4	Fill `account`, `password_md5`, and `api_imei`. The `api_imei` value comes from `GET /v2/devices` response field `devices[].imei`.
5	Run `Auth / Get Access Token`. The test script saves `access_token` and `user_id` from the response.
6	Run `Read-only Quick Test / List Devices`. If needed, copy `devices[].imei` into `api_imei` and use `device_key` only as a display/reference value.
7	Run the other read-only requests, such as `Get Device Statuses`, `Get Tire BLE Sensor Bindings`, `Get BLE Temperature/Humidity Sensors`, `Get Snapshots`, and `Get Alarm Points`.
8	Run smart lock write examples only on a confirmed test device. Use `Get Device by API IMEI` and realtime push to confirm lock status instead of looking for a close-lock command.

Included Requests

Folder	Requests	Purpose
Auth	`POST /v2/auth/action`	Get an access token and save it into the Postman environment.
Read-only Quick Test	`GET /v2/devices`, `GET /v2/devices/{imei}`, `GET /v2/device-statuses`, `GET /v2/tire-ble-mac`, `GET /v2/device-ble-temps`, `GET /v2/snapshots`, `GET /v2/alarm-points`, `GET /v2/alarm-policies`, `GET /v2/geofences`	Confirm account permissions, device data, status refresh, BLE sensor bindings, history, alarms, policies, and geofences. Requests that contain `{imei}` or `imei=` use the environment variable `api_imei`.
Write Examples – Use Carefully	`POST/PUT/DELETE /v2/alarm-policies`, `POST/PUT/DELETE /v2/geofences`, `POST /v2/device-lock-cards/action`	Create, update, delete, or send unlock commands only after confirming the target account, API device identifier, policy, geofence, and lock accessory. Smart lock close/lock state is verified from returned status and realtime events.

Environment Variables

Variable	Description
`base_url`	Default is `https://openapi.tftiot.com/v2`.
`account`	Monitor account name used for authentication.
`password_md5`	MD5 hash of the account password. The kit does not require storing the plain-text password.
`access_token`	Saved automatically after a successful auth request.
`user_id`	Saved automatically from the auth response. This is useful when testing realtime sign-in separately.
`api_imei`	API device identifier copied from `GET /v2/devices` response field `devices[].imei`. Use this for Open API parameters named `imei`.
`device_key`	Optional customer-visible device number for your own reference or UI mapping. Do not use it as `imei` unless an endpoint explicitly documents support for it.
`from_ms`, `to_ms`	Unix epoch milliseconds for snapshot and alarm queries. If empty, the collection fills a last-24-hours range for those requests.
`policy_name`, `geofence_name`, `geofence_id`	Used by alarm policy and geofence write examples.
`sub_lock_ble_id`, `sub_lock_password_md5_16`	Used only by the sub-lock unlock example. `sub_lock_password_md5_16` is `MD5(password).substring(8, 24)`.

Postman is for manual verification and onboarding. Do not use Collection Runner for high-frequency polling, load testing, or scheduled production traffic. For realtime device updates, follow the Realtime Push section instead of polling repeatedly.

Request Guidelines

Use limit and offset for large device, snapshot, or alarm result sets.
Keep refresh intervals reasonable. High-frequency polling from the same source IP can hit rate limits.
For large time ranges, query historical data in pages or smaller time windows.
When a response has code other than 0, read msg, i18nMsg, and param when present.

Time and Coordinates

Data	Rule
Request time range	`from_date` and `to_date` use Unix epoch milliseconds.
Response timestamps	Fields such as `keep-time`, `status.date`, `snapshot.date`, and `alarm time` are milliseconds.
Coordinates	Latitude and longitude are decimal degrees.
GPS validity	Use `latlng_valid` before treating a point as a reliable GPS location.