1. 概述
DeliTMS 通过专用服务——Telemetry——接收 GPS 数据，该服务针对时间序列的写入/读取进行了优化。任何来源(车载跟踪设备、企业移动应用、第三方 GPS 网关)都可以通过统一的 HTTP API 上传位置数据，支持GPS数据上传与API集成。DeliTMS 会自动将 GPS 点关联到正确的车辆/行程，实现车辆跟踪和实时监控，显示在地图和监控页面(参见第 12 章)，并运行告警分析。
如果企业使用 DeliTMS 司机应用，应用已自动发送 GPS——无需额外集成。本指南适用于使用自有 GPS 设备/系统的情况。
2. 获取密钥与认证
每个发送方都会获得一个 API key，格式为 dtms_…(联系 DeliTMS 部署团队获取您企业的密钥)。通过 header 将密钥附加到每个请求:
X-Api-Key: dtms_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
或使用 Authorization: Bearer dtms_…。缺少/错误的密钥 → 401。请保密密钥——仅在设备/服务器端配置，不要嵌入到最终用户应用中。
3. GPS 上传端点
POST {TELEMETRY_URL}/gps/ingest
Content-Type: application/json
X-Api-Key: dtms_…
{TELEMETRY_URL} 是 DeliTMS 提供的 Telemetry 服务地址(例如 https://telemetry.delitms.com)。每个请求发送一辆车的一个 GPS 点。
4. 两种车辆识别方式
Telemetry 需要知道 GPS 点属于哪辆车。选择其中一种方式:
| 方式 | 发送字段 | 何时使用 |
|---|---|---|
| 按 IMEI(跟踪器推荐) | imei + company_id | 设备仅知道自身序列号；Telemetry 自动通过IMEI识别查询 DeliTms_device.serial_number → 当前分配的车辆。无需知道 vehicle_id |
| 按 vehicle_id | vehicle_id + company_id | 您的系统已知 DeliTMS 中的车辆 ID |
对于硬件跟踪器，使用 IMEI 模式:当企业更换/调整设备对应的车辆时，只需在 DeliTMS 中更新设备分配，GPS 发送方无需任何修改。
5. 请求内容(JSON body)
{
"imei": "SN-0864221135", // 或: "vehicle_id": 558
"company_id": 22,
"source": "tracker", // "tracker"(设备) | "app"(应用)
"latitude": 10.776900,
"longitude": 106.696600,
"speed": 45.5, // km/h
"heading": 180, // 度数，0–360
"accuracy": 8.0, // 米
"status": "moving", // moving | stopped | idle
"timestamp": 1714298401, // Unix 秒；省略 = 接收时刻
"metadata": { "driver_id": 123, "trip_id": "ABC-001", "fuel_level_pct": 78.4 }
}
| 字段 | 类型 | 必填 | 描述 |
|---|---|---|---|
imei | 字符串 | 是* | 设备序列号——代替 vehicle_id |
vehicle_id | 数字 | 是* | DeliTMS 中的车辆 ID(与 company_id 一起使用) |
company_id | 数字 | 是 | 企业 ID(以便 Telemetry 查询正确的设备/车辆) |
source | 字符串 | 是 | "tracker" 或 "app" |
latitude / longitude | 浮点数 | 是 | 十进制坐标(例如 10.7769 / 106.6966) |
status | 字符串 | 是 | moving(行驶中) · stopped(停止，熄火) · idle(停驻，发动机运转) |
speed | 浮点数 | – | km/h |
heading | 浮点数 | – | 行驶方向，度数(0–360) |
accuracy / altitude | 浮点数 | – | 精度 / 海拔，米 |
timestamp | 数字 | – | Unix 秒；省略则取请求接收时刻 |
metadata | 对象 | – | 自定义 JSON: driver_id、trip_id、fuel_level_pct、cargo_door、route_violation、forbidden_zone… |
* 必须有二选一: imei 或 (vehicle_id + company_id)。使用 imei 时仍建议附带 company_id。
响应。 成功: 200 { "success": true, "latency_ms": 42 }。缺少字段: 400 { "error": "field 'vehicle_id' is required" }。写入错误: 500。密钥错误/缺失: 401。
6. 示例
6.1. curl
curl -X POST "$TELEMETRY_URL/gps/ingest" \
-H "Content-Type: application/json" \
-H "X-Api-Key: $TELEMETRY_API_KEY" \
-d '{
"imei": "SN-0864221135", "company_id": 22, "source": "tracker",
"latitude": 10.7769, "longitude": 106.6966,
"speed": 45.5, "heading": 180, "status": "moving",
"timestamp": '"$(date +%s)"'
}'
6.2. Node.js
async function sendGps({ imei, companyId, lat, lng, speed, heading, status }) {
const res = await fetch(`${process.env.TELEMETRY_URL}/gps/ingest`, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'X-Api-Key': process.env.TELEMETRY_API_KEY,
},
body: JSON.stringify({
imei, company_id: companyId, source: 'tracker',
latitude: Number(lat.toFixed(6)), longitude: Number(lng.toFixed(6)),
speed: Number(speed.toFixed(1)), heading: Number(heading.toFixed(1)),
status, timestamp: Math.floor(Date.now() / 1000),
}),
});
if (!res.ok) throw new Error(`HTTP ${res.status}: ${await res.text()}`);
return res.json();
}
// 定期发送(例如每 10–15 秒)，当车辆行驶中:
setInterval(async () => {
const p = readGpsFromDevice(); // 从设备读取 lat/lng/speed/heading
try { await sendGps({ imei: 'SN-0864221135', companyId: 22, ...p, status: p.speed > 0 ? 'moving' : 'idle' }); }
catch (e) { console.warn('gps 发送失败(将在下次重试):', e.message); }
}, 10000);
6.3. 硬件跟踪设备
如果跟踪器仅支持原始 HTTP: 配置它 POST 到 {TELEMETRY_URL}/gps/ingest，添加 header X-Api-Key，JSON body 如上，其中 imei = 设备序列号。DeliTMS 通过设备分配记录自动映射序列号 → 车辆(缓存 30 秒)。
7. 频率与最佳实践
- 频率: 车辆行驶时每 5–15 秒/点是合理的(足够流畅显示地图 + 告警，节省电量/带宽)。
stopped状态时可适当放宽。 - 错误重试: 如果请求网络错误，在下一周期重试——无需阻塞流程。旧数据点仍使用原始
timestamp。 - 正确设置
status以确保告警/历史准确: speed > 0 时为moving，停驻且发动机运转时为idle，熄火时为stopped。 - 同步设备时间(NTP)以避免
timestamp偏差。
8. 读取已发送数据
除了上传，Telemetry 还提供读取(同样使用 X-Api-Key): GET /gps/history(按车辆/时间范围查询历史)、GET /gps/events(告警事件: 超速、偏离路线…)、GET /gps/summary/daily(每日 KPI)。上传的数据也会立即显示在门户的地图与监控页面。