Authentication

Devices

Device Object

Device Configuration Fields

Latest Status Fields

Optional Telemetry Groups

Device Statuses

Status Fields

Snapshots

Snapshot Fields

Complex Query Notes

• For route playback, request a bounded time range and paginate with offset and limit.
• Use get_pre_snapshot=1 when drawing a route line and the first visible segment needs the previous point.
• Use need_get_geo=1 only when geofence events must be mixed into the route result.
• Use alarm_codes only after confirming the packed alarm-code format in the Alarm Points section.

Alarm Points

Event / Alarm Code Definitions

The following values are used by fields such as alarm_code, alarm_codes, and realtime event payloads. Use the numeric code in API filters or comparisons; the hexadecimal value is provided as an equivalent reference for developers.

Using alarm_codes Filters

The alarm_codes query parameter accepts comma-separated numeric mask positions. For most integrations, it is simpler to query by device and time range, then classify returned points[].code values with the table above.

When server-side alarm filtering is required, build the mask from decimal code values:

Input Alarm Codes

Input alarms use the 0x02000000 group. Input n ON uses bit 2 * (n - 1); input n OFF uses bit 2 * (n - 1) + 1. Example: input 1 ON is 33554433, input 1 OFF is 33554434.

Alarm Policies

Alarm policies define which alarm event types are enabled for devices and how matching alarm notifications are handled. Use this API to create policy names, select alarm codes, assign devices, set active time windows, and control email/web/app delivery switches. Use /v2/alarm-points to query stored alarm records, and use Realtime Push to receive live alarm events.

What Alarm Policies Control

Request Fields

Response Fields

Building codes

codes is a grouped bitmask array. Build it from the public event code value in the Event / Alarm Code Definitions table.

// Enable SOS (16), Over Speed (32), and Over Speed in Geofence
// (67112960 / 0x04001000). Initialize unused groups as 0.
var codes = [0, 0, 0, 0, 0];
codes[0] = codes[0] | 16 | 32; // 48
codes[4] = codes[4] | 0x001000; // 4096

// Send codes as: [48, 0, 0, 0, 4096]

Examples

Create a policy that enables SOS and Over Speed:

POST /v2/alarm-policies?access-token=ACCESS_TOKEN
Content-Type: application/json

{
  "sname": "High Priority",
  "codes": [48],
  "towed": 200,
  "vibration": 8
}

Assign devices to the policy:

PUT /v2/alarm-policies?access-token=ACCESS_TOKEN
Content-Type: application/json

{
  "opr_sname": "High Priority",
  "devices": ["862000000000001", "862000000000002"]
}

Make the policy active only on weekdays from 08:00 to 18:00 in UTC+8:

PUT /v2/alarm-policies?access-token=ACCESS_TOKEN
Content-Type: application/json

{
  "opr_sname": "High Priority",
  "jsondates": "[[],[[28800,64800]],[[28800,64800]],[[28800,64800]],[[28800,64800]],[[28800,64800]],[]]",
  "time_zone": 8
}

The jsondates value is a 7-day array from Sunday to Saturday. Each day contains zero or more [startSecond,endSecond] ranges, counted from local midnight.

Disable web notification delivery for this policy while keeping other policy settings unchanged:

PUT /v2/alarm-policies?access-token=ACCESS_TOKEN
Content-Type: application/json

{
  "opr_sname": "High Priority",
  "not_send_web": 1
}

Delete a policy:

DELETE /v2/alarm-policies?access-token=ACCESS_TOKEN
Content-Type: application/json

{
  "opr_sname": "High Priority"
}

Smart Locks

Smart lock support has two parts: remote unlock commands and the status/events that confirm whether a lock is open or closed. Open API v2 exposes unlock commands for supported main locks and sub-locks. Lock/close state is reported by device status, realtime push, and alarm records.

Unlock Main Lock

POST /v2/device-lock-cards/action?access-token=ACCESS_TOKEN
Content-Type: application/json

{
  "openLock": {
    "imei": "API_DEVICE_IDENTIFIER"
  }
}

Unlock Sub-lock

POST /v2/device-lock-cards/action?access-token=ACCESS_TOKEN
Content-Type: application/json

{
  "openSubLock": {
    "imei": "API_DEVICE_IDENTIFIER",
    "ble_id": "SUB_LOCK_BLE_ID",
    "pwd": "MD5_PASSWORD_SUBSTRING_8_24"
  }
}

Command Response

Main Lock Status

Main lock state is returned in status.lock_status on device/status responses and in realtime snapshot or onlyUpdateEvent messages when the field changes.

Sub-lock Status

Sub-lock state is returned by GET /v2/devices as status.sub_lock_json_str, a JSON string that clients should parse into an array. Realtime updates are delivered as subLockInfo; merge each item by ble_id.

Lock Status Codes

Related Alarm Names

Use GET /v2/alarm-points or notification push to build an audit trail of lock activity. The following public alarm names identify the lock meaning without exposing internal constants.

Recommended State Flow

