ข้อกำหนดเหตุการณ์เทเลเมติกส์

ใช้สคีมานี้เมื่อส่งเหตุการณ์เทเลเมติกส์เข้าสู่ Cartrack

หมายเหตุสำคัญ

• เวลาใช้ UTC รูปแบบ ISO-8601 เท่านั้น
• บังคับความไม่ซ้ำของเหตุการณ์ (event uniqueness) เช่น ใช้ provider_event_id
• ตรวจสอบว่า event_ts <= ingested_at + tolerance (เวลาบันทึกฝั่งเซิร์ฟเวอร์)
• กำหนดเวอร์ชันของสคีมาหรือเส้นทาง เพื่อรองรับการเปลี่ยนแปลงในอนาคต
• หน่วยเลขกิโลเมตรสำหรับเลขไมล์สะสม (odometer)

Example payload

{
  "event_type": "PERIODIC",
  "event_ts": "2026-01-19T08:42:15Z",

  "chassis_number": "ABC12345678901234",

  "source": {
    "provider": "third_party_x",
    "device_id": "IMEI123456789",
    "provider_event_id": "evt-984739287",
    "provider_received_ts": "2026-01-19T08:42:18Z"
  },

  "position": {
    "latitude": 1.3521,
    "longitude": 103.8198,
    "altitude": 15
  },

  "telemetry": {
    "speed": 54,
    "ignition": true,
    "rpm": 2200,
    "odometer": 45231.4
  }
}

คำอธิบายฟิลด์

ฟิลด์ระดับบนสุด

Field	Type	Required	Notes
event_type	string	yes	IGNITION_ON, IGNITION_OFF, PERIODIC
event_ts	ISO-8601 UTC	yes	เวลาที่เกิดเหตุการณ์บนอุปกรณ์
chassis_number	string	yes	หมายเลขตัวถัง (VIN) 17 ตัวอักษรเท่านั้น
source	object	yes	ระบุที่มาของเหตุการณ์
position	object	conditional	จำเป็นสำหรับเหตุการณ์ที่มีตำแหน่ง
telemetry	object	optional	สัญญาณรถ เช่น ความเร็ว/สถานะกุญแจ

source

Field	Type	Required	Notes
provider	string	yes	ชื่อแหล่งข้อมูลเชิงตรรกะ
device_id	string	optional	IMEI หรือหมายเลขซีเรียล
provider_event_id	string	recommended	ใช้ควบคุมความซ้ำ (idempotency)
provider_received_ts	ISO-8601 UTC	optional	เวลาที่ผู้ให้บริการรับเหตุการณ์

position

Field	Type	Required	Notes
latitude	number	yes	องศาละติจูดแบบทศนิยม
longitude	number	yes	องศาลองจิจูดแบบทศนิยม
altitude	number	optional	ความสูงจากระดับน้ำทะเล (เมตร)

telemetry

Field	Type	Required	Units / Notes
speed	number	yes	km/h
ignition	boolean	yes	true = กุญแจ ON
rpm	number	optional	รอบเครื่องยนต์ต่อนาที
odometer	number	yes	กิโลเมตร

ความคาดหวังตามประเภทเหตุการณ์

Event type	Position	Telemetry
IGNITION_ON	required	จุดเริ่มต้นการเดินทาง
IGNITION_OFF	required	จบการเดินทาง
PERIODIC	required	ใช้ระบุเส้นทางการเดินทาง แนะนำให้ส่งต่อเนื่อง