Skip to content

Roadside Assistance (RSA) API Developer Guide

Service Overview

Roadside Assistance (RSA) is a telematics service that provides emergency support services through the call center when a vehicle stops on the roadside due to breakdowns or problems during vehicle operation.

Service Features

  • Remote status diagnosis for vehicle breakdowns
  • Accurate location-based emergency dispatch support
  • Response to various breakdown situations (battery, tires, fuel, etc.)
  • Real-time dispatch service coordination
  • Improved customer satisfaction
  • Lower priority than eCall/SOS
  • Compliance with personal information protection laws
  • Consent for vehicle breakdown information collection
  • Compliance with dispatch service contract conditions

Key Scenarios

Scenario 1: RSA Request and Data Collection

API Flow by Entity:

📱 App (User):

  1. RSA Request: Select RSA button to trigger help
  2. Monitoring: Receive RSA status via SSE
  3. Emergency Call: Immediate voice call connection with call center

🚗 Vehicle (TCU):

  1. Event Reception: Receive RSA button signal from app or vehicle
  2. Data Transmission: Transmit RSA notification data to server

🏢 Call Center:

  1. Event Monitoring: Monitor real-time RSA requests
  2. Consultation: Conduct professional consultation based on diagnosis information
  3. Dispatch Request: Request dispatch to appropriate partner

Scenario 2: Consultation and Partner Dispatch Processing

API Flow by Entity:

🏢 Call Center:

  1. Voice Consultation Progress: Conduct consultation based on vehicle status information
  2. Customer Consent Check: Check dispatch service consent
  3. Partner Dispatch Request: Request dispatch to appropriate partner
  4. Partner Response Processing: Receive partner ticket ID and update status
  5. Real-time Notification Transmission: Transmit dispatch acceptance and ETA information via SSE

🚗 Vehicle (TCU):

  1. Voice Call Maintenance: Maintain voice call during consultation progress
  2. Status Information Transmission: Continuous transmission of vehicle status information
  3. Location Information Provision: Provide accurate vehicle location information
  4. Dispatch Information Reception: Receive partner dispatch information
  5. Waiting Status Maintenance: Maintain waiting status until partner arrival

📱 App (User App):

  1. Real-time Status Reception: Receive dispatch processing status via SSE
  2. Partner Information Check: Check dispatch partner information and ETA
  3. Location Information Display: Display vehicle location and partner location on map
  4. Call Connection Maintenance: Maintain call connection with call center
  5. Service Progress Check: Check real-time service progress status

Scenario 3: Service Completion and Incident Closure

API Flow by Entity:

🏢 Call Center:

  1. Incident Closure: Close RSA incident after service completion
  2. Service Completion: Confirm partner service completion
  3. Status Update: Update RSA record status to "CLOSED"

📱 App (User):

  1. Result Check: Check final service result
  2. History Query: Check completed service history

Scenario 4: RSA Management and Statistics Processing

API Flow by Entity:

🏢 Call Center:

  1. Statistics Query: Query RSA service statistics
  2. Status Query: Query specific incident status
  3. History Query: Query past RSA service history
  4. Partner Confirmation: Confirm partner dispatch
  5. Performance Query: Query agent performance

🚗 Vehicle (TCU):

  1. Data Log Storage: Store diagnosis data and service logs
  2. Status History Management: Manage RSA-related status change history
  3. System Health Status: Maintain connection status with RSA system
  4. Data Synchronization: Synchronize with service data server

📱 App (User App):

  1. Service History Check: Check past RSA service history
  2. Statistics Information Query: Check RSA service-related statistics information
  3. Status Monitoring: Monitor current RSA service status
  4. Notification Settings Management: Manage RSA-related notification settings

Key Features

📱 Features to Implement in App

1. RSA Request and Monitoring


🏢 Features to Implement in Call Center

1. RSA Incident Management

2. System and Performance Analysis

Sequence Diagram

RSA (Roadside Assistance) System Flow

RSA

API Endpoints

