1. Tổng quan

DeliTMS nhận GPS qua một dịch vụ riêng — Telemetry — tối ưu cho ghi/đọc chuỗi thời gian. Bất kỳ nguồn nào (thiết bị tracker gắn xe, app di động của doanh nghiệp, cổng GPS của bên thứ ba) đều có thể bơm vị trí lên qua một API HTTP duy nhất. DeliTMS tự gắn điểm GPS vào đúng xe/chuyến, hiển thị trên trang Bản đồ và Giám sát (xem chương 12), và chạy phân tích cảnh báo.

Nếu doanh nghiệp dùng app lái xe DeliTMS thì app đã tự gửi GPS — không cần tích hợp gì thêm. Hướng dẫn này dành cho khi bạn dùng thiết bị/hệ thống GPS riêng và cần tích hợp GPS với DeliTMS.

2. Lấy khóa & xác thực

Mỗi bên gửi được cấp một API key dạng dtms_… (liên hệ đội triển khai DeliTMS để lấy key cho doanh nghiệp của bạn). Gắn key vào mọi request qua header:

X-Api-Key: dtms_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Hoặc dùng Authorization: Bearer dtms_…. Thiếu/sai key → 401. Giữ key bí mật — chỉ đặt ở phía thiết bị/máy chủ, không nhúng vào ứng dụng phía người dùng cuối.

3. Endpoint gửi GPS

POST {TELEMETRY_URL}/gps/ingest
Content-Type: application/json
X-Api-Key: dtms_…

{TELEMETRY_URL} là địa chỉ dịch vụ Telemetry do DeliTMS cung cấp (ví dụ https://telemetry.delitms.com). API GPS này nhận một điểm GPS của một xe mỗi request.

4. Hai cách định danh xe

Telemetry cần biết điểm GPS thuộc xe nào. Chọn một trong hai cách:

CáchTrường gửiKhi nào dùng
Theo IMEI (khuyến nghị cho tracker)imei + company_idThiết bị chỉ biết số serial của mình; Telemetry tự tra DeliTms_device.serial_number → xe đang gán. Không cần biết vehicle_id
Theo vehicle_idvehicle_id + company_idHệ thống của bạn đã biết ID xe trong DeliTMS

Với tracker phần cứng, dùng IMEI mode: khi doanh nghiệp thay/đổi xe cho thiết bị, chỉ cần cập nhật gán thiết bị trong DeliTMS, bên gửi GPS không phải đổi gì.

5. Nội dung request (body JSON)

{
  "imei": "SN-0864221135",        // hoặc: "vehicle_id": 558
  "company_id": 22,
  "source": "tracker",             // "tracker" (thiết bị) | "app" (ứng dụng)
  "latitude": 10.776900,
  "longitude": 106.696600,
  "speed": 45.5,                   // km/h
  "heading": 180,                  // độ, 0–360
  "accuracy": 8.0,                 // mét
  "status": "moving",              // moving | stopped | idle
  "timestamp": 1714298401,         // Unix seconds; bỏ qua = thời điểm nhận
  "metadata": { "driver_id": 123, "trip_id": "ABC-001", "fuel_level_pct": 78.4 }
}
TrườngKiểuBắt buộcMô tả
imeichuỗiCó*Serial thiết bị — thay cho vehicle_id
vehicle_idsốCó*ID xe trong DeliTMS (đi cùng company_id)
company_idsốCóID doanh nghiệp (để Telemetry tra đúng thiết bị/xe)
sourcechuỗiCó"tracker" hoặc "app"
latitude / longitudesố thựcCóTọa độ thập phân (vd 10.7769 / 106.6966)
statuschuỗiCómoving (đang chạy) · stopped (dừng, tắt máy) · idle (đứng, nổ máy)
speedsố thực–km/h
headingsố thực–Hướng di chuyển, độ (0–360)
accuracy / altitudesố thực–Độ chính xác / độ cao, mét
timestampsố–Unix seconds; bỏ qua thì lấy thời điểm nhận request
metadataobject–JSON tự do: driver_id, trip_id, fuel_level_pct, cargo_door, route_violation, forbidden_zone…

* Phải có một trong hai: imei HOẶC (vehicle_id + company_id). Khi dùng imei vẫn nên kèm company_id.

Phản hồi. Thành công: 200 { "success": true, "latency_ms": 42 }. Thiếu trường: 400 { "error": "field 'vehicle_id' is required" }. Lỗi ghi: 500. Sai/thiếu key: 401.

6. Ví dụ

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();
}

// Gửi dữ liệu GPS định kỳ (vd mỗi 10–15 giây) khi xe đang chạy:
setInterval(async () => {
  const p = readGpsFromDevice();            // lat/lng/speed/heading từ thiết bị
  try { await sendGps({ imei: 'SN-0864221135', companyId: 22, ...p, status: p.speed > 0 ? 'moving' : 'idle' }); }
  catch (e) { console.warn('gps gửi lỗi (sẽ thử lại lần sau):', e.message); }
}, 10000);

6.3. Thiết bị tracker phần cứng

Nếu tracker chỉ gửi được HTTP thô: cấu hình nó POST tới {TELEMETRY_URL}/gps/ingest, thêm header X-Api-Key, thân JSON như trên với imei = serial của thiết bị. DeliTMS tự map serial → xe qua bản ghi gán thiết bị (cache 30 giây).

7. Tần suất & thực hành tốt

  • Tần suất: 5–15 giây/điểm khi xe chạy là hợp lý (đủ mượt cho bản đồ + cảnh báo, tiết kiệm pin/băng thông). Khi stopped có thể giãn thưa.
  • Gửi lại khi lỗi: nếu request lỗi mạng, thử lại ở nhịp sau — không cần chặn luồng. Điểm cũ vẫn dùng timestamp gốc.
  • Đặt status đúng để cảnh báo/lịch sử chính xác: moving khi speed > 0, idle khi đứng nổ máy, stopped khi tắt máy.
  • Đồng bộ giờ thiết bị (NTP) để timestamp không lệch.

8. Đọc lại dữ liệu đã gửi

Ngoài gửi, Telemetry còn cho đọc (cùng X-Api-Key): GET /gps/history (lịch sử theo xe/khoảng thời gian), GET /gps/events (sự kiện cảnh báo: vượt tốc độ, rời tuyến…), GET /gps/summary/daily (KPI ngày). Dữ liệu gửi lên cũng hiện ngay trên Bản đồ & Giám sát của portal, giúp giám sát xe theo thời gian thực.