Tractors API

​

Overview

• vehicle_id - Terminal API vehicle ID (e.g., vcl_xxx)
• mcleod_tractor_id - McLeod tractor ID (e.g., 735)
• latitude, longitude - GPS coordinates
• fault_codes - PostgreSQL TEXT[] array of fault code descriptions

• Terminal API provides vehicles with IDs like vcl_01D8ZQFGHVJ858NBF2Q7DV9MNC
• McLeod TMS uses tractor IDs like 735
• The mapping service connects these two systems by normalizing vehicle names

​

Sync Tractor Mapping

​

POST /api/tractors/sync-mapping

{
  "terminal_vehicles_fetched": 100,
  "mcleod_tractors_found": 75,
  "mappings_created": 60,
  "ambiguous_mappings": 5,
  "errors": 0,
  "ambiguous_names": ["Tractor 123 (Unit A)", "Tractor 123 (Unit B)"]
}

1. Fetch Terminal Vehicles: Calls Terminal API /tsp/v1/vehicles to get all vehicles
2. Normalize Names: Extracts tractor numbers from vehicle names:
   • “Tractor 735” → “735”
   • “TRK-00735” → “735”
   • “Truck #0735” → “735”
3. Get McLeod Tractors: Queries movements table for distinct __tractorid values
4. Match: Compares normalized numbers to McLeod tractor IDs
5. Update Database: Calls update_tractor_mapping() to set mcleod_tractor_id for matching vehicles
6. Handle Ambiguity: If multiple Terminal vehicles normalize to the same number, mapping is skipped and logged

• Extracts last contiguous digits from vehicle name
• Removes leading zeros
• Example: “FLEET-TRUCK-00735-WEST” → “735”

​

Sync All Vehicle Names

​

POST /api/tractors/sync-vehicle-names

{
  "success": true,
  "message": "Terminal vehicle names synced to mcleod_tractor_id successfully",
  "data": {
    "vehicles_fetched": 120,
    "vehicles_updated": 115,
    "errors": 5
  }
}

1. Fetches all vehicles from Terminal API /tsp/v1/vehicles
2. For each vehicle, sets tractors.mcleod_tractor_id = vehicle.name
3. Uses update_tractor_mcleod_id_from_terminal_name() which:
   • Updates existing tractor if vehicle_id matches
   • Creates new tractor record if not found

• sync-mapping: Only updates tractors with matching movements (selective)
• sync-vehicle-names: Updates ALL tractors with Terminal vehicle names (comprehensive)

​

Get Mapping Stats

​

GET /api/tractors/mapping-stats

{
  "total_tractors": 120,
  "mcleod_mapped_count": 110,
  "terminal_mapped_count": 105,
  "fully_mapped_count": 98,
  "unmapped_count": 10,
  "mcleod_mapped_percentage": 91.67,
  "terminal_mapped_percentage": 87.5,
  "fully_mapped_percentage": 81.67,
  "needs_sync": true
}

1. Queries tractors table with SQL aggregation
2. Uses CASE statements to count mapping states
3. Calculates percentages and needs_sync threshold
4. Calls get_tractor_mapping_count_metrics() and get_tractor_mapping_health()

​

Sync Fault Codes

​

POST /api/tractors/fault-codes/sync

{
  "success": true,
  "message": "Fault codes synced successfully",
  "data": {
    "fetched": 25,
    "synced": 20,
    "errors": 5
  }
}

1. Calls Motive API /v1/vehicle_diagnostics/fault_codes via MotiveClient
2. For each fault code, extracts description field
3. Matches fault codes to tractors via mcleod_id
4. Appends descriptions to tractors.fault_codes PostgreSQL array via append_fault_codes_to_tractor()
5. Deduplicates entries (won’t add same description twice)

Motive API (/v1/vehicle_diagnostics/fault_codes)
         ↓
MotiveClient.get_fault_codes()
         ↓
sync_fault_codes() service
         ↓
append_fault_codes_to_tractor() → tractors.fault_codes (TEXT[] array)

​

Get Fault Codes

​

GET /api/tractors/fault-codes

{
  "vehicle_id": "vcl_01D8ZQFGHVJ858NBF2Q7DV9MNC",
  "fault_codes": [
    "Engine coolant temperature above threshold",
    "Exhaust gas recirculation valve position sensor",
    "Diesel particulate filter regeneration required"
  ]
}

1. Queries tractors table by vehicle_id
2. Returns fault_codes array (PostgreSQL TEXT[])
3. Handles backward compatibility with JSON and comma-separated string formats
4. Returns 404 if tractor not found

​

Data Model

​

Tractors Table Schema

​

Location Provider Priority

1. Terminal GPS (authoritative): Updated by LocationPollingService every 60 seconds
2. Movement Stop Fallback: When Terminal GPS unavailable, uses stop coordinates from McLeod movements