RSA Dispatch Request

bash
curl -X POST "https://api.ecarus.run/api/v1/safety/vehicles/KMHSH81C7LU123456/rsa/dispatch" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d" \
     -H "Content-Type: application/json" \
     -d '{
       "cid": "RSA_20260307_001",
       "partner": "SAMSUNG_FIRE",
       "serviceType": "TOWING",
       "priority": "NORMAL",
       "destination": { "name": "Gangnam Center", "address": "Seoul...", "latitude": 37.5, "longitude": 127.0 },
       "customerConsent": { "granted": true, "timestamp": "2026-03-07T10:00:00Z", "recorded": true }
     }'

Partner Dispatch Confirmation

bash
curl -X POST "https://api.ecarus.run/api/v1/safety/partners/SAMSUNG_FIRE/dispatch/confirm" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d" \
     -H "Content-Type: application/json" \
     -d '{
       "cid": "RSA_20260307_001",
       "partnerTicketId": "SFT_12345",
       "status": "CONFIRMED",
       "provider": { "name": "FastTow" },
       "estimatedArrival": "2026-03-07T10:30:00Z"
     }'

RSA Incident Closure

bash
curl -X POST "https://api.ecarus.run/api/v1/safety/vehicles/KMHSH81C7LU123456/rsa/close" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d" \
     -H "Content-Type: application/json" \
     -d '{
       "cid": "RSA_20260307_001",
       "result": "TOWING_COMPLETED",
       "completionTime": "2026-03-07T12:00:00Z",
       "agentId": "AGENT_001",
       "notes": "Successfully towed to service center.",
       "partnerTicketId": "SFT_12345",
       "actualCost": 80000,
       "followUpRequired": false
     }'

RSA Incident Status Query

bash
curl -X GET "https://api.ecarus.run/api/v1/safety/vehicles/KMHSH81C7LU123456/rsa/status?cid=RSA_20260307_001" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d"

RSA Incident History Query

bash
curl -X GET "https://api.ecarus.run/api/v1/safety/vehicles/KMHSH81C7LU123456/rsa/history" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d"

RSA Service Statistics Query

bash
curl -X GET "https://api.ecarus.run/api/v1/safety/rsa/stats" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d"

Partner Service Completion

bash
curl -X POST "https://api.ecarus.run/api/v1/safety/partners/:partner/service/complete" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d" \
     -H "Content-Type: application/json" \
     -d '{
       "cid": "RSA_20260307_001",
       "partnerTicketId": "SFT_12345",
       "status": "COMPLETED",
       "completionTime": "2026-03-07T12:00:00Z",
       "actualCost": 80000,
       "serviceDetails": {
         "serviceType": "TOWING",
         "distance": 15.2,
         "destination": "Gangnam Service Center"
       }
     }'

Agent RSA Results Query

bash
curl -X GET "https://api.ecarus.run/api/v1/safety/rsa/agents/AGENT_001/performance" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d"

RSA Processing Status Real-time Query (SSE)

Note: Recommended to access via browser or use a dedicated SSE client

bash
curl -N -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d" \
     "https://api.ecarus.run/api/v1/safety/rsa/events"

Data Models

RSA Dispatch Request

json
{
  "cid": "RSA_20260307_001",
  "vin": "KMHSH81C7LU123456",
  "partner": "SAMSUNG_FIRE",
  "serviceType": "TOWING",
  "priority": "NORMAL",
  "breakdownLocation": {
    "address": "Seoul Gangnam-gu...",
    "latitude": 37.5,
    "longitude": 127.0,
    "description": "Near intersection..."
  },
  "destination": {
    "name": "Gangnam Service Center",
    "address": "Seoul Gangnam-gu...",
    "latitude": 37.5,
    "longitude": 127.0,
    "phone": "02-1234-5678"
  },
  "vehicleInfo": {
    "make": "HYUNDAI",
    "model": "SONATA",
    "year": 2020,
    "color": "WHITE",
    "licensePlate": "12GA3456"
  },
  "breakdownDetails": {
    "symptoms": ["ENGINE_START_FAILURE"],
    "description": "Vehicle won't start, clicking sound",
    "dtcCodes": ["P1234"],
    "batteryVoltage": 11.8
  },
  "customerInfo": {
    "name": "Hong Gildong",
    "phone": "010-1234-5678",
    "membershipId": "HM2024001234"
  },
  "customerConsent": {
    "granted": true,
    "timestamp": "2026-03-07T10:00:00Z",
    "locationSharing": true,
    "vehicleStatusSharing": true,
    "recorded": true
  },
  "requestTime": "2026-03-07T10:00:00Z",
  "notes": "Customer is waiting with family"
}

