tracksolid_timescale_grafana_prod/tracksolidApiDocumentation.md

# Tracksolid Pro API Documentation

> Consolidated from official Jimi IoT documentation at [tracksolidprodocs.jimicloud.com](https://tracksolidprodocs.jimicloud.com/) and [docs.jimicloud.com](https://docs.jimicloud.com/integration/integration.html).
>
> API Spec Version: 2.7.7 | Last updated: 2026-04-11

---

## Table of Contents

1. [Overview](#1-overview)
2. [Authentication & Signing](#2-authentication--signing)
3. [Access Control](#3-access-control)
4. [Device Management](#4-device-management)
5. [Tracking & Telemetry](#5-tracking--telemetry)
6. [Alarms](#6-alarms)
7. [Media](#7-media)
8. [Command Management](#8-command-management)
9. [Geofencing](#9-geofencing)
10. [Data Push API (Webhooks)](#10-data-push-api-webhooks)

---

## 1. Overview

### Architecture

Your application server connects to the Jimi API server — client apps should never call the API directly. You must apply for an `appKey` and `appSecret` from Jimi (providing your account), then use your server to obtain an `access_token` and call other interfaces.

### Conventions

- Encoding: UTF-8
- Format: JSON (`application/json charset=utf-8`)
- Timezone: UTC (GMT+0)
- Timestamp format: `yyyy-MM-dd HH:mm:ss`
- All requests use POST to a single base URL with the `method` parameter to differentiate endpoints

### Regional Base URLs

| Region | Base URL |
|---|---|
| TrackSolid (TS) | `http://open.10000track.com/route/rest` |
| TSP Hong Kong / Singapore | `https://hk-open.tracksolidpro.com/route/rest` |
| TSP Europe | `https://eu-open.tracksolidpro.com/route/rest` |
| TSP United States | `https://us-open.tracksolidpro.com/route/rest` |

### Common Request Parameters

Every API call includes these base parameters:

| Parameter | Type | Required | Description |
|---|---|---|---|
| `method` | string | Yes | API method identifier (e.g. `jimi.oauth.token.get`) |
| `app_key` | string | Yes | Application key assigned by Jimi |
| `timestamp` | string | Yes | Current UTC time (`yyyy-MM-dd HH:mm:ss`) |
| `sign_method` | string | Yes | Always `md5` |
| `sign` | string | Yes | MD5 signature (see [Signing](#2-authentication--signing)) |
| `v` | string | Yes | API version, always `1.0` |
| `format` | string | Yes | Always `json` |
| `access_token` | string | Conditional | Required for all methods except token acquisition |

### Common Response Structure

```json
{
  "code": 0,
  "message": "success",
  "result": { }
}
```

| Code | Meaning |
|---|---|
| `0` | Success |
| `1004` | Token expired — refresh or re-authenticate |
| `1006` | Rate limit exceeded — back off and retry |
| `-1` | General error |

### Rate Limits

- Token acquisition (`jimi.oauth.token.get`) can be called **at most once per minute**
- `jimi.device.alarm.list` — time range limited to **1 month**, max **1000 rows** returned
- Batch endpoints accept up to **50 IMEIs** per call
- `jimi.device.track.list` — per-device endpoint (no batch); each call can be slow (~137s observed in production for a 35-minute lookback). Do not call synchronously inside a 60s scheduler loop; run on a dedicated 30-minute schedule.

---

## 2. Authentication & Signing

### MD5 Signature Algorithm

Every API call requires a signature to prevent tampering. The algorithm:

1. Collect all request parameters (excluding `sign` and any with `null` values)
2. Sort parameters alphabetically by key
3. Concatenate as: `{appSecret}{key1}{value1}{key2}{value2}...{appSecret}`
4. Compute MD5 hash of the UTF-8 encoded string
5. Convert to uppercase hex

Example:
```
Input:  SECRET + "app_keyABC123methodjimi.oauth.token.gettimestamp2025-01-01 00:00:00" + SECRET
Output: MD5 → uppercase hex string
```

---

## 3. Access Control

### 3.1 Get Access Token

Obtain an authentication token for API access.

| | |
|---|---|
| **Method** | `jimi.oauth.token.get` |
| **Auth required** | No (this obtains the token) |
| **Rate limit** | Max 1 call per minute |

**Parameters:**

| Parameter | Type | Required | Description |
|---|---|---|---|
| `user_id` | string | Yes | Account user ID |
| `user_pwd_md5` | string | Yes | MD5 hash of user password |
| `expires_in` | int | Yes | Token lifetime in seconds (e.g. `7200` for 2 hours) |

**Response:**

| Field | Type | Description |
|---|---|---|
| `accessToken` | string | The access token for subsequent API calls |
| `expiresIn` | int | Token lifetime in seconds |
| `account` | string | Account identifier |
| `appKey` | string | Application key |
| `refreshToken` | string | Token used to refresh before expiry |
| `time` | string | Server time |

---

### 3.2 Refresh Access Token

Update token before it expires without full re-authentication.

| | |
|---|---|
| **Method** | `jimi.oauth.token.refresh` |
| **Auth required** | Yes |

**Parameters:**

| Parameter | Type | Required | Description |
|---|---|---|---|
| `access_token` | string | Yes | Current access token |
| `refresh_token` | string | Yes | Refresh token from initial auth |
| `expires_in` | int | Yes | New token lifetime in seconds |

**Response:** Same as `jimi.oauth.token.get`.

---

## 4. Device Management

### 4.1 List All Devices

Retrieve all devices belonging to a specified account.

| | |
|---|---|
| **Method** | `jimi.user.device.list` |
| **Auth required** | Yes |

**Parameters:**

| Parameter | Type | Required | Description |
|---|---|---|---|
| `target` | string | Yes | Target account ID |

**Response (array):**

| Field | Type | Description |
|---|---|---|
| `imei` | string | Device IMEI |
| `deviceName` | string | Device display name |
| `mcType` | string | Device model type |
| `sim` | string | SIM card number |
| `expiration` | string | Service expiration date |
| `activationTime` | string | Device activation date |
| `vehicleName` | string | Assigned vehicle name |
| `vehicleNumber` | string | License plate / vehicle number |
| `driverName` | string | Assigned driver name |
| `enabledFlag` | int | 1 = enabled, 0 = disabled |

---

### 4.2 Get Device Detail

Retrieve comprehensive information for a specific IMEI.

| | |
|---|---|
| **Method** | `jimi.track.device.detail` |
| **Auth required** | Yes |

**Parameters:**

| Parameter | Type | Required | Description |
|---|---|---|---|
| `imei` | string | Yes | Device IMEI |

**Response:**

| Field | Type | Description |
|---|---|---|
| `imei` | string | Device IMEI |
| `deviceName` | string | Device name |
| `account` | string | Owner account |
| `mcType` | string | Model type |
| `sim` | string | SIM number |
| `expiration` | string | Service expiration |
| `vehicleName` | string | Vehicle name |
| `currentMileage` | number | Odometer reading |
| `deviceGroup` | string | Group name |

---

### 4.3 Update Device Expiration

Modify device expiration dates.

| | |
|---|---|
| **Method** | `jimi.user.device.expiration.update` |
| **Auth required** | Yes |

**Parameters:**

| Parameter | Type | Required | Description |
|---|---|---|---|
| `imei_list` | string | Yes | Comma-separated IMEIs |
| `new_expiration` | string | Yes | New expiration date |

**Response:**

| Field | Type | Description |
|---|---|---|
| `imei` | string | Device IMEI |
| `update_result` | string | Result status |
| `update_msg` | string | Result message |

---

### 4.4 Update Vehicle Information by IMEI

Update vehicle details and device settings.

| | |
|---|---|
| **Method** | `jimi.open.device.update` |
| **Auth required** | Yes |

**Parameters:**

| Parameter | Type | Required | Description |
|---|---|---|---|
| `imei` | string | Yes | Device IMEI |
| `device_name` | string | No | Device display name |
| `vehicle_name` | string | No | Vehicle name |
| `vehicle_icon` | string | No | Vehicle icon identifier |
| `vehicle_number` | string | No | License plate |
| `driver_name` | string | No | Driver name |
| `driver_phone` | string | No | Driver phone |
| `device_status` | string | No | Device status |
| `sim` | string | No | SIM card number |
| `remarks` | string | No | Notes |
| `mileage` | number | No | Current mileage |

**Response:** Success confirmation (code 0).

---

### 4.5 Move Devices Between Accounts

Transfer devices between sub-accounts.

| | |
|---|---|
| **Method** | `jimi.open.device.move` |
| **Auth required** | Yes |

**Parameters:**

| Parameter | Type | Required | Description |
|---|---|---|---|
| `src_account` | string | Yes | Source account |
| `dest_account` | string | Yes | Destination account |
| `imeis` | string | Yes | Comma-separated IMEIs |
| `cleanBindFlag` | boolean | No | Clear existing bindings |

**Response:**

| Field | Type | Description |
|---|---|---|
| `result` | array | Array of moved device IMEIs |

---

### 4.6 Bind App User

Associate device with a mobile application user.

| | |
|---|---|
| **Method** | `jimi.open.device.bind` |
| **Auth required** | Yes |

**Parameters:**

| Parameter | Type | Required | Description |
|---|---|---|---|
| `imei` | string | Yes | Device IMEI |
| `user_id` | string | Yes | App user ID |

---

### 4.7 Unbind App User

Remove device association from a mobile application user.

| | |
|---|---|
| **Method** | `jimi.open.device.unbind` |
| **Auth required** | Yes |

**Parameters:**

| Parameter | Type | Required | Description |
|---|---|---|---|
| `imei` | string | Yes | Device IMEI |
| `user_id` | string | Yes | App user ID |

---

### 4.8 Create Device Group

| | |
|---|---|
| **Method** | `jimi.device.group.create` |
| **Auth required** | Yes |

**Parameters:**

| Parameter | Type | Required | Description |
|---|---|---|---|
| `account` | string | Yes | Account ID |
| `group_name` | string | Yes | Group name |

**Response:**

| Field | Type | Description |
|---|---|---|
| `group_id` | string | Created group ID |
| `group_name` | string | Group name |

---

### 4.9 Edit Device Group

| | |
|---|---|
| **Method** | `jimi.device.group.update` |
| **Auth required** | Yes |

**Parameters:**

| Parameter | Type | Required | Description |
|---|---|---|---|
| `group_id` | string | Yes | Group ID to edit |
| `group_name` | string | Yes | New group name |

---

### 4.10 Delete Device Group

| | |
|---|---|
| **Method** | `jimi.device.group.delete` |
| **Auth required** | Yes |

**Parameters:**

| Parameter | Type | Required | Description |
|---|---|---|---|
| `group_id` | string | Yes | Group ID to delete |

---

### 4.11 List Device Groups

| | |
|---|---|
| **Method** | `jimi.device.group.list` |
| **Auth required** | Yes |

**Parameters:**

| Parameter | Type | Required | Description |
|---|---|---|---|
| `account` | string | Yes | Account ID |

**Response (array):**

| Field | Type | Description |
|---|---|---|
| `group_id` | string | Group identifier |
| `group_name` | string | Group display name |

---

## 5. Tracking & Telemetry

### 5.1 Get Location of Devices by Account

Retrieve latest positions for all devices under an account. Single API call for entire fleet.

| | |
|---|---|
| **Method** | `jimi.user.device.location.list` |
| **Auth required** | Yes |

**Parameters:**

| Parameter | Type | Required | Description |
|---|---|---|---|
| `target` | string | Yes | Target account ID |
| `map_type` | string | No | Coordinate system (e.g. `GOOGLE`) |

**Response (array):**

| Field | Type | Description |
|---|---|---|
| `imei` | string | Device IMEI |
| `deviceName` | string | Device name |
| `status` | string | Device status code |
| `lat` | double | Latitude |
| `lng` | double | Longitude |
| `speed` | number | Speed (km/h) |
| `direction` | number | Heading (0–360 degrees) |
| `gpsTime` | string | GPS fix timestamp |
| `hbTime` | string | Heartbeat/server receive time |
| `accStatus` | string | ACC ignition status (`0`=off, `1`=on) |
| `gpsSignal` | int | GPS signal quality (0–4) |
| `gpsNum` | int | Satellites used |
| `currentMileage` | number | Odometer reading |
| `powerValue` | number | External power voltage |
| `elecQuantity` | number | Battery percentage |
| `posType` | string | Position type |
| `confidence` | int | Position confidence score |
| `expireFlag` | string | Subscription expiration flag |
| `activationFlag` | string | Activation status |
| `locDesc` | string | Reverse-geocoded address (if available) |

> **Implementation note:** This is the fleet sweep endpoint called every 60 seconds. In production it returns ~19 active devices out of 63 queried, averaging ~200ms per call. Devices without a current position are silently omitted from the response — they are not returned with null coordinates.

---

### 5.2 Get Location of Specific Device(s)

Fetch current position for one or multiple specific devices.

| | |
|---|---|
| **Method** | `jimi.device.location.get` |
| **Auth required** | Yes |

**Parameters:**

| Parameter | Type | Required | Description |
|---|---|---|---|
| `imeis` | string | Yes | Comma-separated IMEI list |
| `map_type` | string | No | Coordinate system |

**Response (array):**

| Field | Type | Description |
|---|---|---|
| `imei` | string | Device IMEI |
| `deviceName` | string | Device name |
| `lat` | double | Latitude |
| `lng` | double | Longitude |
| `status` | string | Device status |
| `speed` | number | Speed (km/h) |
| `gpsTime` | string | GPS fix timestamp |
| `accStatus` | string | ACC ignition status |
| `currentMileage` | number | Odometer |

---

### 5.3 Get Sharing Location URL

Generate a shareable map link for device location display.

| | |
|---|---|
| **Method** | `jimi.device.location.URL.share` |
| **Auth required** | Yes |

**Parameters:**

| Parameter | Type | Required | Description |
|---|---|---|---|
| `imei` | string | Yes | Device IMEI |

**Response:**

| Field | Type | Description |
|---|---|---|
| `URL` | string | Shareable map URL |

---

### 5.4 Get Mileage / Trip Data

Extract trip and distance records within a time period. Supports batching up to 50 IMEIs.

| | |
|---|---|
| **Method** | `jimi.device.track.mileage` |
| **Auth required** | Yes |

**Parameters:**

| Parameter | Type | Required | Description |
|---|---|---|---|
| `imeis` | string | Yes | Comma-separated IMEI list (max 50) |
| `begin_time` | string | Yes | Start time (`yyyy-MM-dd HH:mm:ss`) |
| `end_time` | string | Yes | End time (`yyyy-MM-dd HH:mm:ss`) |
| `start_row` | int | No | Pagination offset |
| `page_size` | int | No | Page size |

**Response (array):**

| Field | Type | Description |
|---|---|---|
| `imei` | string | Device IMEI |
| `startTime` | string | Trip start time |
| `endTime` | string | Trip end time |
| `distance` | number | Distance — **stored as kilometres in DB** (see note below) |
| `avgSpeed` | number | Average speed (km/h) — field name: `avgSpeed` |
| `maxSpeed` | number | Maximum speed (km/h) — field name: `maxSpeed` |
| `runTimeSecond` | int | Driving time (seconds) |
| `idleSecond` | int | Idle time (seconds) |

> **Distance unit note (BUG-02):** The raw `distance` value returned by this endpoint is in **kilometres** as labelled. However, the value was being stored incorrectly as millimetres due to an erroneous `× 1000` multiplication in earlier code. Migration 04 corrected all historical rows: `distance_km = stored_value / 1,000,000`. Current code stores `distance` directly as `distance_km` with no further conversion. The DB column was renamed from `distance_m` to `distance_km` to reflect this.
>
> **maxSpeed note (BUG-03):** `maxSpeed` was present in the API response but not mapped in `poll_trips()`. Fixed — now stored in `tracksolid.trips.max_speed_kmh`.

---

### 5.5 Get Track Data (GPS Trail)

Retrieve detailed positional waypoints for a specified timeframe. **Per-device** endpoint.

| | |
|---|---|
| **Method** | `jimi.device.track.list` |
| **Auth required** | Yes |

**Parameters:**

| Parameter | Type | Required | Description |
|---|---|---|---|
| `imei` | string | Yes | Single device IMEI |
| `begin_time` | string | Yes | Start time (`yyyy-MM-dd HH:mm:ss`) |
| `end_time` | string | Yes | End time (`yyyy-MM-dd HH:mm:ss`) |
| `map_type` | string | No | Coordinate system |

**Response (array):**

| Field | Type | Description |
|---|---|---|
| `lat` | double | Latitude |
| `lng` | double | Longitude |
| `gpsTime` | string | Timestamp of GPS fix |
| `gpsSpeed` | int | Speed (km/h) |
| `direction` | int | Heading (0–360 degrees) |
| `ignition` | string | Ignition state |
| `accStatus` | string | ACC status |
| `confidence` | int | Position confidence |
| `altitude` | int | Altitude (metres) — not populated by all device models |
| `satellite` | int | Satellite count |

> **Implementation note (POLL-01):** Called per-device every 30 minutes with a 35-minute lookback window. Results written to `tracksolid.position_history` with `source='track_list'` (vs `source='poll'` for the 60s sweep). Use `ON CONFLICT DO NOTHING` — duplicate fixes from overlapping windows are safely discarded. Observed: ~5–6 waypoints per active device per 30-min window. Altitude field is returned but not populated by X3 and GT06E devices in this fleet.

---

### 5.6 Wi-Fi / Base Station Locating

Determine position using cellular tower and wireless network signals (fallback when GPS unavailable).

| | |
|---|---|
| **Method** | `jimi.lbs.address.get` |
| **Auth required** | Yes |

**Parameters:**

| Parameter | Type | Required | Description |
|---|---|---|---|
| `imei` | string | Yes | Device IMEI |
| `lbs` | string | No | LBS data |
| `wifi` | string | No | WiFi data |

**Response:**

| Field | Type | Description |
|---|---|---|
| `lat` | double | Latitude |
| `lng` | double | Longitude |
| `accuracy` | number | Position accuracy (meters) |

---

### 5.7 Get Parking / Idling Data

Analyze stationary and engine-running periods.

| | |
|---|---|
| **Method** | `jimi.open.platform.report.parking` |
| **Auth required** | Yes |

**Parameters:**

| Parameter | Type | Required | Description |
|---|---|---|---|
| `account` | string | Yes | Account ID |
| `imeis` | string | Yes | Comma-separated IMEI list |
| `start_time` | string | Yes | Start time |
| `end_time` | string | Yes | End time |
| `start_row` | int | Yes | Pagination offset |
| `page_size` | int | Yes | Page size |
| `acc_type` | string | Yes | ACC filter: **`0`** = all stops, `1` = ignition-off only |

**Response (array):**

| Field | Type | Description |
|---|---|---|
| `imei` | string | Device IMEI |
| `startTime` | string | Parking/idle start |
| `endTime` | string | Parking/idle end |
| `durSecond` | int | Total duration (seconds) — **use this field for duration** |
| `stopSecond` | int | Stationary-only duration (seconds) — may be absent |
| `addr` | string | Address / location |
| `deviceName` | string | Device name |

> **Implementation note (POLL-02):** Pass `acc_type=0` to capture all stop events (not just ignition-off). If `acc_type` is omitted or set to an empty string the API returns 0 rows. The primary duration field is `durSecond`; `stopSecond` is a secondary field that may not be populated. In production: 60 calls logged, all successful, 0 rows — expected while fleet is overnight-parked. Will populate once vehicles complete a full stop–start–stop cycle.

---

### 5.8 Get Location of TAG Device

Query latest beacon/TAG positioning data.

| | |
|---|---|
| **Method** | `jimi.device.location.getTagMsg` |
| **Auth required** | Yes |

**Parameters:**

| Parameter | Type | Required | Description |
|---|---|---|---|
| `imei` | string | Yes | TAG device IMEI |

**Response:**

| Field | Type | Description |
|---|---|---|
| `lng` | double | Longitude |
| `lat` | double | Latitude |
| `gpsTime` | string | GPS timestamp |
| `gpsSpeed` | int | Speed |
| `positionType` | string | Position method |
| `gpsNum` | int | Satellite count |

---

## 6. Alarms

### 6.1 Get Device Alarm List

Retrieve alarm events for devices within a time range.

| | |
|---|---|
| **Method** | `jimi.device.alarm.list` |
| **Auth required** | Yes |
| **Constraints** | Time range max **1 month**, max **1000 rows** returned |

**Parameters:**

| Parameter | Type | Required | Description |
|---|---|---|---|
| `imeis` | string | Yes | Comma-separated IMEI list |
| `begin_time` | string | Yes | Start time (`yyyy-MM-dd HH:mm:ss`) |
| `end_time` | string | Yes | End time (`yyyy-MM-dd HH:mm:ss`) |
| `page_size` | int | No | Results per page (max 1000) |

**Response (array):**

| Field | Type | Description |
|---|---|---|
| `deviceName` | string | Device name |
| `imei` | string | Device IMEI |
| `model` | string | Device model |
| `account` | string | Account |
| `alertTypeId` | string | Alarm type identifier — **polling field name** |
| `alarmTypeName` | string | Alarm type display name — **polling field name** |
| `alertTime` | string | Alarm trigger time — **polling field name** |
| `positioningTime` | string | GPS fix time at alarm |
| `lat` | double | Latitude |
| `lng` | double | Longitude |
| `speed` | number | Speed at alarm time |
| `geoid` | string | Geo-fence ID (if geofence alarm) |

> **Critical field name difference — polling vs push (BUG-01):**
>
> | Data | Polling (`jimi.device.alarm.list`) | Push (`/pushalarm`) | DB column |
> |---|---|---|---|
> | Type ID | `alertTypeId` | `alarmType` | `alarm_type` |
> | Type name | `alarmTypeName` | `alarmName` | `alarm_name` |
> | Time | `alertTime` | `gateTime` | `alarm_time` |
>
> Earlier code used the push field names (`alarmType`, `alarmName`) in the polling path — these keys are never present in the polling response, so `alarm_type` and `alarm_name` were always NULL. Fixed in `ingest_events_rev.py` (FIX-E06): polling now maps `item.get('alertTypeId')` → `alarm_type` and `item.get('alarmTypeName')` → `alarm_name`. **Verified in production:** vibration alarms now store type `3` and name `"Vibration alert"` correctly.

---

## 7. Media

### 7.1 Get Device Live Streaming Page URL

Provides an embeddable URL for real-time video broadcast.

| | |
|---|---|
| **Method** | `jimi.device.live.page.url` |
| **Auth required** | Yes |

**Parameters:**

| Parameter | Type | Required | Description |
|---|---|---|---|
| `imei` | string | Yes | Device IMEI |
| `type` | string | No | Stream type |
| `voice` | string | No | Audio toggle |

**Response:**

| Field | Type | Description |
|---|---|---|
| `lat` | double | Device latitude |
| `lng` | double | Device longitude |
| `gpsTime` | string | GPS time |
| `VIN` | string | Vehicle VIN |
| `plateNo` | string | Plate number |
| `UrlCamera` | string | Embeddable streaming page URL |

---

### 7.2 Send Media Instruction (Capture Photo/Video)

Command a DVR device to capture video or still images on demand.

| | |
|---|---|
| **Method** | `jimi.device.meida.cmd.send` |
| **Auth required** | Yes |

**Parameters:**

| Parameter | Type | Required | Description |
|---|---|---|---|
| `imei` | string | Yes | Device IMEI |
| `camera` | int | Yes | Camera channel index |
| `mediaType` | string | Yes | `photo` or `video` |
| `shootTime` | int | No | Video recording duration (seconds) |

**Response:**

| Field | Type | Description |
|---|---|---|
| `code` | int | Result code |
| `msg` | string | Result message |
| `cmdSeqNo` | string | Command sequence number for tracking |

---

### 7.3 Send History Video Instruction

Command device to upload recorded video files from its storage.

| | |
|---|---|
| **Method** | `jimi.device.history.cmd.send` |
| **Auth required** | Yes |

**Parameters:**

| Parameter | Type | Required | Description |
|---|---|---|---|
| `imei` | string | Yes | Device IMEI |
| `type` | string | Yes | Upload type |
| `camera` | int | Yes | Camera channel |
| `fileName` | string | No | Specific file name |
| `time` | string | No | Time filter |

**Response:**

| Field | Type | Description |
|---|---|---|
| `code` | int | Result code |
| `msg` | string | Result message |
| `cmdSeqNo` | string | Command sequence number |

---

### 7.4 Get Device Photo/Video URL

Retrieve URLs for captured photos and video recordings.

| | |
|---|---|
| **Method** | `jimi.device.jimi.media.URL` |
| **Auth required** | Yes |

**Parameters:**

| Parameter | Type | Required | Description |
|---|---|---|---|
| `imei` | string | Yes | Device IMEI |
| `camera` | int | Yes | Camera channel |
| `media_type` | string | Yes | `photo` or `video` |
| `start_time` | string | No | Filter start time |
| `end_time` | string | No | Filter end time |
| `token` | string | No | Pagination token |
| `page_no` | int | No | Page number |
| `page_size` | int | No | Results per page |

**Response (array):**

| Field | Type | Description |
|---|---|---|
| `thumb_URL` | string | Thumbnail URL |
| `file_URL` | string | Full file download URL |
| `create_time` | string | Capture timestamp |
| `mime_type` | string | MIME type (`image/jpeg`, `video/mp4`, etc.) |
| `camera` | int | Camera channel |
| `file_size` | int | File size in bytes |

---

### 7.5 Get Device Media Event URL

Retrieve media files triggered by alarm events (hard braking, collision, etc.).

| | |
|---|---|
| **Method** | `jimi.device.media.event.URL` |
| **Auth required** | Yes |

**Parameters:**

| Parameter | Type | Required | Description |
|---|---|---|---|
| `imeis` | string | Yes | Comma-separated IMEI list |
| `media_type` | string | Yes | `photo` or `video` |
| `start_time` | string | Yes | Filter start time |
| `end_time` | string | Yes | Filter end time |
| `page_no` | int | Yes | Page number |
| `page_size` | int | Yes | Results per page |
| `event_type` | string | No | Filter by event type |

**Response (array):**

| Field | Type | Description |
|---|---|---|
| `imei` | string | Device IMEI |
| `event_type` | string | Alarm/event type |
| `lat` | double | Latitude at event |
| `lng` | double | Longitude at event |
| `alarm_time` | string | Event timestamp |
| `fileList` | array | Nested array of file objects (URLs, MIME types, sizes) |

---

### 7.6 Get Device Live Streaming Address

Obtain a streaming protocol address (RTSP/HLS) for real-time video.

| | |
|---|---|
| **Method** | `jimi.device.media.live.stream` |
| **Auth required** | Yes |

**Parameters:**

| Parameter | Type | Required | Description |
|---|---|---|---|
| `imei` | string | Yes | Device IMEI |
| `channel` | int | Yes | Camera channel (1-5) |
| `appId` | string | Yes | Application identifier |

**Response:**

| Field | Type | Description |
|---|---|---|
| `result` | string | Streaming URL |

---

### 7.7 Send Command to Query Historical Video List

Two-step process: first send this command to prompt the device to compile its stored video inventory.

| | |
|---|---|
| **Method** | `jimi.device.media.history.list.cmd` |
| **Auth required** | Yes |

**Parameters:**

| Parameter | Type | Required | Description |
|---|---|---|---|
| `imei` | string | Yes | Device IMEI |
| `channel` | int | Yes | Camera channel |
| `dateTime` | string | Yes | Target date/time |
| `instructionId` | string | Yes | Unique instruction identifier |
| `appId` | string | Yes | Application identifier |

**Response:** Acknowledgment only.

---

### 7.8 Query Historical Video List

Second step: retrieve the compiled video file metadata (after sending 7.7).

| | |
|---|---|
| **Method** | `jimi.device.media.history.list.get` |
| **Auth required** | Yes |

**Parameters:**

| Parameter | Type | Required | Description |
|---|---|---|---|
| `instructionId` | string | Yes | Same ID used in 7.7 |

**Response (array):**

| Field | Type | Description |
|---|---|---|
| `channel` | int | Camera channel |
| `beginTime` | string | Recording start time |
| `endTime` | string | Recording end time |
| `fileSize` | int | File size |
| `fileName` | string | File name |
| `codeType` | int | Encoding type (1=Main, 2=Sub) |

---

### 7.9 Get Historical Video Streaming Address

Generate a playback URL for recorded video segments.

| | |
|---|---|
| **Method** | `jimi.device.media.history.stream` |
| **Auth required** | Yes |

**Parameters:**

| Parameter | Type | Required | Description |
|---|---|---|---|
| `imei` | string | Yes | Device IMEI |
| `channel` | int | Yes | Camera channel |
| `appId` | string | Yes | Application identifier |
| `beginTime` | string | No | Playback start time |
| `endTime` | string | No | Playback end time |
| `fileNameList` | string | No | Specific file names |

**Response:**

| Field | Type | Description |
|---|---|---|
| `result` | string | Playback streaming URL |

---

### 7.10 Close Streaming

Terminate an active video streaming session to release resources.

| | |
|---|---|
| **Method** | `jimi.device.media.close.stream` |
| **Auth required** | Yes |

**Parameters:**

| Parameter | Type | Required | Description |
|---|---|---|---|
| `imei` | string | Yes | Device IMEI |
| `channel` | int | Yes | Camera channel |
| `type` | string | Yes | Stream type to close |
| `appId` | string | Yes | Application identifier |

---

## 8. Command Management

### 8.1 Get Command List Supported by Device

Retrieve available command templates for a target device model.

| | |
|---|---|
| **Method** | `jimi.open.instruction.list` |
| **Auth required** | Yes |

**Parameters:**

| Parameter | Type | Required | Description |
|---|---|---|---|
| `imei` | string | Yes | Device IMEI |

**Response (array):**

| Field | Type | Description |
|---|---|---|
| `id` | string | Command template ID |
| `orderName` | string | Command name |
| `orderContent` | string | Command template |
| `orderExplain` | string | Description |
| `isOffLine` | boolean | Supports offline delivery |

---

### 8.2 Send Command to Device

Transmit a formatted instruction with substituted parameters.

| | |
|---|---|
| **Method** | `jimi.open.instruction.send` |
| **Auth required** | Yes |

**Parameters:**

| Parameter | Type | Required | Description |
|---|---|---|---|
| `imei` | string | Yes | Device IMEI |
| `inst_param_json` | string | Yes | JSON-encoded command parameters |

---

### 8.3 Get Results of Command Execution

Retrieve execution status and device response for a sent command.

| | |
|---|---|
| **Method** | `jimi.open.instruction.result` |
| **Auth required** | Yes |

**Parameters:**

| Parameter | Type | Required | Description |
|---|---|---|---|
| `imei` | string | Yes | Device IMEI |

**Response (array):**

| Field | Type | Description |
|---|---|---|
| `codeId` | string | Command ID |
| `code` | string | Command code |
| `content` | string | Device response content |
| `isExecute` | boolean | Whether executed |
| `sendTime` | string | Send timestamp |
| `sender` | string | Who sent |
| `receiveDevice` | string | Target device |

---

### 8.4 Send Raw Command Data

Transmit hexadecimal command directly to device (advanced usage).

| | |
|---|---|
| **Method** | `jimi.open.instruction.raw.send` |
| **Auth required** | Yes |

**Parameters:**

| Parameter | Type | Required | Description |
|---|---|---|---|
| `imei` | string | Yes | Device IMEI |
| `raw_cmd` | string | Yes | Hex-encoded command data |

---

## 9. Geofencing

### 9.1 Create Device Geo-fence

Establish a circular boundary alarm directly on the device.

| | |
|---|---|
| **Method** | `jimi.open.device.fence.create` |
| **Auth required** | Yes |

**Parameters:**

| Parameter | Type | Required | Description |
|---|---|---|---|
| `imei` | string | Yes | Device IMEI |
| `fence_name` | string | Yes | Fence display name |
| `alarm_type` | string | Yes | Alarm trigger type |
| `report_mode` | string | Yes | Reporting mode |
| `alarm_switch` | string | Yes | Enable/disable |
| `lng` | double | Yes | Center longitude |
| `lat` | double | Yes | Center latitude |
| `radius` | int | Yes | Radius in meters |
| `zoom_level` | int | Yes | Map zoom level |
| `map_type` | string | Yes | Map coordinate system |

**Response:**

| Field | Type | Description |
|---|---|---|
| `result` | string | Fence serial number |

---

### 9.2 Delete Device Geo-fence

| | |
|---|---|
| **Method** | `jimi.open.device.fence.delete` |
| **Auth required** | Yes |

**Parameters:**

| Parameter | Type | Required | Description |
|---|---|---|---|
| `imei` | string | Yes | Device IMEI |
| `instruct_no` | string | Yes | Fence serial number |

---

### 9.3 Create Platform Geo-fence

Establish a server-side boundary definition (supports polygons, circles, etc.).

| | |
|---|---|
| **Method** | `jimi.open.platform.fence.create` |
| **Auth required** | Yes |

**Parameters:**

| Parameter | Type | Required | Description |
|---|---|---|---|
| `account` | string | Yes | Account ID |
| `fence_name` | string | Yes | Fence name |
| `fence_type` | string | Yes | Geometry type |
| `geom` | string | Yes | Geometry definition (GeoJSON or WKT) |
| `fence_color` | string | No | Display color |
| `radius` | int | No | Radius (for circle type) |
| `description` | string | No | Description |

**Response:**

| Field | Type | Description |
|---|---|---|
| `data` | string | Created fence ID |

---

### 9.4 Delete Platform Geo-fence

| | |
|---|---|
| **Method** | `jimi.open.platform.fence.delete` |
| **Auth required** | Yes |

**Parameters:**

| Parameter | Type | Required | Description |
|---|---|---|---|
| `account` | string | Yes | Account ID |
| `fence_id` | string | Yes | Fence ID to delete |

---

### 9.5 Bind Devices to Platform Geo-fence

Associate devices with a server boundary and configure alert triggers.

| | |
|---|---|
| **Method** | `jimi.open.platform.fence.bind` |
| **Auth required** | Yes |

**Parameters:**

| Parameter | Type | Required | Description |
|---|---|---|---|
| `fence_id` | string | Yes | Fence ID |
| `imeis` | string | No | Comma-separated IMEIs |
| `alert_type` | string | No | Alert trigger (enter/exit/both) |
| `stay_time_in` | int | No | Dwell time threshold for entry (seconds) |
| `stay_time_out` | int | No | Dwell time threshold for exit (seconds) |

**Response:**

| Field | Type | Description |
|---|---|---|
| `data` | int | Count of related devices |

---

## 10. Data Push API (Webhooks)

The Data Push API is a **server-to-server push architecture** where Jimi's servers POST data to your HTTP endpoints. This is the primary mechanism for receiving real-time telemetry and the **only way** to receive certain data types (OBD, fault codes, heartbeat).

You must configure your callback URL in the Tracksolid Pro platform. All push endpoints use:
- **Method:** POST
- **Content-Type:** `application/x-www-form-urlencoded`
- **Common parameters:** `token` (string) and `data_list` (JSON string array, max 50 items per request)
- **Expected response:** `{"code": 0, "msg": "success"}`

---

### 10.1 Login/Logout Events

| Endpoint | `{YourURL}/pushevent` |
|---|---|
| **Handler** | `webhook_receiver_rev.py` — implemented (PUSH-01) |
| **DB table** | `tracksolid.device_events` |

**`data_list` fields:**

| Field | Type | Description |
|---|---|---|
| `deviceImei` | string | Device IMEI |
| `type` | string | `LOGIN` or `LOGOUT` |
| `gateTime` | string | Event time (`yyyy-MM-dd HH:mm:ss`) |
| `timezone` | string | Device timezone (e.g. `GMT+08:00`) |

---

### 10.2 Heartbeat Data

| Endpoint | `{YourURL}/pushhb` |
|---|---|
| **Handler** | Not yet implemented — DB table `tracksolid.heartbeats` exists and is ready |

**`data_list` fields (max 50 per request):**

| Field | Type | Description |
|---|---|---|
| `deviceImei` | string | Device IMEI |
| `gateTime` | string | Heartbeat time |
| `powerLevel` | int | Battery percentage |
| `gsmSign` | int | GSM signal strength |
| `acc` | int | ACC status (0=OFF, 1=ON) |
| `powerStatus` | int | 0=Not charging, 1=Charging |
| `fortify` | int | Defense/fortify status |

---

### 10.3 GPS Data

| Endpoint | `{YourURL}/pushgps` |
|---|---|

**`data_list` fields (max 50 per request):**

| Field | Type | Description |
|---|---|---|
| `deviceImei` | string | Device IMEI |
| `gpsTime` | string | GPS fix time |
| `gateTime` | string | Server receive time |
| `lng` | double | Longitude |
| `lat` | double | Latitude |
| `satelliteNum` | int | Satellites used |
| `gpsSpeed` | int | Speed (km/h) |
| `direction` | int | Heading (0-360 degrees) |
| `acc` | int | ACC status |
| `postType` | int | 1=GPS, 2=LBS, 3=WiFi |
| `postMethod` | int | Upload mode (0x00-0x0F) |
| `status` | int | Position status flags |
| `altitude` | int | Altitude (meters) |
| `distance` | int | Mileage (meters) |

---

### 10.4 Alarm Data

| Endpoint | `{YourURL}/pushalarm` |
|---|---|
| **Handler** | `webhook_receiver_rev.py` — implemented |
| **DB table** | `tracksolid.alarms` |

> **Field name note:** Push uses `alarmType` and `alarmName` — different from the polling endpoint which uses `alertTypeId` and `alarmTypeName`. See Section 6.1 for the full mapping table.

**`data_list` fields (max 50 per request):**

| Field | Type | Description |
|---|---|---|
| `deviceImei` | string | Device IMEI |
| `alarmType` | string | Alarm type |
| `alarmName` | string | Alarm display name |
| `gateTime` | string | Event time |
| *(additional fields vary by alarm type)* | | |

---

### 10.5 RFID Data

| Endpoint | `{YourURL}/rfid` |
|---|---|

**`data_list` fields:**

| Field | Type | Description |
|---|---|---|
| `moduleType` | string | RFID module type |
| `deviceImei` | string | Device IMEI |
| `gateTime` | string | Scan time |
| `postTime` | string | Post time |
| `value` | string | Encoded RFID value |
| `gpsTime` | string | Optional GPS time |
| `lng`, `lat` | double | Optional GPS position |

---

### 10.6 Plug-In Module Data

| Endpoint | `{YourURL}/wgtc` |
|---|---|

**`data_list` fields:**

| Field | Type | Description |
|---|---|---|
| `deviceImei` | string | Device IMEI |
| `hexContent` | string | Hex-formatted module data |
| `postTime` | string | Optional timestamp |
| `gpsTime` | string | Optional GPS time |
| `lng`, `lat` | double | Optional GPS position |
| `category` | string | Protocol (0x9B, 0xF2) |
| `type` | int | Message type |

---

### 10.7 Fuel / Oil Sensor Data

| Endpoint | `{YourURL}/pushoil` |
|---|---|
| **Handler** | `webhook_receiver_rev.py` — implemented (PUSH-02) |
| **DB table** | `tracksolid.fuel_readings` (TimescaleDB hypertable) |

**`data_list` fields (max 50 per request):**

| Field | Type | Description |
|---|---|---|
| `deviceImei` | string | Device IMEI |
| `path` | int | Sensor ID |
| `gateTime` | string | Reading time |
| `value` | double | Oil level (divide by 100 for actual value) |
| `unit` | int | `1`=cm, `2`=%, `3`=V, `4`=L — stored as text label in DB |
| `gpsTime` | string | Optional GPS time |
| `lng`, `lat` | double | Optional GPS position |

---

### 10.8 File Upload Notification

| Endpoint | `{YourURL}/pushfileupload` |
|---|---|

**`data_list` fields:**

| Field | Type | Description |
|---|---|---|
| `deviceImei` | string | Device IMEI |
| `fileName` | string | File list (semicolon-separated) |
| `gateTime` | string | Upload time |
| `result` | string | `SUCCESS` or `FAILURE` |

---

### 10.9 Temperature & Humidity

| Endpoint | `{YourURL}/pushtem` |
|---|---|
| **Handler** | `webhook_receiver_rev.py` — implemented (PUSH-03) |
| **DB table** | `tracksolid.temperature_readings` (TimescaleDB hypertable) |

**`data_list` fields:**

| Field | Type | Description |
|---|---|---|
| `deviceImei` | string | Device IMEI |
| `tem` | double | Temperature value |
| `hum` | double | Humidity percentage |
| `gateTime` | string | Reading time |
| `postTime` | string | Post time |

---

### 10.10 LBS / Cell Tower Data

| Endpoint | `{YourURL}/pushlbs` |
|---|---|
| **Handler** | `webhook_receiver_rev.py` — implemented (PUSH-04) |
| **DB table** | `tracksolid.lbs_readings` |

**`data_list` fields:**

| Field | Type | Description |
|---|---|---|
| `postType` | string | `WIFI` or `LBS` |
| `deviceImei` | string | Device IMEI |
| `gateTime` | string | Reading time |
| `lbsJson` | string | JSON with MCC, MNC, cellList (LAC, CI, RSSI) |

---

### 10.11 Resource List (Video Inventory)

| Endpoint | `{YourURL}/pushresourcelist` |
|---|---|

**`data_list` fields:**

| Field | Type | Description |
|---|---|---|
| `imei` | string | Device IMEI |
| `totalNum` | string | Number of resources |
| `instructionID` | string | Unique instruction ID |
| `resourceList` | array | Objects with: `channel`, `beginTime`, `endTime`, `fileSize`, `resourceType`, `codeType`, `storageType`, `alarmFlag` |

---

### 10.12 FTP Upload Result

| Endpoint | `{YourURL}/pushftpfileupload` |
|---|---|

**`data_list` fields:**

| Field | Type | Description |
|---|---|---|
| `result` | int | 0=Success, 1=Failure |
| `deviceImei` | string | Device IMEI |
| `instructionID` | string | Instruction reference |
| `gateTime` | string | Completion time |

---

### 10.13 IoTHub Events

| Endpoint | `{YourURL}/pushIothubEvent` |
|---|---|

**`data_list` fields:**

| Field | Type | Description |
|---|---|---|
| `deviceImei` | string | Device IMEI |
| `gateTime` | string | Event time |
| `eventType` | string | One of: `UploadAlarmFileList`, `UploadAlarmFileBegin`, `UploadAlarmFileEnd`, `UploadMediaFileBegin`, `UploadMediaFileEnd` |
| `eventContent` | string | Event-specific JSON payload |

---

### 10.14 PassThrough Data

| Endpoint | `{YourURL}/pushPassThroughData` |
|---|---|

**`data_list` fields:**

| Field | Type | Description |
|---|---|---|
| `deviceImei` | string | Device IMEI |
| `gateTime` | string | Receive time |
| `type` | int | Message type (0, 11, 65, 66, 240-255) |
| `category` | string | Protocol (0x0900, 0x9C, 0x94) |
| `content` | string | Base64-encoded message body |

---

### 10.15 Extension Data

| Endpoint | `{YourURL}/pushTerminalTransInfo` |
|---|---|

**`data_list` fields:**

| Field | Type | Description |
|---|---|---|
| `postTime` | string | Post time |
| `deviceImei` | string | Device IMEI |
| `gpsTime` | string | Optional GPS time |
| `lng`, `lat` | double | Optional GPS position |
| `extensionId` | int | 8197=device status, 8199=serial port data |
| `content` | string | Extension-specific JSON |

---

### 10.16 Offline Command Response

| Endpoint | `{YourURL}/pushInstructResponse` |
|---|---|

**Fields:**

| Field | Type | Description |
|---|---|---|
| `token` | string | Auth token |
| `msgType` | int | 1=Asynchronous, 2=Offline commands |
| `data_list` | string | JSON with `_code`, `_msg`, `_imei`, `_serverFlagId`, `_content` |

---

### 10.17 Facial ID List

| Endpoint | `{YourURL}/pushFileContent` |
|---|---|

**`data_list` fields:**

| Field | Type | Description |
|---|---|---|
| `instructionId` | string | Instruction reference |
| `postTime` | string | Post time |
| `deviceImei` | string | Device IMEI |
| `gateTime` | string | Event time |
| `content` | array | ID list strings |

---

### 10.18 Extended Data (JIMI KKS)

| Endpoint | `{YourURL}/pushextendedkks` |
|---|---|

Pushes extended device data with sub-message types identified by `subMessagesId`:
- GPS data, KC208 events, power info, Bluetooth peripherals, positioning method, distance, ACC, LBS, pass-through data, positional accuracy

---

### 10.19 DVR Upload Callback

| Endpoint | `{YourURL}/uploadCallback` |
|---|---|

Called when a device finishes uploading media (photo, video, event clip) to Jimi's cloud.

**`data_list` fields:**

| Field | Type | Description |
|---|---|---|
| `businessType` | string | `regularPicture`, `remotePictureOrVideo`, `eventAttachment`, `historyVideo`, `facePicture`, etc. |
| `imei` | string | Device IMEI |
| `camera` | int | Camera channel index |
| `shootType` | int | 1=Photo, 2=Video |
| `shootTime` | int | Video duration (seconds) |
| `alarmTime` | long | Unix timestamp of alarm trigger |
| `lat`, `lng` | string | GPS coordinates |
| `mimeType` | string | `image/jpeg`, `video/mp4`, etc. |
| `localFileName` | string | Original device filename |
| `filename` | string | Cloud storage filename |
| `timezone` | string | Optional timezone |
| `instructionId` | string | Optional instruction reference |

---

### 10.20 OBD Data

| Endpoint | `{YourURL}/pushobd` |
|---|---|
| **Handler** | `webhook_receiver_rev.py` — implemented |
| **DB table** | `tracksolid.obd_readings` |

> **Important:** This is the only documented method for receiving OBD data. There is no polling/pull endpoint for OBD. The handler extracts scalar fields (`engine_rpm`, `coolant_temp_c`, `fuel_level_pct`, `battery_voltage`, `intake_pressure`, `throttle_pct`, `vehicle_speed`, `engine_load_pct`) from `obdJson` using well-known OBD PID dataID keys, and also stores the full `obdJson` in the `obd_data JSONB` column.

**`data_list` fields:**

| Field | Type | Description |
|---|---|---|
| `deviceImei` | string | Device IMEI |
| `obdJson` | object | Contains all OBD readings |
| `obdJson.car_type` | int | 1=Commercial, 2=Passenger |
| `obdJson.push_time` | string | Push timestamp |
| `obdJson.event_time` | string | Event timestamp |
| `obdJson.AccState` | int | 0=OFF, 1=ON |
| `obdJson.statusFlags` | int | Status bit flags |
| `obdJson.lng` | double | Longitude |
| `obdJson.lat` | double | Latitude |
| `obdJson.dataID1..N` | int | Vehicle parameter values (engine RPM, coolant temp, fuel level, etc.) |

---

### 10.21 DTC Fault Codes

| Endpoint | `{YourURL}/pushfaultinfo` |
|---|---|
| **Handler** | Not yet implemented — DB table `tracksolid.fault_codes` exists and is ready |

> **Important:** This is the only documented method for receiving DTC fault codes.

**`data_list` fields:**

| Field | Type | Description |
|---|---|---|
| `deviceImei` | string | Device IMEI |
| `gateTime` | string | Report time (`yyyy-MM-dd HH:mm:ss`) |
| `faultCodeList` | array | DTC codes (e.g. `["P0301", "P0420"]`) |
| `faultNum` | int | Number of fault codes |
| `statusFlags` | int | OBD status bit flags |
| `lng` | double | GPS longitude |
| `lat` | double | GPS latitude |
| `eventTime` | long | Fault event timestamp (Unix) |

---

### 10.22 Trip Report

| Endpoint | `{YourURL}/pushtripreport` |
|---|---|
| **Handler** | `webhook_receiver_rev.py` — implemented |
| **DB table** | `tracksolid.trips` |

**`data_list` fields:**

| Field | Type | Description |
|---|---|---|
| `deviceImei` | string | Device IMEI |
| `gateTime` | string | Report time |
| `miles` | double | Distance (km) |
| `oils` | double | Fuel consumption (L) |
| `idleTimes` | int | Accumulated idle time (seconds) |
| `tripSeq` | int | Trip sequence number |
| `beginTime` | string | Trip start (BCD format) |
| `endTime` | string | Trip end (BCD format) |
| `beginLat`, `beginLng` | double | Start coordinates |
| `endLat`, `endLng` | double | End coordinates |
| `properties` | int | 1=Start, 2=End |

---

## Appendix A: Instruction API (sendInstruct)

For advanced device control, the instruction API uses a separate endpoint:

**Endpoint:** `{InsAddress}/api/device/sendInstruct` (POST)

Common parameters: `deviceImei`, `proNo` (protocol number), `cmdContent` (JSON), `token`

| proNo | Function | Key cmdContent Fields |
|---|---|---|
| `128` | Universal text command | `cmdContent` (command string), `sync`, `offlineFlag`, `timeOut` |
| `37121` | Start real-time A/V stream | `dataType`, `codeStreamType`, `channel`, `videoIP`, `videoTCPPort` |
| `37122` | Control A/V stream | `channel`, `cmd` (0=Off, 1=Switch, 2=Pause, 3=Resume), `dataType` |
| `37381` | Query on-device video list | `channel`, `beginTime`, `endTime`, `alarmFlag`, `resourceType`, `instructionID` |
| `37377` | Start video playback | `serverAddress`, `tcpPort`, `channel`, `beginTime`, `endTime`, `playMethod`, `instructionID` |
| `33283` | Acknowledge alarm | `alarmSerialNo` |

**Response codes (`data._code`):**

| Code | Meaning |
|---|---|
| `100` | Success |
| `200` | Invalid parameter |
| `300` | Device offline |
| `600` | Timeout |

---

## Appendix B: API Coverage in This Codebase

### Polling (Pull) Endpoints

| API Method | File | Status | Notes |
|---|---|---|---|
| `jimi.oauth.token.get` | `ts_shared_rev.py` | ✅ In use | Token auto-refreshed, cached in DB |
| `jimi.oauth.token.refresh` | `ts_shared_rev.py` | ✅ In use | |
| `jimi.user.device.list` | `ingest_movement_rev.py` | ✅ In use | Fleet sync every 5h; 2 runs, 126 devices synced |
| `jimi.track.device.detail` | `ingest_movement_rev.py` | ✅ In use | Called alongside device.list |
| `jimi.user.device.location.list` | `ingest_movement_rev.py` | ✅ In use | Every 60s; 311 calls, 5,909 upserts, 0 failures |
| `jimi.device.track.mileage` | `ingest_movement_rev.py` | ✅ In use | Trip polling; `maxSpeed` now mapped (BUG-03 fixed) |
| `jimi.device.track.list` | `ingest_movement_rev.py` | ✅ In use | `poll_track_list()` every 30m (POLL-01 / FIX-M14); 15 calls, 80 waypoints |
| `jimi.device.location.get` | `ingest_movement_rev.py` | ✅ In use | `get_device_locations()` on-demand batch refresh (POLL-03 / FIX-M15); max 50 IMEIs/call |
| `jimi.open.platform.report.parking` | `ingest_movement_rev.py` | ✅ In use | `acc_type=0`, `durSecond` corrected (POLL-02 / FIX-M13); 60 calls, 0 rows (fleet overnight) |
| `jimi.device.alarm.list` | `ingest_events_rev.py` | ✅ In use | `alertTypeId`/`alarmTypeName` mapping fixed (BUG-01 / FIX-E06); 11 calls, 11 rows |
| `jimi.device.obd.list` | — | ❌ Does not exist | OBD data is push-only via `/pushobd` |
| `jimi.device.jimi.media.URL` | — | Not used | Media file catalog |
| `jimi.device.media.event.URL` | — | Not used | Alarm-triggered media |
| All other geofence/command/media polling | — | Not used | Available when needed |

### Push (Webhook) Endpoints

| Endpoint | File | Status | DB Table |
|---|---|---|---|
| `/pushalarm` | `webhook_receiver_rev.py` | ✅ Implemented | `tracksolid.alarms` |
| `/pushtripreport` | `webhook_receiver_rev.py` | ✅ Implemented | `tracksolid.trips` |
| `/pushobd` | `webhook_receiver_rev.py` | ✅ Implemented | `tracksolid.obd_readings` |
| `/pushevent` | `webhook_receiver_rev.py` | ✅ Implemented (PUSH-01) | `tracksolid.device_events` |
| `/pushoil` | `webhook_receiver_rev.py` | ✅ Implemented (PUSH-02) | `tracksolid.fuel_readings` |
| `/pushtem` | `webhook_receiver_rev.py` | ✅ Implemented (PUSH-03) | `tracksolid.temperature_readings` |
| `/pushlbs` | `webhook_receiver_rev.py` | ✅ Implemented (PUSH-04) | `tracksolid.lbs_readings` |
| `/pushhb` | — | ⚠️ Not yet wired | `tracksolid.heartbeats` table ready |
| `/pushfaultinfo` | — | ⚠️ Not yet wired | `tracksolid.fault_codes` table ready |
| `/pushgps` | — | Not used | GPS data received via polling |
| All other push endpoints | — | Not used | |

> **Registration status:** All implemented webhook endpoints need to be registered in the Tracksolid Pro dashboard with your server's public URL before they will receive data. Tables exist and are ready; rows will be 0 until registration is complete.