1. Load devices with GET /v2/devices and parse status.lock_status and status.sub_lock_json_str when present.
2. For remote unlock, send openLock or openSubLock only after the operator confirms the target device and lock.
3. Update the UI from realtime snapshot, onlyUpdateEvent, and subLockInfo messages. Use GET /v2/device-statuses or GET /v2/devices after reconnect.
4. Use GET /v2/alarm-points to show lock/open/close history and error recovery in reports.

BLE Sensors

BLE accessories are reported as child sensor data under a parent tracker. Use the tracker API device identifier returned as devices[].imei as the parent key. The customer-visible device_key may look like an IMEI in Monitor, but it is not the default value for Open API parameters named imei.

BLE Tire Pressure

BLE tire pressure integrations usually need two datasets: the latest sensor readings and the tire sensor binding table. The reading list tells you what the sensor reported; the binding table tells you which tire slot/name that sensor belongs to.

PUT https://openapi.tftiot.com/v2/tire-ble-mac?access-token=ACCESS_TOKEN
{
  "imei": "API_DEVICE_IDENTIFIER",
  "device_type": 0,
  "id1": 123,
  "mac1": "A1B2C3D4E5F6",
  "name1": "Front Left",
  "mac2": "A1B2C3D4E5F7",
  "name2": "Front Right"
}

Current tire readings

Read current values from devices[].status.ble_tire_pressure_list or device-statuses[].status.ble_tire_pressure_list. Merge each reading with the binding list by imei and mac.

{
  "code": 0,
  "device-statuses": [
    {
      "imei": "API_DEVICE_IDENTIFIER",
      "status": {
        "ble_tire_pressure_list": [
          {
            "mac": "A1B2C3D4E5F6",
            "date": 1700000000000,
            "airPressure": 245,
            "airTemp": 28,
            "voltage": 2.92,
            "alarm": 0
          }
        ]
      }
    }
  ]
}

Recommended tire display flow

1. Load tracker list with GET /v2/devices and use devices[].imei as the parent key.
2. Load bindings with GET /v2/tire-ble-mac, then keep only rows where device_type=0.
3. Read current values from status.ble_tire_pressure_list or realtime bleTire.
4. Merge by mac, render the configured name/position, and show missing readings as offline or unavailable.
5. Use GET /v2/alarm-points to show Tire Leak or TPS Low Battery history.

BLE Temperature / Humidity

BLE temperature/humidity integrations also separate current readings from configured sensor identity. In REST status responses, the current reading list is returned as a JSON string; parse it before using the values.

POST https://openapi.tftiot.com/v2/device-ble-temps?access-token=ACCESS_TOKEN
{
  "imei": "API_DEVICE_IDENTIFIER",
  "ble_ids": ["A1B2C3D4"]
}

PUT https://openapi.tftiot.com/v2/device-ble-temps?access-token=ACCESS_TOKEN
{
  "imei": "API_DEVICE_IDENTIFIER",
  "old_ble_id": "A1B2C3D4",
  "new_ble_id": "A1B2C3D4",
  "name": "Cargo Box",
  "high_temp": 8,
  "low_temp": 2,
  "high_humidity": 80,
  "low_humidity": 20
}

Current temperature/humidity readings

REST status responses return status.ble_temp_jsonarray_str as a JSON string. If it is empty, missing, or invalid, treat the current sensor list as empty. Realtime bleTemp messages return the same kind of readings as an array named ble_temp_list.

const list = status.ble_temp_jsonarray_str
  ? JSON.parse(status.ble_temp_jsonarray_str)
  : [];

// Example parsed item
{
  "ble_id": "A1B2C3D4",
  "date": 1700000000000,
  "temp": 4.8,
  "humidity": 62,
  "battery_percent": 91,
  "light_intensity": 1,
  "rssi": -63
}

Relevant alarm names

Use the Event / Alarm Code Definitions table above for numeric values. The BLE temperature/humidity names most commonly used by integrations are BLE Temperature High, BLE Temperature Low, BLE Temperature Recover, BLE Humidity High, BLE Humidity Low, and BLE Humidity Recover.

Recommended temperature/humidity display flow

1. Load configured sensors with GET /v2/device-ble-temps?imei=API_DEVICE_IDENTIFIER.
2. Read current values from status.ble_temp_jsonarray_str, parse the JSON string, and merge readings by ble_id.
3. Use realtime bleTemp to update the same sensor list without high-frequency polling.
4. After WebSocket reconnect or page reload, refresh with GET /v2/device-statuses and parse ble_temp_jsonarray_str again.
5. Use GET /v2/alarm-points for temperature/humidity alarm history.

Geofences

Geometry Examples

Coordinates use latitude and longitude decimal degrees. A polygon requires at least three points, encoded as lat,lng,lat,lng,....

{
  "name": "Warehouse Area",
  "type": 2,
  "form_type": 0,
  "polygon": "22.5199,113.9190,22.5209,113.9190,22.5209,113.9200"
}

A circle uses the center point in polygon and the radius in meters.

{
  "name": "Office Radius",
  "type": 2,
  "form_type": 1,
  "polygon": "22.5199,113.9190",
  "radius": 500
}

Overspeed In Geofence

When over_speed_enable=1 and over_speed is set, supported devices can report geofence overspeed code 67112960 while inside the geofence.