RSA Dispatch Response

json
{
  "cid": "RSA_20260307_001",
  "status": "DISPATCHED",
  "timestamp": "2026-03-07T10:05:00Z",
  "partner": "SAMSUNG_FIRE",
  "partnerTicketId": "SFT_12345",
  "provider": {
    "id": "PROV_001",
    "name": "FastTow",
    "phone": "02-9876-5432",
    "vehicleType": "TOW_TRUCK",
    "licensePlate": "88NA6789"
  },
  "estimatedArrival": "2026-03-07T10:30:00Z",
  "estimatedDuration": "25 min",
  "dispatchLocation": {
    "address": "Seoul Gangnam-gu...",
    "latitude": 37.5,
    "longitude": 127.0
  },
  "costEstimate": {
    "baseFee": 50000,
    "additionalFee": 0,
    "totalEstimate": 50000,
    "currency": "KRW"
  }
}

Partner Dispatch Confirmation Request

json
{
  "cid": "RSA_20260307_001",
  "partnerTicketId": "SFT_12345",
  "status": "CONFIRMED",
  "provider": {
    "id": "PROV_001",
    "name": "FastTow",
    "phone": "02-9876-5432",
    "driver": {
      "name": "Kim Cheolsu",
      "phone": "010-1111-2222",
      "licenseNumber": "12-34-567890"
    },
    "vehicle": {
      "type": "TOW_TRUCK",
      "licensePlate": "88NA6789",
      "capacity": "3.5T"
    }
  },
  "estimatedArrival": "2026-03-07T10:30:00Z",
  "currentLocation": {
    "latitude": 37.48,
    "longitude": 126.98,
    "address": "Seoul Seocho-gu..."
  },
  "estimatedDistance": 8.5,
  "confirmationTime": "2026-03-07T10:10:00Z"
}

Partner Dispatch Confirmation Response

json
{
  "cid": "RSA_20260307_001",
  "partnerTicketId": "SFT_12345",
  "status": "CONFIRMED",
  "timestamp": "2026-03-07T10:10:00Z"
}

RSA Closure Request

json
{
  "cid": "RSA_20260307_001",
  "vin": "KMHSH81C7LU123456",
  "result": "TOWING_COMPLETED",
  "completionTime": "2026-03-07T12:00:00Z",
  "agentId": "AGENT_001",
  "partnerTicketId": "SFT_12345",
  "provider": {
    "id": "PROV_001",
    "name": "FastTow",
    "driver": {
      "name": "Kim Cheolsu",
      "phone": "010-1111-2222"
    }
  },
  "serviceDetails": {
    "serviceType": "TOWING",
    "actualDistance": 15.2,
    "serviceDuration": "1 hour 45 min",
    "pickupLocation": "Seoul Gangnam-gu...",
    "dropoffLocation": "Gangnam Service Center",
    "specialEquipment": ["WHEEL_LIFT"]
  },
  "costDetails": {
    "baseFee": 50000,
    "distanceFee": 30000,
    "additionalFee": 0,
    "discount": 0,
    "totalCost": 80000,
    "currency": "KRW",
    "paymentMethod": "MEMBERSHIP",
    "billingStatus": "PAID"
  },
  "customerFeedback": {
    "satisfaction": 5,
    "comments": "Quick and professional service",
    "recommendation": true
  },
  "notes": "Successfully towed to service center. Customer satisfied.",
  "followUpRequired": false
}

