Live GPS Fleet Tracking — Enterprise ERP Integration & API Reference

01

System Architecture & Integration Topology

Enterprise Platform Architecture

The Fleet Telematics System is a cloud-native, multi-tenant live GPS tracking platform engineered for high-throughput telematics ingestion, spatial boundary processing, and real-time state synchronization. External ERP systems integrate across three distinct data planes:

1. Ingestion Engine (:9000 TCP)

Asynchronously parses Sinotrack H02 ASCII datagrams. Employs in-memory negative-hit IMEI caching for sub-millisecond lookups, rejecting unauthorized devices before touching the database.

2. Spatial & Geofence Engine

Built on PostgreSQL with PostGIS geography point geometry. Computes geodetic distances on WGS84 ellipsoids (ST_DWithin) to trigger atomic enter and exit transitions.

3. ERP Stream Multiplexer

Stateless, cryptographically bounded WebSocket channel. Enforces tenant boundaries via signed session JWT tokens embedding whitelisted vehicle IDs.

02

5-Minute ERP Integration Quickstart

Follow this streamlined 5-step implementation lifecycle to register your ERP client, discover vehicles, mint a session token, and stream live telematics updates.

1

Self-Register or Rotate API Key

The ERP registers itself using the customer admin's dashboard credentials. Re-calling this endpoint with the same erpClientId instantly rotates the key and invalidates the previous one.

POST /api/integration/register

curl -X POST https://api.yourtrackinghost.com/api/integration/register \
  -H "Content-Type: application/json" \
  -d '{
    "erpClientId": "odoo-production",
    "email": "admin@acme-logistics.com",
    "password": "CustomerAdminPassword123!"
  }'

HTTP 201 CREATED RESPONSE:

{
  "customerId": 2,
  "erpClientId": "odoo-production",
  "apiKey": "fk_9d4e5f6a7b8c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c"
}

2

Retrieve Vehicle Catalog & Map Internal IDs

Query the customer's fleet directory to match ERP delivery vehicles against system tracking IDs and device IMEIs.

GET /api/integration/vehicles

curl -X GET https://api.yourtrackinghost.com/api/integration/vehicles \
  -H "Authorization: Bearer fk_9d4e5f6a7b8c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c"

HTTP 200 OK RESPONSE:

[
  { "id": 2, "name": "Van 12 - North Delivery", "plate": "BK-4412", "imei": "867421030123456" },
  { "id": 3, "name": "Van 04 - Express Hub", "plate": "BK-4401", "imei": "867421030123457" },
  { "id": 4, "name": "Heavy Truck 02", "plate": "TL-8821", "imei": "867421030123458" }
]

3

Mint Short-Lived WebSocket Session Token

Mint a scoped session token embedding the specific array of vehicle IDs to track. You can specify a custom TTL (30s to 86,400s).

POST /api/integration/session

curl -X POST https://api.yourtrackinghost.com/api/integration/session \
  -H "Content-Type: application/json" \
  -d '{
    "erpClientId": "odoo-production",
    "apiKey": "fk_9d4e5f6a7b8c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c",
    "vehicleIds": [2, 3, 4],
    "sessionLengthSeconds": 600
  }'

HTTP 200 OK RESPONSE:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJraW5kIjoiaW50ZWdyYXRpb24iLCJjaWQiOjIsInZpZHMiOlsyLDMsNF0sImlhdCI6MTcyNDIxODAwMCwiZXhwIjoxNzI0MjE4NjAwfQ.xyz...",
  "vehicleIds": [2, 3, 4],
  "expiresIn": 600,
  "expiresAt": "2026-08-21T10:30:00.000Z",
  "wsUrl": "/ws?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

4

Connect WebSocket & Stream Real-Time Frames

Open a persistent WebSocket connection to wss://api.yourtrackinghost.com/ws?token=<token>. Receive an immediate initial snapshot frame, followed by live position and alert pushes.

Proactive Reconnect Strategy: The session JWT is single-purpose and stateless. To maintain seamless 24/7 streaming without disconnect gaps, schedule a background timer to mint a new token at 80% TTL elapsed (e.g. at 480 seconds for a 600s token) and gracefully reconnect.

03

Authentication & Security Architecture

Two-Tier Security Architecture

The platform combines long-lived tenant API keys with short-lived cryptographically signed session JWT tokens to guarantee isolation and zero trust on WebSocket channels.

Credential Type	Format / Pattern	Storage / Cryptography	Lifecycle / Expiration	Scope & Boundary
Integration API Key	`fk_<48 hex chars>`	One-way SHA-256 hash in `integration_keys`	Persistent until revoked or auto-rotated	Bound to customer tenant & `client_id`
Session JWT Token	Stateless HMAC-SHA256 JWT	Signed with server `JWT_SECRET`	Configurable TTL (30s – 86,400s)	Whitelist array of vehicle IDs (`vids`)
User Dashboard JWT	Stateless HMAC-SHA256 JWT	Signed with server `JWT_SECRET`	7 Days (`expiresIn: '7d'`)	User role (`super_admin`, `admin`, `user`)

HTTP Status Codes & Security Errors

Status Code	Error Payload	Root Cause & Mitigation
`400 Bad Request`	`{"error":"vehicleIds required"}`	Request body omitted the `vehicleIds` array or passed an empty list. Max limit is 500 IDs per request.
`401 Unauthorized`	`{"error":"invalid or revoked integration key"}`	Supplied API key is invalid, improperly formatted, or has been revoked in the database.
`401 Unauthorized`	`{"error":"invalid admin credentials"}`	On `/api/integration/register`, the supplied email or password does not match a tenant admin user.
`403 Forbidden`	`{"error":"erpClientId does not match integration key"}`	The `erpClientId` passed in the session request does not match the bound `client_id` of the API key.
`403 Forbidden`	`{"error":"no allowed vehicles"}`	None of the requested vehicle IDs belong to the customer tenant associated with this API key.
`4001 WS Close`	WebSocket Close Code `4001`	WebSocket connection attempted with a missing, malformed, or expired session JWT token.

12

How to Mint & Manage Integration API Keys

Two Methods for Minting Integration API Keys

Every customer tenant has isolated access to their own vehicle fleet. Integration API keys (format: fk_<48 hex chars>) are bound to both a customer tenant and a unique ERP client identifier (client_id). Only the SHA-256 hash is stored on the server.

METHOD A Programmatic Self-Service Registration (API)

ERP developers can programmatically mint their own API key by sending their desired erpClientId along with the email and password of their customer tenant administrator.

POST /api/integration/register

curl -X POST https://api.yourtrackinghost.com/api/integration/register \
  -H "Content-Type: application/json" \
  -d '{
    "erpClientId": "odoo-production-instance",
    "email": "admin@yourcompany.com",
    "password": "TenantAdminPassword123!"
  }'

HTTP 201 CREATED RESPONSE:

{
  "customerId": 2,
  "erpClientId": "odoo-production-instance",
  "apiKey": "fk_4f8e2a1b9c3d7e5f608192a3b4c5d6e7f8a9b0c1d2e3f4a5"
}

Zero-Downtime Key Rotation: Re-issuing a POST /api/integration/register request with the same erpClientId generates a fresh key and immediately replaces the previous key hash in the database.

METHOD B Web Dashboard UI Generation (Platform Portal)

Administrators can visually generate and manage integration keys through the web dashboard:

Log in to the web dashboard (/login) as an administrator account.
In the navigation bar, navigate to Integration (/admin/integration).
Under New API Key, enter:
- Label / Name: e.g., "Odoo Main ERP"
- Client ID (erp_client_id): e.g., "odoo-prod"
Click Generate Key. Copy the raw key (fk_...) immediately, as it is displayed only once.

Equivalently via the Admin REST API:

POST /api/integration/keys
Authorization: Bearer <admin-jwt-token>
Content-Type: application/json

{
  "name": "Odoo Production",
  "clientId": "odoo-prod"
}

HTTP/1.1 201 Created
{
  "name": "Odoo Production",
  "clientId": "odoo-prod",
  "key": "fk_9d4e5f6a7b8c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c"
}

Key Revocation & Leak Recovery