RSA Closure Response

json
{
  "cid": "RSA_20260307_001",
  "status": "CLOSED",
  "timestamp": "2026-03-07T12:05:00Z",
  "summary": {
    "serviceType": "TOWING",
    "duration": "2 hours 5 min",
    "totalCost": 80000,
    "customerSatisfaction": 5,
    "partner": "SAMSUNG_FIRE",
    "provider": "FastTow"
  }
}

RSA Status Response

json
{
  "vin": "KMHSH81C7LU123456",
  "cid": "RSA_20260307_001",
  "status": "DISPATCHED",
  "timestamp": "2026-03-07T10:05:00Z",
  "serviceType": "TOWING",
  "priority": "NORMAL",
  "partner": "SAMSUNG_FIRE",
  "partnerTicketId": "SFT_12345",
  "provider": {
    "id": "PROV_001",
    "name": "FastTow",
    "phone": "02-9876-5432",
    "driver": {
      "name": "Kim Cheolsu",
      "phone": "010-1111-2222"
    },
    "vehicle": {
      "type": "TOW_TRUCK",
      "licensePlate": "88NA6789"
    }
  },
  "locationTracking": {
    "currentLocation": {
      "latitude": 37.48,
      "longitude": 126.98,
      "address": "Seoul Seocho-gu...",
      "lastUpdate": "2026-03-07T10:15:00Z"
    },
    "breakdownLocation": {
      "latitude": 37.5,
      "longitude": 127.0,
      "address": "Seoul Gangnam-gu..."
    },
    "destination": {
      "latitude": 37.5,
      "longitude": 127.0,
      "address": "Gangnam Service Center"
    },
    "estimatedDistance": 8.5,
    "estimatedArrival": "2026-03-07T10:30:00Z"
  },
  "timeline": [
    {
      "status": "REQUESTED",
      "timestamp": "2026-03-07T10:00:00Z",
      "description": "Roadside assistance requested"
    },
    {
      "status": "DISPATCHED",
      "timestamp": "2026-03-07T10:05:00Z",
      "description": "Service provider dispatched"
    }
  ],
  "estimatedCost": {
    "baseFee": 50000,
    "additionalFee": 0,
    "totalEstimate": 50000,
    "currency": "KRW"
  },
  "customerInfo": {
    "name": "Hong Gildong",
    "phone": "010-1234-5678"
  }
}

RSA History Response

json
{
  "vin": "KMHSH81C7LU123456",
  "incidents": [
    {
      "cid": "RSA_20260307_001",
      "timestamp": "2026-03-07T10:00:00Z",
      "serviceType": "TOWING",
      "status": "COMPLETED",
      "priority": "NORMAL",
      "partner": "SAMSUNG_FIRE",
      "provider": "FastTow",
      "duration": "2 hours 5 min",
      "cost": {
        "amount": 80000,
        "currency": "KRW",
        "paymentMethod": "MEMBERSHIP"
      },
      "breakdownLocation": "Seoul Gangnam-gu...",
      "destination": "Gangnam Service Center",
      "customerSatisfaction": 5,
      "agentId": "AGENT_001",
      "completionTime": "2026-03-07T12:05:00Z",
      "notes": "Successfully towed to service center."
    }
  ],
  "total": 1,
  "summary": {
    "totalIncidents": 1,
    "totalCost": 80000,
    "averageSatisfaction": 5.0,
    "mostUsedService": "TOWING",
    "lastServiceDate": "2026-03-07T12:05:00Z"
  }
}

RSA Statistics Response

json
{
  "period": "30d",
  "summary": {
    "totalRequests": 1250,
    "activeRequests": 3,
    "completedToday": 8,
    "averageResponseTime": "15 min",
    "successRate": 98.2,
    "customerSatisfaction": 4.7
  },
  "serviceTypes": {
    "TOWING": { "count": 45, "percentage": 36.0 },
    "BATTERY_JUMP": { "count": 30, "percentage": 24.0 },
    "TIRE_CHANGE": { "count": 25, "percentage": 20.0 },
    "FUEL_DELIVERY": { "count": 15, "percentage": 12.0 },
    "LOCKOUT": { "count": 10, "percentage": 8.0 }
  },
  "partners": {
    "SAMSUNG_FIRE": { "requests": 500, "successRate": 98.5 },
    "HYUNDAI_ROAD": { "requests": 400, "successRate": 97.8 },
    "GENESIS_ROAD": { "requests": 350, "successRate": 98.9 }
  },
  "timeStats": {
    "peakHours": ["09:00-11:00", "17:00-19:00"],
    "peakDays": ["MONDAY", "FRIDAY"],
    "averageServiceTime": "45 min",
    "longestServiceTime": "3 hours 15 min"
  },
  "costStats": {
    "totalRevenue": 85000000,
    "averageCostPerService": 68000,
    "currency": "KRW"
  },
  "generatedAt": "2026-03-07T15:00:00Z"
}

Partner Dispatch Completion Request

json
{
  "cid": "RSA_20260307_001",
  "partnerTicketId": "SFT_12345",
  "status": "COMPLETED",
  "completionTime": "2026-03-07T12:00:00Z",
  "provider": {
    "id": "PROV_001",
    "name": "FastTow",
    "driver": {
      "name": "Kim Cheolsu",
      "phone": "010-1111-2222"
    }
  },
  "serviceDetails": {
    "serviceType": "TOWING",
    "actualDistance": 15.2,
    "estimatedDistance": 12.0,
    "pickupLocation": {
      "address": "Seoul Gangnam-gu...",
      "latitude": 37.5,
      "longitude": 127.0,
      "arrivalTime": "2026-03-07T10:28:00Z"
    },
    "dropoffLocation": {
      "address": "Gangnam Service Center",
      "latitude": 37.5,
      "longitude": 127.0,
      "arrivalTime": "2026-03-07T12:00:00Z"
    },
    "serviceDuration": "1 hour 32 min",
    "specialEquipment": ["WHEEL_LIFT"],
    "serviceNotes": "Vehicle started successfully at destination"
  },
  "costDetails": {
    "baseFee": 50000,
    "distanceFee": 30000,
    "additionalFee": 0,
    "discountAmount": 0,
    "totalCost": 80000,
    "currency": "KRW",
    "paymentStatus": "PAID"
  },
  "customerFeedback": {
    "satisfactionRating": 5,
    "comments": "Professional and quick service",
    "recommendation": true
  },
  "followUpRequired": false,
  "completionNotes": "Service completed successfully. Customer satisfied."
}

Partner Dispatch Completion Response

json
{
  "cid": "RSA_20260307_001",
  "partnerTicketId": "SFT_12345",
  "status": "COMPLETED",
  "timestamp": "2026-03-07T12:05:00Z",
  "confirmation": {
    "serviceId": "SVC_001",
    "billingProcessed": true,
    "customerNotified": true,
    "documentsGenerated": ["RECEIPT", "SERVICE_REPORT"]
  },
  "nextSteps": {
    "customerFeedbackRequested": true,
    "followUpScheduled": false,
    "warrantyClaim": false
  }
}

Agent RSA Results Response