If an API key is ever compromised, revoke it immediately via the Admin dashboard or by calling:

POST /api/integration/keys/:id/revoke
Authorization: Bearer <admin-jwt-token>

HTTP/1.1 204 No Content

13

Building a Live Telematics Map on Your Own ERP UI

Architecture: Secure Backend Proxy Pattern

To securely render live vehicle markers on your ERP browser interface without exposing your master API key, follow the Backend Session Token Proxy Pattern:

            1. User opens ERP Delivery Dashboard in Browser.

            2. ERP Web Server calls POST /api/integration/session using server-side apiKey (e.g. TTL = 300s).

            3. ERP Web Server embeds the short-lived sessionToken into the frontend component.

            4. Browser opens wss://api.yourtrackinghost.com/ws?token=<sessionToken>.

            5. Browser receives live positions, rotates vehicle heading markers, and renders real-time movement trails.

Interactive Frontend Components (Plain HTML, React, Angular)

Select your preferred frontend framework tab below for a full, copy-pasteable implementation:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>ERP Live Fleet Tracking Map</title>
  <!-- Leaflet CSS -->
  <link rel="stylesheet" href="https://unpkg.com/leaflet@1.9.4/dist/leaflet.css" />
  <style>
    * { box-sizing: border-box; margin: 0; padding: 0; font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; }
    body { display: flex; height: 100vh; background: #0f172a; color: #f8fafc; overflow: hidden; }
    
    /* Sidebar */
    #fleet-sidebar { width: 320px; background: #1e293b; border-right: 1px solid #334155; display: flex; flex-direction: column; z-index: 10; }
    .sidebar-head { padding: 16px; border-bottom: 1px solid #334155; display: flex; justify-content: space-between; align-items: center; }
    .sidebar-head h3 { font-size: 1rem; font-weight: 700; color: #38bdf8; }
    .status-pill { font-size: 0.7rem; padding: 2px 8px; border-radius: 9999px; background: #065f46; color: #34d399; font-weight: 600; }
    .status-pill.offline { background: #7f1d1d; color: #f87171; }
    
    #vehicle-list { flex: 1; overflow-y: auto; padding: 12px; }
    .vehicle-card { background: #0f172a; border: 1px solid #334155; border-radius: 8px; padding: 12px; margin-bottom: 8px; cursor: pointer; transition: all 0.2s; }
    .vehicle-card:hover, .vehicle-card.active { border-color: #38bdf8; background: #172554; }
    .vehicle-title { font-weight: 600; font-size: 0.9rem; margin-bottom: 4px; display: flex; justify-content: space-between; }
    .vehicle-meta { font-size: 0.75rem; color: #94a3b8; display: flex; justify-content: space-between; }
    
    /* Map Area */
    #map-container { flex: 1; position: relative; height: 100%; }
    #map { width: 100%; height: 100%; background: #0b0f19; }
    
    /* Directional Marker */
    .marker-dot { width: 20px; height: 20px; border-radius: 50%; background: #38bdf8; border: 2px solid #ffffff; box-shadow: 0 0 10px rgba(56, 189, 248, 0.6); position: relative; display: flex; align-items: center; justify-content: center; }
    .marker-dot.offline { background: #94a3b8; box-shadow: none; }
    .marker-dot .arrow { width: 0; height: 0; border-left: 5px solid transparent; border-right: 5px solid transparent; border-bottom: 10px solid #ffffff; position: absolute; top: -14px; transform-origin: 50% 24px; }
    .pulse-ring { position: absolute; width: 100%; height: 100%; border-radius: 50%; animation: pulse 2s infinite; border: 2px solid #38bdf8; opacity: 0; }
    @keyframes pulse { 0% { transform: scale(1); opacity: 0.8; } 100% { transform: scale(2.5); opacity: 0; } }
    
    /* Movement Trail */
    .leaflet-interactive.trail-line { stroke: #38bdf8; stroke-width: 3; stroke-dasharray: 6, 6; filter: drop-shadow(0 0 4px #0284c7); }
    
    /* Alert Toast */
    #alert-toast-container { position: absolute; top: 20px; right: 20px; z-index: 1000; display: flex; flex-direction: column; gap: 8px; }
    .alert-toast { background: rgba(30, 41, 59, 0.95); border-left: 4px solid #f59e0b; color: #f8fafc; padding: 12px 16px; border-radius: 6px; box-shadow: 0 10px 15px -3px rgba(0,0,0,0.5); font-size: 0.85rem; }
  </style>
</head>
<body>

  <!-- Sidebar -->
  <aside id="fleet-sidebar">
    <div class="sidebar-head">
      <h3>Fleet Telematics</h3>
      <span id="conn-status" class="status-pill">Connecting...</span>
    </div>
    <div id="vehicle-list"></div>
  </aside>

  <!-- Map Container -->
  <main id="map-container">
    <div id="map"></div>
    <div id="alert-toast-container"></div>
  </main>

  <!-- Leaflet JS -->
  <script src="https://unpkg.com/leaflet@1.9.4/dist/leaflet.js"></script>
  <script>
    const CONFIG = {
      wsBaseUrl: "ws://localhost:3000/ws",
      sessionToken: "PASTE_YOUR_SESSION_JWT_TOKEN_HERE" 
    };

    const state = {
      vehicles: new Map(),
      markers: new Map(),
      trails: new Map(),
      selectedId: null,
      ws: null
    };

    // 1. Initialize Map
    const map = L.map('map').setView([51.5074, -0.1278], 13);
    L.tileLayer('https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png', {
      maxZoom: 19,
      attribution: '© OpenStreetMap'
    }).addTo(map);

    // 2. Custom Marker Generator
    function createMarkerIcon(heading = 0, isLive = true) {
      const headingDeg = heading || 0;
      const html = `
        <div class="marker-dot ${isLive ? '' : 'offline'}">
          ${isLive ? '<div class="pulse-ring"></div>' : ''}
          <div class="arrow" style="transform: rotate(${headingDeg}deg);"></div>
        </div>
      `;
      return L.divIcon({ className: '', html, iconSize: [20, 20], iconAnchor: [10, 10] });
    }

    // 3. Render Vehicle Sidebar
    function renderSidebar() {
      const listEl = document.getElementById('vehicle-list');
      listEl.innerHTML = '';
      state.vehicles.forEach(v => {
        const card = document.createElement('div');
        card.className = `vehicle-card ${state.selectedId === v.id ? 'active' : ''}`;
        const speedKmh = Math.round((v.speedKn || 0) * 1.852);
        card.innerHTML = `
          <div class="vehicle-title">
            <span>${v.name || 'Vehicle #' + v.id}</span>
            <span style="color:${v.valid ? '#34d399' : '#f87171'}">${speedKmh} km/h</span>
          </div>
          <div class="vehicle-meta">
            <span>${v.plate || 'No Plate'}</span>
            <span>${v.course || 0}° Heading</span>
          </div>
        `;
        card.onclick = () => focusVehicle(v.id);
        listEl.appendChild(card);
      });
    }

    // 4. Focus Vehicle
    function focusVehicle(vid) {
      state.selectedId = vid;
      renderSidebar();
      const v = state.vehicles.get(vid);
      if (v && v.lat && v.lon) {
        map.flyTo([v.lat, v.lon], 16, { duration: 1.2 });
        const m = state.markers.get(vid);
        if (m) m.openPopup();
      }
    }

    // 5. Update Position
    function updateVehiclePosition(vid, pos, meta = {}) {
      let v = state.vehicles.get(vid) || { id: vid, ...meta };
      v = { ...v, ...pos };
      state.vehicles.set(vid, v);

      const latLng = [v.lat, v.lon];
      let marker = state.markers.get(vid);

      if (!marker) {
        marker = L.marker(latLng, { icon: createMarkerIcon(v.course, v.valid) }).addTo(map);
        marker.on('click', () => focusVehicle(vid));
        state.markers.set(vid, marker);
      } else {
        marker.setLatLng(latLng);
        marker.setIcon(createMarkerIcon(v.course, v.valid));
      }

      const speedKmh = Math.round((v.speedKn || 0) * 1.852);
      marker.bindPopup(`
        <div style="color:#0f172a; font-family:sans-serif;">
          <strong style="font-size:1rem;">${v.name || 'Vehicle #' + vid}</strong><br>
          <span style="color:#64748b;">Plate:</span> ${v.plate || '—'}<br>
          <span style="color:#64748b;">Speed:</span> <strong>${speedKmh} km/h</strong><br>
          <span style="color:#64748b;">Heading:</span> ${v.course || 0}°<br>
          <span style="color:#64748b;">Coords:</span> ${v.lat.toFixed(5)}, ${v.lon.toFixed(5)}
        </div>
      `);

      let trail = state.trails.get(vid);
      if (!trail) {
        trail = L.polyline([latLng], { className: 'trail-line' }).addTo(map);
        state.trails.set(vid, trail);
      } else {
        trail.addLatLng(latLng);
      }

      renderSidebar();
    }

    // 6. Connect Realtime WebSocket
    function connectStreaming(token) {
      const statusEl = document.getElementById('conn-status');
      const ws = new WebSocket(`${CONFIG.wsBaseUrl}?token=${token}`);

      ws.onopen = () => {
        statusEl.textContent = "Live";
        statusEl.className = "status-pill";
      };

      ws.onmessage = (event) => {
        try {
          const msg = JSON.parse(event.data);
          if (msg.type === 'snapshot') {
            msg.positions.forEach(p => {
              updateVehiclePosition(p.vehicle_id, {
                lat: p.lat, lon: p.lon, speedKn: p.speed_kn, course: p.course, valid: p.valid
              });
            });
            const pts = msg.positions.map(p => [p.lat, p.lon]);
            if (pts.length) map.fitBounds(pts, { padding: [50, 50] });
          } else if (msg.type === 'position') {
            updateVehiclePosition(msg.vehicleId, msg.position);
          }
        } catch (e) { console.error("WS Parse error:", e); }
      };

      ws.onclose = () => {
        statusEl.textContent = "Disconnected";
        statusEl.className = "status-pill offline";
        setTimeout(() => connectStreaming(token), 4000);
      };
    }

    connectStreaming(CONFIG.sessionToken);
  </script>
</body>
</html>

import React, { useEffect, useRef, useState } from 'react';
import L from 'leaflet';
import 'leaflet/dist/leaflet.css';

interface VehiclePosition {
  id: number;
  name?: string;
  plate?: string;
  lat: number;
  lon: number;
  speedKn: number;
  course: number;
  valid: boolean;
}

interface FleetLiveMapProps {
  wsUrl: string;       // e.g. "wss://api.yourtrackinghost.com/ws"
  sessionToken: string; // Minted via POST /api/integration/session
}

export const FleetLiveMap: React.FC<FleetLiveMapProps> = ({ wsUrl, sessionToken }) => {
  const mapContainerRef = useRef<HTMLDivElement>(null);
  const mapRef = useRef<L.Map | null>(null);
  const markersRef = useRef<Map<number, L.Marker>>(new Map());
  const trailsRef = useRef<Map<number, L.Polyline>>(new Map());

  const [vehicles, setVehicles] = useState<Map<number, VehiclePosition>>(new Map());
  const [selectedId, setSelectedId] = useState<number | null>(null);
  const [isConnected, setIsConnected] = useState<boolean>(false);

  // 1. Initialize Leaflet Map
  useEffect(() => {
    if (!mapContainerRef.current || mapRef.current) return;

    const map = L.map(mapContainerRef.current).setView([51.5074, -0.1278], 13);
    L.tileLayer('https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png', {
      maxZoom: 19,
      attribution: '© OpenStreetMap'
    }).addTo(map);

    mapRef.current = map;

    return () => {
      map.remove();
      mapRef.current = null;
    };
  }, []);

  // 2. Custom Marker Icon with Heading Rotation
  const createMarkerIcon = (course = 0, isValid = true) => {
    return L.divIcon({
      className: '',
      html: `
        
          
        
      `,
      iconSize: [20, 20],
      iconAnchor: [10, 10]
    });
  };

  // 3. Connect Realtime WebSocket Stream
  useEffect(() => {
    if (!sessionToken) return;

    const ws = new WebSocket(`${wsUrl}?token=${sessionToken}`);

    ws.onopen = () => setIsConnected(true);
    ws.onclose = () => setIsConnected(false);

    ws.onmessage = (event) => {
      try {
        const msg = JSON.parse(event.data);

        if (msg.type === 'snapshot') {
          setVehicles((prev) => {
            const next = new Map(prev);
            const pts: [number, number][] = [];

            msg.positions.forEach((p: any) => {
              const posData: VehiclePosition = {
                id: p.vehicle_id,
                lat: p.lat,
                lon: p.lon,
                speedKn: p.speed_kn,
                course: p.course,
                valid: p.valid
              };
              next.set(p.vehicle_id, posData);
              pts.push([p.lat, p.lon]);
              updateMarker(p.vehicle_id, posData);
            });

            if (mapRef.current && pts.length) {
              mapRef.current.fitBounds(pts, { padding: [50, 50] });
            }
            return next;
          });
        } else if (msg.type === 'position') {
          const vid = msg.vehicleId;
          const pos = msg.position;
          const posData: VehiclePosition = {
            id: vid,
            lat: pos.lat,
            lon: pos.lon,
            speedKn: pos.speedKn,
            course: pos.course,
            valid: pos.valid
          };

          setVehicles((prev) => {
            const next = new Map(prev);
            next.set(vid, { ...next.get(vid), ...posData });
            return next;
          });

          updateMarker(vid, posData);
        }
      } catch (err) {
        console.error('Error parsing telematics frame:', err);
      }
    };

    return () => {
      ws.close();
    };
  }, [wsUrl, sessionToken]);

  // 4. Update Leaflet Marker & Trail Line
  const updateMarker = (vid: number, pos: VehiclePosition) => {
    if (!mapRef.current) return;
    const latLng: [number, number] = [pos.lat, pos.lon];

    let marker = markersRef.current.get(vid);
    if (!marker) {
      marker = L.marker(latLng, { icon: createMarkerIcon(pos.course, pos.valid) }).addTo(mapRef.current);
      marker.on('click', () => handleFocus(vid));
      markersRef.current.set(vid, marker);
    } else {
      marker.setLatLng(latLng);
      marker.setIcon(createMarkerIcon(pos.course, pos.valid));
    }

    const speedKmh = Math.round((pos.speedKn || 0) * 1.852);
    marker.bindPopup(`
      
        Vehicle #${vid}

        Speed: ${speedKmh} km/h

        Heading: ${pos.course || 0}°

        Coords: ${pos.lat.toFixed(5)}, ${pos.lon.toFixed(5)}
      
    `);

    let trail = trailsRef.current.get(vid);
    if (!trail) {
      trail = L.polyline([latLng], { color: '#38bdf8', weight: 3, dashArray: '5,5' }).addTo(mapRef.current);
      trailsRef.current.set(vid, trail);
    } else {
      trail.addLatLng(latLng);
    }
  };

  const handleFocus = (vid: number) => {
    setSelectedId(vid);
    const v = vehicles.get(vid);
    if (v && mapRef.current) {
      mapRef.current.flyTo([v.lat, v.lon], 16, { duration: 1.2 });
      const m = markersRef.current.get(vid);
      if (m) m.openPopup();
    }
  };

  return (
    
      {/* Fleet Sidebar */}
      
        
          ERP Fleet Live Map
          
            {isConnected ? 'LIVE' : 'DISCONNECTED'}
          
        
        
          {Array.from(vehicles.values()).map((v) => {
            const speedKmh = Math.round((v.speedKn || 0) * 1.852);
            return (
               handleFocus(v.id)}
                style={{
                  background: selectedId === v.id ? '#172554' : '#0f172a',
                  border: `1px solid ${selectedId === v.id ? '#38bdf8' : '#334155'}`,
                  borderRadius: '8px',
                  padding: '12px',
                  marginBottom: '8px',
                  cursor: 'pointer'
                }}
              >
                
                  Vehicle #{v.id}
                  {speedKmh} km/h
                
                
                  {v.plate || 'No Plate'}
                  {v.course || 0}° Heading
                
              
            );
          })}
        
      

      {/* Map Viewport */}
      
        
      
    
  );
};

import { Component, OnInit, OnDestroy, ElementRef, ViewChild, Input } from '@angular/core';
import { CommonModule } from '@angular/common';
import * as L from 'leaflet';

interface VehiclePosition {
  id: number;
  name?: string;
  plate?: string;
  lat: number;
  lon: number;
  speedKn: number;
  course: number;
  valid: boolean;
}

@Component({
  selector: 'app-fleet-live-map',
  standalone: true,
  imports: [CommonModule],
  template: `
    
      
      
        
          ERP Fleet Telematics
          
            {{ isConnected ? 'LIVE' : 'DISCONNECTED' }}
          
        
        
          
            
              {{ v.name || 'Vehicle #' + v.id }}
              {{ getKmh(v.speedKn) }} km/h
            
            
              {{ v.plate || 'No Plate' }}
              {{ v.course || 0 }}° Heading
            
          
        
      

      
      
        
      
    
  `,
  styles: [`
    .map-layout { display: flex; width: 100%; height: 100vh; background: #0f172a; color: #f8fafc; font-family: sans-serif; }
    .sidebar { width: 320px; background: #1e293b; border-right: 1px solid #334155; display: flex; flex-direction: column; }
    .sidebar-header { padding: 16px; border-bottom: 1px solid #334155; display: flex; justify-content: space-between; align-items: center; }
    .sidebar-header h3 { margin: 0; font-size: 1rem; color: #38bdf8; }
    .status-pill { font-size: 0.7rem; padding: 2px 8px; border-radius: 9999px; font-weight: 600; }
    .status-pill.online { background: #065f46; color: #34d399; }
    .status-pill.offline { background: #7f1d1d; color: #f87171; }
    .vehicle-list { flex: 1; overflow-y: auto; padding: 12px; }
    .vehicle-card { background: #0f172a; border: 1px solid #334155; border-radius: 8px; padding: 12px; margin-bottom: 8px; cursor: pointer; }
    .vehicle-card.active, .vehicle-card:hover { border-color: #38bdf8; background: #172554; }
    .title-row { display: flex; justify-content: space-between; font-weight: 600; font-size: 0.9rem; margin-bottom: 4px; }
    .meta-row { display: flex; justify-content: space-between; font-size: 0.75rem; color: #94a3b8; }
    .map-container { flex: 1; height: 100%; position: relative; }
    .map-viewport { width: 100%; height: 100%; }
  `]
})
export class FleetLiveMapComponent implements OnInit, OnDestroy {
  @Input() wsUrl: string = 'wss://api.yourtrackinghost.com/ws';
  @Input() sessionToken: string = '';

  @ViewChild('mapElement', { static: true }) mapElement!: ElementRef;

  private map!: L.Map;
  private ws!: WebSocket;
  private markers = new Map();
  private trails = new Map();

  vehicles = new Map();
  selectedId: number | null = null;
  isConnected = false;

  get vehiclesList(): VehiclePosition[] {
    return Array.from(this.vehicles.values());
  }

  ngOnInit(): void {
    this.initMap();
    this.connectWebSocket();
  }

  ngOnDestroy(): void {
    if (this.ws) this.ws.close();
    if (this.map) this.map.remove();
  }

  getKmh(knots: number): number {
    return Math.round((knots || 0) * 1.852);
  }

  private initMap(): void {
    this.map = L.map(this.mapElement.nativeElement).setView([51.5074, -0.1278], 13);
    L.tileLayer('https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png', {
      maxZoom: 19,
      attribution: '© OpenStreetMap'
    }).addTo(this.map);
  }

  private createMarkerIcon(course = 0, isValid = true): L.DivIcon {
    return L.divIcon({
      className: '',
      html: `
        
          
        
      `,
      iconSize: [20, 20],
      iconAnchor: [10, 10]
    });
  }

  private connectWebSocket(): void {
    if (!this.sessionToken) return;

    this.ws = new WebSocket(`${this.wsUrl}?token=${this.sessionToken}`);

    this.ws.onopen = () => { this.isConnected = true; };
    this.ws.onclose = () => {
      this.isConnected = false;
      setTimeout(() => this.connectWebSocket(), 4000);
    };

    this.ws.onmessage = (event) => {
      try {
        const msg = JSON.parse(event.data);
        if (msg.type === 'snapshot') {
          const pts: [number, number][] = [];
          msg.positions.forEach((p: any) => {
            const pos: VehiclePosition = {
              id: p.vehicle_id,
              lat: p.lat,
              lon: p.lon,
              speedKn: p.speed_kn,
              course: p.course,
              valid: p.valid
            };
            this.vehicles.set(p.vehicle_id, pos);
            pts.push([p.lat, p.lon]);
            this.updateMarker(p.vehicle_id, pos);
          });
          if (pts.length) this.map.fitBounds(pts, { padding: [50, 50] });
        } else if (msg.type === 'position') {
          const vid = msg.vehicleId;
          const pos: VehiclePosition = {
            id: vid,
            lat: msg.position.lat,
            lon: msg.position.lon,
            speedKn: msg.position.speedKn,
            course: msg.position.course,
            valid: msg.position.valid
          };
          this.vehicles.set(vid, { ...this.vehicles.get(vid), ...pos });
          this.updateMarker(vid, pos);
        }
      } catch (e) {
        console.error('WebSocket message parsing error:', e);
      }
    };
  }

  private updateMarker(vid: number, pos: VehiclePosition): void {
    const latLng: [number, number] = [pos.lat, pos.lon];
    let marker = this.markers.get(vid);

    if (!marker) {
      marker = L.marker(latLng, { icon: this.createMarkerIcon(pos.course, pos.valid) }).addTo(this.map);
      marker.on('click', () => this.focusVehicle(vid));
      this.markers.set(vid, marker);
    } else {
      marker.setLatLng(latLng);
      marker.setIcon(this.createMarkerIcon(pos.course, pos.valid));
    }

    const speedKmh = this.getKmh(pos.speedKn);
    marker.bindPopup(`
      
        Vehicle #${vid}

        Speed: ${speedKmh} km/h

        Heading: ${pos.course || 0}°

        Coords: ${pos.lat.toFixed(5)}, ${pos.lon.toFixed(5)}
      
    `);

    let trail = this.trails.get(vid);
    if (!trail) {
      trail = L.polyline([latLng], { color: '#38bdf8', weight: 3, dashArray: '5,5' }).addTo(this.map);
      this.trails.set(vid, trail);
    } else {
      trail.addLatLng(latLng);
    }
  }

  focusVehicle(vid: number): void {
    this.selectedId = vid;
    const v = this.vehicles.get(vid);
    if (v) {
      this.map.flyTo([v.lat, v.lon], 16, { duration: 1.2 });
      const m = this.markers.get(vid);
      if (m) m.openPopup();
    }
  }
}

04

Complete REST API Specification

All REST API endpoints accept and return JSON payloads (Content-Type: application/json). Cross-Origin Resource Sharing (CORS) is enabled platform-wide with permissive headers (*) for cross-domain server and worker communication.

POST /api/integration/register Unauthenticated (Admin Creds in Body)

Self-service registration endpoint for 3rd-party ERP systems. Authenticates using tenant administrator email and password to issue or rotate an integration API key. If the erpClientId already exists, its API key hash is updated, immediately revoking any previous key.

Request Body (JSON)

Field	Type	Required	Description
`erpClientId`	String	Yes	Unique identifier for the ERP installation (e.g. `"odoo-prod-east"`, `"sap-wms-01"`).
`email`	String	Yes	Email address of an active tenant administrator with role `admin`.
`password`	String	Yes	Plaintext password for the administrator account.

curl -X POST https://api.yourtrackinghost.com/api/integration/register \
  -H "Content-Type: application/json" \
  -d '{
    "erpClientId": "odoo-main",
    "email": "roshan@test.com",
    "password": "roshan123"
  }'

HTTP/1.1 201 Created
Content-Type: application/json

{
  "customerId": 2,
  "erpClientId": "odoo-main",
  "apiKey": "fk_7a2b9c3d4e5f60718293a4b5c6d7e8f9a0b1c2d3e4f5a6b7"
}

POST /api/integration/session API Key (Header or Body)

Mints a short-lived, signed JWT session token authorized strictly for a whitelisted set of vehicle IDs. Supports two credential styles: standard Bearer token in the Authorization header, or direct apiKey in the JSON body.

Request Body (JSON)

Field	Type	Required	Description
`erpClientId` / `clientId`	String	Yes	Must match the client ID bound to the integration key.
`apiKey`	String	Conditional	Required if not sending `Authorization: Bearer fk_...` header.
`vehicleIds`	Array<Integer>	Yes	List of vehicle IDs to track (max 500 IDs per session).
`sessionLengthSeconds` / `ttlSeconds`	Integer	No	Session duration in seconds (min 30, max 86400, default 300).

curl -X POST https://api.yourtrackinghost.com/api/integration/session \
  -H "Content-Type: application/json" \
  -d '{
    "erpClientId": "odoo-main",
    "apiKey": "fk_7a2b9c3d4e5f60718293a4b5c6d7e8f9a0b1c2d3e4f5a6b7",
    "vehicleIds": [2, 3, 4],
    "sessionLengthSeconds": 600
  }'

curl -X POST https://api.yourtrackinghost.com/api/integration/session \
  -H "Authorization: Bearer fk_7a2b9c3d4e5f60718293a4b5c6d7e8f9a0b1c2d3e4f5a6b7" \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": "odoo-main",
    "vehicleIds": [2, 3, 4],
    "ttlSeconds": 600
  }'

HTTP/1.1 200 OK
Content-Type: application/json

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "vehicleIds": [2, 3, 4],
  "expiresIn": 600,
  "expiresAt": "2026-08-21T10:45:00.000Z",
  "wsUrl": "/ws?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

GET /api/integration/vehicles Bearer fk_... or x-api-key

Lists all vehicles belonging to the customer tenant associated with the API key. Used by ERP synchronization jobs to map internal fleet assets to tracking IDs and device IMEIs.

GET /api/integration/vehicles

curl -X GET https://api.yourtrackinghost.com/api/integration/vehicles \
  -H "Authorization: Bearer fk_7a2b9c3d4e5f60718293a4b5c6d7e8f9a0b1c2d3e4f5a6b7"

HTTP/1.1 200 OK
Content-Type: application/json

[
  { "id": 2, "name": "Van 12", "plate": "BK-4412", "imei": "867421030123456" },
  { "id": 3, "name": "Van 04", "plate": "BK-4401", "imei": "867421030123457" },
  { "id": 4, "name": "Truck 2", "plate": "TL-8821", "imei": "867421030123458" }
]

POST GET /api/integration/keys | /:id/revoke Bearer Admin JWT

Administrative management endpoints for creating, inspecting, and revoking API keys from the web dashboard or management scripts.

POST /api/integration/keys: Creates key with {"name":"...", "clientId":"..."}. Returns key once.
GET /api/integration/keys: Returns active and revoked keys with creation and revocation timestamps.
POST /api/integration/keys/:id/revoke: Revokes key instantly (HTTP 204 No Content).

GET POST /api/vehicles Bearer User / Admin JWT

Lists vehicles accessible to the authenticated identity, including their most recent telemetry report and any target destination coordinates.

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "id": 2,
    "name": "Van 12",
    "plate": "BK-4412",
    "imei": "867421030123456",
    "destination": { "lat": 51.5150, "lon": -0.1410 },
    "position": {
      "id": 8842,
      "recordedAt": "2026-08-21T10:15:30.123Z",
      "deviceTime": "2026-08-21T10:15:22.000Z",
      "valid": true,
      "lat": 51.5074,
      "lon": -0.1278,
      "speedKn": 14.2,
      "course": 88.5
    }
  }
]

GET /api/vehicles/:id/positions Bearer User / Admin JWT

Retrieves historical GPS trail records for route playback, speed profiling, and delivery compliance auditing.

Query Parameters

Parameter	Type	Default	Description
`from`	ISO Date / Epoch ms	Now - 6 hours	Start of temporal window.
`to`	ISO Date / Epoch ms	Now	End of temporal window (max 30 days range).

PATCH /api/vehicles/:id/destination Bearer Admin JWT

Assigns or clears navigation destination coordinates for a vehicle. Used by dispatch ERPs to broadcast dynamic drop-off targets.

// Set Destination:
PATCH /api/vehicles/2/destination
{ "lat": 51.5150, "lon": -0.1410 } -> HTTP 204 No Content

// Clear Destination:
PATCH /api/vehicles/2/destination
{ "clear": true } -> HTTP 204 No Content

POST /api/routes/optimize Bearer User / Admin JWT

Solves the Traveling Salesperson Problem (TSP) using greedy nearest-neighbor Haversine geodesics. Takes 2 to 50 waypoint coordinates and returns the optimized sequence index array and total kilometers.

POST /api/routes/optimize
{
  "waypoints": [
    [51.5074, -0.1278],
    [51.5200, -0.1000],
    [51.5100, -0.1500]
  ]
}

HTTP/1.1 200 OK
{
  "order": [0, 2, 1],
  "totalKm": 6.8,
  "points": [
    [51.5074, -0.1278],
    [51.5100, -0.1500],
    [51.5200, -0.1000]
  ]
}

GET POST /api/geofences | /:id/assign Bearer Admin JWT

Manages circular spatial geofences (center WGS84 point + radius in meters) and assigns vehicles to active monitoring zones.

GET /api/geofences: Lists all tenant geofences with center lat, lon, radius_m, and vehicleIds.
POST /api/geofences: Creates geofence with {"name":"Warehouse Zone", "lat":51.5074, "lon":-0.1278, "radiusM":500, "vehicleIds":[2,3]}.
POST /api/geofences/:id/assign & DELETE /api/geofences/:id/assign: Links or unlinks vehicle with {"vehicleId": 2}.

GET /api/alerts Bearer User / Admin JWT

Queries historical security and spatial boundary events (enter, exit, offline, online) for the authenticated tenant. Supports limit query parameter (max 200).

GET POST /api/users | /api/vehicles/:id/assign Bearer Admin JWT

Enables tenant administrators to provision standard driver/viewer accounts and grant granular vehicle visibility permissions.

GET POST /api/invoices | /api/invoices/:id/pay Bearer Admin / Super Admin JWT

Exposes automated billing records generated by the periodic invoice scheduler (every 12 hours). Enables ERP accounting reconciliation and status updates.

05

Real-Time WebSocket Protocol Specification

WebSocket Connection Lifecycle

The platform provides low-latency push delivery over standard RFC 6455 WebSockets. ERP clients connect by appending their signed session token as a URL query parameter:

WebSocket Connection URL

wss://api.yourtrackinghost.com/ws?token=<session-jwt-token>

WebSocket Message Frame Types

FRAME 1 Snapshot Frame (Sent Immediately on Connect)

Provides the current last-known state of all vehicles whitelisted in the session token. Vehicles that have not yet reported are omitted. Note that raw DB snapshot keys use snake_case.

{
  "type": "snapshot",
  "positions": [
    {
      "vehicle_id": 2,
      "id": 8841,
      "recorded_at": "2026-08-21T10:14:02.123Z",
      "device_time": "2026-08-21T10:13:55.000Z",
      "valid": true,
      "lat": 51.5074,
      "lon": -0.1278,
      "speed_kn": 12.4,
      "course": 90.0
    }
  ]
}

FRAME 2 Position Frame (Live GPS Report)

Pushed in real time whenever an incoming device datagram is ingested. Position frames use camelCase property formatting.

{
  "type": "position",
  "vehicleId": 2,
  "position": {
    "id": 8842,
    "recordedAt": "2026-08-21T10:14:17.654Z",
    "deviceTime": "2026-08-21T10:14:10.000Z",
    "valid": true,
    "lat": 51.5081,
    "lon": -0.1269,
    "speedKn": 13.7,
    "course": 91.2
  }
}

FRAME 3 Alert Frame (Geofence / Offline Event)

Pushed immediately when a spatial transition or stale timeout occurs. Alert type values: enter, exit, offline, online.

{
  "type": "alert",
  "alert": {
    "id": 77,
    "customer_id": 2,
    "vehicle_id": 2,
    "geofence_id": 5,
    "type": "enter",
    "message": "Van 12 entered Distribution Depot",
    "lat": 51.5074,
    "lon": -0.1278,
    "created_at": "2026-08-21T10:14:17.654Z",
    "resolved_at": null
  }
}

Telemetry Units & Conversion Reference

Field	Units	Conversion Formula	Description
`lat`, `lon`	Decimal Degrees (WGS84)	`lat: ±90.0`, `lon: ±180.0`	Geodetic coordinates. Negative values indicate South / West hemispheres.
`speedKn` / `speed_kn`	Knots (Nautical Miles/hr)	`km/h = knots * 1.852` `mph = knots * 1.15078`	Instantaneous ground speed calculated by the GPS chip.
`course`	Degrees (0.0° – 360.0°)	`0°=North, 90°=East, 180°=South, 270°=West`	True heading relative to true geographic North.
`valid`	Boolean (`true` \| `false`)	`true` = 3D Fix, `false` = Fix Lost	When `false`, coordinates represent last known cached position.
`deviceTime`	ISO 8601 UTC	`YYYY-MM-DDTHH:mm:ss.sssZ`	GPS satellite timestamp as reported by the tracker hardware.
`recordedAt`	ISO 8601 UTC	`YYYY-MM-DDTHH:mm:ss.sssZ`	Ingestion timestamp when server received the frame.

06

Webhook & Out-of-Band Notifications

Automated Event Webhook Delivery

In addition to WebSocket streaming, the telematics platform supports direct HTTP POST webhook dispatching to external ERP endpoints whenever geofence transitions or vehicle offline/online events occur.

Webhook JSON Payload (HTTP POST)

{
  "type": "enter",
  "message": "Van 12 entered Distribution Depot",
  "vehicleId": 2,
  "geofenceId": 5,
  "lat": 51.5074,
  "lon": -0.1278,
  "at": "2026-08-21T10:14:17.654Z"
}

Webhook Receiver Best Practices:

Return an immediate HTTP 200 OK response within 2,000ms.
Offload heavy ERP operations (e.g. updating order statuses, triggering customer SMS alerts) to a background worker queue (Celery, Laravel Queue, RabbitMQ).
Design receiver idempotency using the combination of vehicleId, type, and at timestamp.

07

Sinotrack (H02 Protocol) Telematics Ingest

Raw TCP Ingest Engine (:9000)

Physical tracking units (such as Sinotrack ST-901, ST-902, ST-906) broadcast NMEA ASCII frames over persistent or connectionless TCP connections to port 9000.

Raw H02 ASCII Datagram:

*HQ,867421030123456,V1,101410,A,5130.4440,N,00007.6140,W,013.70,091,210826,FFFFFBFF,234,15,0,0#

Pos	Raw Value	Field Name	Description & Parsing Logic
1	`*HQ`	Header Marker	Fixed protocol identifier preamble.
2	`867421030123456`	Device IMEI	8 to 15 digit hardware IMEI identifier. Looked up in memory cache.
3	`V1`	Version Code	Protocol specification level.
4	`101410`	Time (HHMMSS)	10:14:10 UTC satellite time.
5	`A`	Fix Validity	`A` = Valid GPS lock, `V` = Void / Cell-tower estimate.
6–7	`5130.4440, N`	Latitude	`51° + (30.4440 / 60)' = 51.5074° N`
8–9	`00007.6140, W`	Longitude	`0° + (07.6140 / 60)' = -0.1269° W` (Negative sign for W/S)
10	`013.70`	Speed (Knots)	13.70 Knots (~25.37 km/h).
11	`091`	Heading	91° True East heading.
12	`210826`	Date (DDMMYY)	August 21, 2026.

Offline Stale-Vehicle Detector

The backend executes an offline evaluation tick every 60 seconds. If a vehicle has not emitted a valid report within OFFLINE_AFTER_MIN (default: 5 minutes), an offline alert is generated and dispatched via WebSocket and Webhook. Once the vehicle resumes transmission, the open offline alert is marked resolved (resolved_at = now()) and an online alert is emitted.

08

Production-Ready Multi-Language Integration SDKs

Copy-paste production implementations for ingesting live vehicle streams into your ERP background services, database layers, and web controllers.

<?php
namespace App\Services;

use Illuminate\Support\Facades\Http;
use Illuminate\Support\Facades\Log;
use WebSocket\Client;

/**
 * Enterprise Fleet Telematics Ingestion Service for Laravel / PHP
 */
class FleetTrackingService
{
    protected string $baseUrl;
    protected string $erpClientId;
    protected string $apiKey;

    public function __construct()
    {
        $this->baseUrl = config('services.telematics.url', 'https://api.yourtrackinghost.com');
        $this->erpClientId = config('services.telematics.client_id', 'odoo-prod');
        $this->apiKey = config('services.telematics.api_key', 'fk_...');
    }

    /**
     * Fetch active vehicle catalog
     */
    public function getVehicles(): array
    {
        $response = Http::withToken($this->apiKey)
            ->get("{$this->baseUrl}/api/integration/vehicles");

        if ($response->failed()) {
            Log::error("Failed to fetch vehicles: " . $response->body());
            throw new \Exception("Vehicle fetch failed: " . $response->status());
        }

        return $response->json();
    }

    /**
     * Mint a short-lived WebSocket session token
     */
    public function createSession(array $vehicleIds, int $ttlSeconds = 600): array
    {
        $response = Http::post("{$this->baseUrl}/api/integration/session", [
            'erpClientId'          => $this->erpClientId,
            'apiKey'               => $this->apiKey,
            'vehicleIds'           => $vehicleIds,
            'sessionLengthSeconds' => $ttlSeconds,
        ]);

        if ($response->failed()) {
            Log::error("Session creation failed: " . $response->body());
            throw new \Exception("Session minting error: " . $response->status());
        }

        return $response->json();
    }

    /**
     * Long-running stream worker daemon
     */
    public function runStreamDaemon(array $vehicleIds): void
    {
        while (true) {
            try {
                Log::info("Minting fresh session token for stream daemon...");
                $session = $this->createSession($vehicleIds, 600);
                
                $wsUrl = str_replace(['http://', 'https://'], ['ws://', 'wss://'], $this->baseUrl) 
                       . "/ws?token=" . $session['token'];

                $client = new Client($wsUrl, ['timeout' => 500]);
                Log::info("Connected to live telematics stream.");

                $connectedAt = time();
                // Renew connection at 80% of TTL (480 seconds)
                while (time() - $connectedAt < 480) {
                    $message = $client->receive();
                    if (!$message) continue;

                    $payload = json_decode($message, true);
                    $this->handleFrame($payload);
                }

                $client->close();
            } catch (\Exception $e) {
                Log::warning("WebSocket stream dropped: " . $e->getMessage() . ". Reconnecting in 5s...");
                sleep(5);
            }
        }
    }

    protected function handleFrame(array $frame): void
    {
        $type = $frame['type'] ?? '';
        if ($type === 'position') {
            $vehicleId = $frame['vehicleId'];
            $pos = $frame['position'];
            Log::debug("Position update: Vehicle #{$vehicleId} @ [{$pos['lat']}, {$pos['lon']}] Speed: {$pos['speedKn']} kn");
            // Update internal ERP database records or broadcast to WebSocket UI
        } elseif ($type === 'alert') {
            $alert = $frame['alert'];
            Log::warning("Fleet Alert: " . $alert['message']);
        } elseif ($type === 'snapshot') {
            Log::info("Snapshot received with " . count($frame['positions']) . " vehicle states.");
        }
    }
}

import asyncio
import json
import logging
import aiohttp
import websockets

logging.basicConfig(level=logging.INFO, format="%(asctime)s [%(levelname)s] %(message)s")

class FleetTrackingClient:
    def __init__(self, base_url: str, erp_client_id: str, api_key: str):
        self.base_url = base_url.rstrip('/')
        self.erp_client_id = erp_client_id
        self.api_key = api_key
        self.ws_base = self.base_url.replace('http://', 'ws://').replace('https://', 'wss://')

    async def get_vehicles(self):
        async with aiohttp.ClientSession() as session:
            headers = {"Authorization": f"Bearer {self.api_key}"}
            async with session.get(f"{self.base_url}/api/integration/vehicles", headers=headers) as resp:
                resp.raise_for_status()
                return await resp.json()

    async def mint_session(self, vehicle_ids: list, ttl_seconds: int = 600) -> dict:
        async with aiohttp.ClientSession() as session:
            payload = {
                "erpClientId": self.erp_client_id,
                "apiKey": self.api_key,
                "vehicleIds": vehicle_ids,
                "sessionLengthSeconds": ttl_seconds
            }
            async with session.post(f"{self.base_url}/api/integration/session", json=payload) as resp:
                resp.raise_for_status()
                return await resp.json()

    async def stream_live_telematics(self, vehicle_ids: list):
        while True:
            try:
                logging.info("Minting integration session token...")
                session_data = await self.mint_session(vehicle_ids, ttl_seconds=600)
                token = session_data["token"]
                ws_url = f"{self.ws_base}/ws?token={token}"

                logging.info(f"Connecting to WebSocket: {ws_url[:45]}...")
                async with websockets.connect(ws_url, ping_interval=20, ping_timeout=10) as ws:
                    logging.info("WebSocket connected successfully!")
                    
                    start_time = asyncio.get_event_loop().time()
                    # Run until 80% of TTL expires (480s)
                    while (asyncio.get_event_loop().time() - start_time) < 480:
                        try:
                            msg = await asyncio.wait_for(ws.recv(), timeout=30.0)
                            data = json.loads(msg)
                            self.on_message(data)
                        except asyncio.TimeoutError:
                            # Keepalive check
                            pass
                            
            except Exception as e:
                logging.error(f"Stream error: {e}. Reconnecting in 5 seconds...")
                await asyncio.sleep(5)

    def on_message(self, data: dict):
        msg_type = data.get("type")
        if msg_type == "position":
            vid = data["vehicleId"]
            pos = data["position"]
            logging.info(f"Vehicle #{vid} => Lat: {pos['lat']:.5f}, Lon: {pos['lon']:.5f}, Speed: {pos['speedKn']} kn, Course: {pos['course']}°")
        elif msg_type == "alert":
            alert = data["alert"]
            logging.warning(f"ALERT [{alert['type'].upper()}]: {alert['message']}")
        elif msg_type == "snapshot":
            logging.info(f"SNAPSHOT: Received initial states for {len(data.get('positions', []))} vehicles.")

if __name__ == "__main__":
    client = FleetTrackingClient("http://localhost:3000", "odoo-prod", "fk_7a2b9c3d4e5f60718293a4b5c6d7e8f9a0b1c2d3e4f5a6b7")
    asyncio.run(client.stream_live_telematics([2, 3, 4]))

import WebSocket from 'ws';
import { EventEmitter } from 'events';

export interface TelematicsPosition {
  id: number;
  recordedAt: string;
  deviceTime: string;
  valid: boolean;
  lat: number;
  lon: number;
  speedKn: number;
  course: number;
}

export class FleetTrackingClient extends EventEmitter {
  private baseUrl: string;
  private wsUrl: string;
  private erpClientId: string;
  private apiKey: string;
  private ws: WebSocket | null = null;
  private refreshTimer: NodeJS.Timeout | null = null;

  constructor(baseUrl: string, erpClientId: string, apiKey: string) {
    super();
    this.baseUrl = baseUrl.replace(/\/$/, '');
    this.wsUrl = this.baseUrl.replace(/^http/, 'ws');
    this.erpClientId = erpClientId;
    this.apiKey = apiKey;
  }

  async getVehicles(): Promise<any[]> {
    const res = await fetch(`${this.baseUrl}/api/integration/vehicles`, {
      headers: { Authorization: `Bearer ${this.apiKey}` }
    });
    if (!res.ok) throw new Error(`Fetch vehicles failed: ${res.statusText}`);
    return res.json();
  }

  async createSession(vehicleIds: number[], ttlSeconds = 600): Promise<string> {
    const res = await fetch(`${this.baseUrl}/api/integration/session`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        erpClientId: this.erpClientId,
        apiKey: this.apiKey,
        vehicleIds,
        sessionLengthSeconds: ttlSeconds
      })
    });
    if (!res.ok) throw new Error(`Mint session failed: ${await res.text()}`);
    const data = await res.json();
    return data.token;
  }

  async startStreaming(vehicleIds: number[]) {
    try {
      const token = await this.createSession(vehicleIds, 600);
      this.ws = new WebSocket(`${this.wsUrl}/ws?token=${token}`);

      this.ws.on('open', () => {
        this.emit('connected');
        // Proactively refresh connection after 480s (80% of TTL)
        this.refreshTimer = setTimeout(() => {
          this.ws?.close();
          this.startStreaming(vehicleIds);
        }, 480 * 1000);
      });

      this.ws.on('message', (raw: Buffer) => {
        try {
          const msg = JSON.parse(raw.toString());
          if (msg.type === 'position') this.emit('position', msg.vehicleId, msg.position);
          else if (msg.type === 'alert') this.emit('alert', msg.alert);
          else if (msg.type === 'snapshot') this.emit('snapshot', msg.positions);
        } catch (e) {
          this.emit('error', e);
        }
      });

      this.ws.on('close', (code) => {
        if (this.refreshTimer) clearTimeout(this.refreshTimer);
        this.emit('disconnected', code);
        // Automatic reconnect on unexpected drop
        setTimeout(() => this.startStreaming(vehicleIds), 5000);
      });

      this.ws.on('error', (err) => this.emit('error', err));
    } catch (err) {
      this.emit('error', err);
      setTimeout(() => this.startStreaming(vehicleIds), 5000);
    }
  }
}

using System;
using System.Net.Http;
using System.Net.Http.Json;
using System.Net.WebSockets;
using System.Text;
using System.Text.Json;
using System.Threading;
using System.Threading.Tasks;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;

public class FleetTrackingWorker : BackgroundService
{
    private readonly ILogger<FleetTrackingWorker> _logger;
    private readonly HttpClient _http;
    private readonly string _baseUrl = "https://api.yourtrackinghost.com";
    private readonly string _erpClientId = "dotnet-erp-prod";
    private readonly string _apiKey = "fk_...";

    public FleetTrackingWorker(ILogger<FleetTrackingWorker> logger, HttpClient http)
    {
        _logger = logger;
        _http = http;
    }

    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        int[] vehicleIds = new[] { 2, 3, 4 };

        while (!stoppingToken.IsCancellationRequested)
        {
            try
            {
                _logger.LogInformation("Minting session JWT token...");
                var sessionReq = new
                {
                    erpClientId = _erpClientId,
                    apiKey = _apiKey,
                    vehicleIds = vehicleIds,
                    sessionLengthSeconds = 600
                };

                var resp = await _http.PostAsJsonAsync($"{_baseUrl}/api/integration/session", sessionReq, stoppingToken);
                resp.EnsureSuccessStatusCode();
                var doc = await resp.Content.ReadFromJsonAsync<JsonElement>(cancellationToken: stoppingToken);
                string token = doc.GetProperty("token").GetString();

                string wsUrl = _baseUrl.Replace("http://", "ws://").Replace("https://", "wss://") + $"/ws?token={token}";
                using var ws = new ClientWebSocket();
                await ws.ConnectAsync(new Uri(wsUrl), stoppingToken);
                _logger.LogInformation("WebSocket connected to live telematics stream.");

                var buffer = new byte[4096];
                var startTime = DateTime.UtcNow;

                while (ws.State == WebSocketState.Open && (DateTime.UtcNow - startTime).TotalSeconds < 480)
                {
                    var result = await ws.ReceiveAsync(new ArraySegment<byte>(buffer), stoppingToken);
                    if (result.MessageType == WebSocketMessageType.Close) break;

                    string json = Encoding.UTF8.GetString(buffer, 0, result.Count);
                    using var frameDoc = JsonDocument.Parse(json);
                    string type = frameDoc.RootElement.GetProperty("type").GetString();

                    if (type == "position")
                    {
                        int vid = frameDoc.RootElement.GetProperty("vehicleId").GetInt32();
                        var pos = frameDoc.RootElement.GetProperty("position");
                        double lat = pos.GetProperty("lat").GetDouble();
                        double lon = pos.GetProperty("lon").GetDouble();
                        double speed = pos.GetProperty("speedKn").GetDouble();
                        _logger.LogInformation("Vehicle {Vid}: ({Lat}, {Lon}) at {Speed} knots", vid, lat, lon, speed);
                    }
                }
            }
            catch (Exception ex)
            {
                _logger.LogError(ex, "Stream error. Reconnecting in 5 seconds...");
                await Task.Delay(5000, stoppingToken);
            }
        }
    }
}

09

Database Schema & PostGIS Spatial Reference

Relational Data Model & PostGIS Extensions

The underlying database is PostgreSQL with the postgis extension enabled. Spatial points are generated dynamically from coordinates using ST_MakePoint(lon, lat) with SRID 4326.

PostgreSQL Schema (Core Entities)

-- Spatial Geometries & Telematics Tables
CREATE EXTENSION IF NOT EXISTS postgis;

CREATE TABLE customers (
  id         BIGSERIAL PRIMARY KEY,
  name       TEXT NOT NULL UNIQUE,
  plan_id    BIGINT REFERENCES plans(id),
  alert_email TEXT,
  alert_webhook TEXT,
  created_at TIMESTAMPTZ NOT NULL DEFAULT now()
);

CREATE TABLE vehicles (
  id          BIGSERIAL PRIMARY KEY,
  customer_id BIGINT NOT NULL REFERENCES customers(id) ON DELETE CASCADE,
  imei        TEXT NOT NULL UNIQUE,
  name        TEXT NOT NULL,
  plate       TEXT NOT NULL DEFAULT '',
  dest_lat    DOUBLE PRECISION,
  dest_lon    DOUBLE PRECISION,
  created_at  TIMESTAMPTZ NOT NULL DEFAULT now()
);
CREATE INDEX idx_vehicles_imei ON vehicles (imei);

CREATE TABLE positions (
  id          BIGSERIAL PRIMARY KEY,
  vehicle_id  BIGINT NOT NULL REFERENCES vehicles(id) ON DELETE CASCADE,
  recorded_at TIMESTAMPTZ NOT NULL DEFAULT now(),
  device_time TIMESTAMPTZ NOT NULL,
  valid       BOOLEAN NOT NULL,
  lat         DOUBLE PRECISION NOT NULL,
  lon         DOUBLE PRECISION NOT NULL,
  point       geography(Point,4326) GENERATED ALWAYS AS
                (ST_SetSRID(ST_MakePoint(lon, lat), 4326)::geography) STORED,
  speed_kn    DOUBLE PRECISION NOT NULL DEFAULT 0,
  course      DOUBLE PRECISION NOT NULL DEFAULT 0,
  raw_frame   TEXT NOT NULL
);
CREATE INDEX idx_positions_vehicle_devicetime ON positions (vehicle_id, device_time DESC);

CREATE TABLE geofences (
  id          BIGSERIAL PRIMARY KEY,
  customer_id BIGINT NOT NULL REFERENCES customers(id) ON DELETE CASCADE,
  name        TEXT NOT NULL,
  center      geography(Point,4326) NOT NULL,
  radius_m    DOUBLE PRECISION NOT NULL CHECK (radius_m > 0),
  created_at  TIMESTAMPTZ NOT NULL DEFAULT now()
);

CREATE TABLE integration_keys (
  id          BIGSERIAL PRIMARY KEY,
  customer_id BIGINT NOT NULL REFERENCES customers(id) ON DELETE CASCADE,
  name        TEXT NOT NULL,
  key_hash    TEXT NOT NULL UNIQUE,
  client_id   TEXT UNIQUE,
  created_at  TIMESTAMPTZ NOT NULL DEFAULT now(),
  revoked_at  TIMESTAMPTZ
);

10

Platform UI & Screenshot Gallery

Click any screenshot to expand in high resolution and inspect live telematics indicators, trail replay lines, and multi-tenant management portals.

Live Map Dashboard

Real-time vehicle markers, heading rotation, speed badges, and active state panel.

Route Replay & Movement Trail

Temporal breadcrumbs connecting GPS points for route adherence analysis.

Multi-Tenant Overview

Global fleet oversight across all provisioned client companies and tenancies.

Restricted User Workspace

Scoped dispatcher view displaying strictly assigned vehicles and routes.

Tenant & Billing Portal

Customer onboarding, webhook URLs, plan limits, and invoice tracking.

11

Troubleshooting, Error Reference & FAQ

Frequently Encountered Integration Questions

Q: Why did my WebSocket connection close with code 4001?

Close code 4001 (Unauthorized) indicates that the session token in the ?token= query parameter was omitted, malformed, or expired. Remember that session JWTs have an expiration timestamp (e.g. 300s or 600s). Re-mint a fresh token via POST /api/integration/session and reconnect.

Q: Can our ERP send a subscribe frame after connecting?

No. Integration sockets are bound strictly to the vehicle IDs cryptographically embedded in the session token during minting. Any subscribe or unsubscribe messages sent over integration sockets are ignored by design to prevent privilege escalation.

Q: What is the maximum number of vehicles per WebSocket session?

A single session token can whitelist up to 500 vehicles. If your fleet exceeds 500 units, partition your fleet into multiple concurrent sessions (e.g. grouped by region or vehicle type) across separate socket connections.

Q: How do we convert speed values to km/h and mph?

The raw GPS chip outputs speed in international nautical knots. Multiply by 1.852 to convert to kilometers per hour (km/h = knots * 1.852), or multiply by 1.15078 for miles per hour (mph = knots * 1.15078).

Q: How does the system handle vehicle reconnects after tunnel loss?

When a vehicle moves through a tunnel, cellular or GPS signal may drop. The device will mark valid: false on un-fixed frames. Once GPS lock is restored, the next valid frame updates coordinates and automatically resolves any open offline alert by emitting an online alert frame.

Live GPS Fleet Tracking — ERP Integration Manual

System Architecture & Integration Topology

Enterprise Platform Architecture

1. Ingestion Engine (:9000 TCP)

2. Spatial & Geofence Engine

3. ERP Stream Multiplexer

5-Minute ERP Integration Quickstart

Self-Register or Rotate API Key

Retrieve Vehicle Catalog & Map Internal IDs

Mint Short-Lived WebSocket Session Token

Connect WebSocket & Stream Real-Time Frames

Authentication & Security Architecture

Two-Tier Security Architecture

HTTP Status Codes & Security Errors

How to Mint & Manage Integration API Keys

Two Methods for Minting Integration API Keys

Key Revocation & Leak Recovery

Building a Live Telematics Map on Your Own ERP UI

Architecture: Secure Backend Proxy Pattern

Interactive Frontend Components (Plain HTML, React, Angular)

Complete REST API Specification

Request Body (JSON)

Request Body (JSON)

Query Parameters

Real-Time WebSocket Protocol Specification

WebSocket Connection Lifecycle

WebSocket Message Frame Types

Telemetry Units & Conversion Reference

Webhook & Out-of-Band Notifications

Automated Event Webhook Delivery

Webhook JSON Payload (HTTP POST)

Sinotrack (H02 Protocol) Telematics Ingest

Raw TCP Ingest Engine (:9000)

Offline Stale-Vehicle Detector

Production-Ready Multi-Language Integration SDKs

Database Schema & PostGIS Spatial Reference

Relational Data Model & PostGIS Extensions

Platform UI & Screenshot Gallery

Live Map Dashboard

Route Replay & Movement Trail

Multi-Tenant Overview

Restricted User Workspace

Tenant & Billing Portal

Troubleshooting, Error Reference & FAQ

Frequently Encountered Integration Questions

Q: Why did my WebSocket connection close with code 4001?

Q: Can our ERP send a subscribe frame after connecting?

Q: What is the maximum number of vehicles per WebSocket session?

Q: How do we convert speed values to km/h and mph?

Q: How does the system handle vehicle reconnects after tunnel loss?