json
{
  "agentId": "AGENT_001",
  "agentName": "Kim Counselor",
  "period": "30d",
  "performance": {
    "totalHandled": 45,
    "averageHandlingTime": "25 min",
    "successRate": 96.5,
    "customerSatisfaction": 4.7,
    "responseRate": 98.2,
    "firstCallResolution": 85.5
  },
  "serviceBreakdown": {
    "TOWING": { "count": 20, "avgTime": "35 min", "satisfaction": 4.8 },
    "BATTERY_JUMP": { "count": 15, "avgTime": "15 min", "satisfaction": 4.6 },
    "TIRE_CHANGE": { "count": 10, "avgTime": "20 min", "satisfaction": 4.7 }
  },
  "timeAnalysis": {
    "totalWorkHours": 180,
    "averageCallsPerHour": 3.5,
    "peakHours": ["09:00-11:00", "14:00-16:00"],
    "averageCallDuration": "8 min"
  },
  "qualityMetrics": {
    "complianceRate": 99.2,
    "documentationAccuracy": 97.8,
    "escalationRate": 3.5,
    "customerComplaints": 1
  },
  "rankings": {
    "teamRank": 3,
    "teamSize": 15,
    "percentile": 80
  },
  "lastActivity": "2026-03-07T11:30:00Z",
  "generatedAt": "2026-03-07T15:00:00Z"
}

RSA Processing Status Real-time Query (SSE)

json
{
  "eventId": "EVT_001",
  "type": "RSA_DISPATCHED",
  "timestamp": "2026-03-07T10:05:00Z",
  "priority": "NORMAL",
  "data": {
    "cid": "RSA_20260307_001",
    "vin": "KMHSH81C7LU123456",
    "partner": "SAMSUNG_FIRE",
    "partnerTicketId": "SFT_12345",
    "serviceType": "TOWING",
    "status": "DISPATCHED",
    "provider": {
      "id": "PROV_001",
      "name": "FastTow",
      "driver": {
        "name": "Kim Cheolsu",
        "phone": "010-1111-2222"
      }
    },
    "location": {
      "breakdownLocation": {
        "latitude": 37.5,
        "longitude": 127.0,
        "address": "Seoul Gangnam-gu..."
      },
      "providerLocation": {
        "latitude": 37.48,
        "longitude": 126.98,
        "address": "Seoul Seocho-gu..."
      },
      "destination": {
        "latitude": 37.5,
        "longitude": 127.0,
        "address": "Gangnam Service Center"
      }
    },
    "estimatedArrival": "2026-03-07T10:30:00Z",
    "estimatedDistance": 8.5,
    "customerInfo": {
      "name": "Hong Gildong",
      "phone": "010-1234-5678"
    },
    "agentId": "AGENT_001"
  }
}

Security

API Endpoints

Refer to the Common API Specifications for headers, response codes, and error formats.

Authentication and Authorization

  • User authentication token required (JWT/OAuth2)
  • Vehicle access permission verification
  • Dispatch service usage permission confirmation

Data Security

  • All API communication encrypted with HTTPS/TLS
  • Security measures for vehicle breakdown information transmission
  • Sensitive information stored only on server

Privacy Protection

  • Explicit consent for vehicle status information collection
  • Specify purpose of location information collection
  • Compliance with service history retention period policy
  • Guarantee right to data deletion upon user request

Access Control

  • VIN-based vehicle access permission verification
  • Dispatch service usage permission confirmation
  • Separate authentication procedures for service company access

Exception Handling

  • Connection Failure: Support offline mode, cache last status
  • Slow Response: Loading indicator, timeout handling
  • Server Down: Display error message, suggest retry
  • Vehicle Offline: Display last status information, notify offline status
  • Data Error: Handle DTC code parsing errors
  • Sensor Error: Display sensor status error, guide manual input
  • Dispatch Delay: Notify when dispatch vehicle is delayed
  • Service Cancellation: Handle service cancellation per user request
  • Cost Issues: Handle service cost-related errors

Test Setup

Base URL: https://api.ecarus.run/api/v1/safety
Authentication Token: sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d
Sample VIN: KMHSH81C7LU123456

Use Swagger UI for interactive API testing. Jennifer

Deployment Considerations

App Store Registration

  • Clear description of location information collection
  • Consent for vehicle status information collection
  • Request emergency situation alert permissions
  • Compliance with personal information protection laws
  • Check dispatch service related regulations
  • Provide services according to contract conditions

Service Integration

  • Integration with dispatch service companies
  • Integration with billing system
  • Integration with call center system

Released under the MIT License.