SOS(Breakdown Support Service) Service API Developer Guide

Service Overview

SOS Service is Breakdown Support Service (bCall, Breakdown Call). It is a telematics service that transmits breakdown information from the vehicle to the call center and connects for consultation when the vehicle cannot operate or driver support is needed, though not an accident.

Service Features

Remote diagnosis support for vehicle breakdowns
Manual request-based emergency support
Automatic transmission of vehicle status information
Voice consultation connection
Appropriate service coordination (towing, maintenance, etc.)

Legal Requirements

No legal obligation unlike eCall
Compliance with personal information protection laws
Consent for vehicle breakdown information collection
Compliance with service contract conditions

Key Scenarios

Scenario 1: SOS Activation and Initial Data Transmission

API Flow by Entity:

📱 App (User):

SOS Request: Select SOS button to trigger help
Monitoring: Receive SOS status via SSE
Emergency Call: Immediate voice call connection with call center 🚗 Vehicle (TCU):
Event Reception: Receive SOS button signal from app or vehicle
Data Transmission: Transmit SOS notification data to server

🏢 Call Center:

Event Monitoring: Monitor real-time SOS requests
Incident Creation: Automatically create record when new SOS occurs
Emergency Contact: Immediate voice call connection with vehicle

Scenario 2: Voice Call Completion and Information Update

API Flow by Entity:

🚗 Vehicle (TCU):

Call Monitoring: Detect voice call completion with call center
Data Update: Transmit status information (battery, duration) to server

🏢 Call Center:

Consultation: Complete voice call and record consultation details
Status Update: Receive update notification via SSE

📱 App (User):

Status Monitoring: Receive vehicle status update via SSE
Battery Check: Check current battery level
Follow-up: Receive next step guidance and consultation summary

Scenario 3: Consultation Completion and Result Processing

API Flow by Entity:

🏢 Call Center:

Incident Closure: Close incident after investigation
Status Update: Update SOS record status to "CLOSED"

📱 App (User):

Result Check: Check final processing result
History Query: Check completed SOS history

Scenario 4: SOS Management and System Operations

API Flow by Entity:

🏢 Call Center:

System Health: Monitor SOS system health
Performance Query: Audit agent performance
Service Statistics: Analyze overall service volume

📱 App (User):

Status Audit: Check SOS service availability
History Audit: Review past SOS service interactions

Key Features

📱 Features to Implement in App

1. SOS Request and Monitoring

Real-time Monitoring: Receive SOS status via SSE
Result Check: Check final processing results
History Query: Query past SOS service history
System Health: Monitor overall SOS system status

🏢 Features to Implement in Call Center

1. SOS Incident Management

Incident Monitoring: Monitor real-time SOS requests
Status Query: Query specific incident status
Incident Closure: Close incident after processing
History Management: Query past SOS history

2. System and Performance Analysis

Service Statistics: Manage overall SOS service statistics
Agent Performance: Analyze agent performance
System Health: Monitor overall SOS system health
System Test: Regular system functionality test

Sequence Diagram

SOS (Real-time Events) System Flow

SOS

API Endpoints

SOS Statistics Query

bash

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

SOS System Test

bash

curl -X POST "https://api.ecarus.run/api/v1/safety/sos/system/test" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d" \
     -H "Content-Type: application/json" \
     -d '{
       "testType": "FULL_SYSTEM",
       "testVehicle": { "vin": "KMHSH81C7LU123456" },
       "testScenarios": ["VOICE_CONNECT", "DATA_TRANSFER"]
     }'

SOS Incident Closure

bash

curl -X POST "https://api.ecarus.run/api/v1/safety/vehicles/KMHSH81C7LU123456/sos/close" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d" \
     -H "Content-Type: application/json" \
     -d '{
       "cid": "SOS_20260307_001",
       "result": "Police Dispatched",
       "completionTime": "2026-03-07T19:00:00Z",
       "agentId": "AGENT_001",
       "notes": "Police dispatched. Customer safe.",
       "emergencyServices": {
         "police": {
           "dispatched": true,
           "reportNumber": "20260307-001234",
           "officerName": "Kim Soon-kyung",
           "arrivalTime": "2026-03-07T18:50:00Z"
         }
       },
       "customerStatus": {
         "safe": true,
         "injuries": false,
         "medicalAttention": false
       },
       "followUpRequired": false
     }'

SOS Incident Status Query

bash

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

SOS Incident History Query

bash

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

Agent SOS Results Query

bash

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

Agent Active SOS Incidents Query

bash

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

SOS System Health Status Query

bash

curl -X GET "https://api.ecarus.run/api/v1/safety/sos/system/health" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d"

SOS Real-time Event Reception (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/sos/events"

Data Models

SOS Incident Request

json

{
  "cid": "SOS_20260307_001",
  "vin": "KMHSH81C7LU123456",
  "emergencyType": "MEDICAL",
  "urgency": "HIGH",
  "location": {
    "latitude": 37.5665,
    "longitude": 126.9780,
    "address": "Seoul, Gangnam-gu, Teheran-ro",
    "accuracy": 5.2
  },
  "description": "Driver chest pain, unable to drive",
  "contactNumber": "+82-10-1234-5678",
  "passengerCount": 2,
  "vehicleCondition": "PARKED",
  "requestType": "MANUAL",
  "customerConsent": {
    "granted": true,
    "timestamp": "2026-03-07T18:30:00Z",
    "locationSharing": true,
    "voiceRecording": true,
    "emergencyServices": true
  }
}

SOS Incident Response

json

{
  "cid": "SOS_20260307_001",
  "vin": "KMHSH81C7LU123456",
  "status": "INITIATED",
  "timestamp": "2026-03-07T18:30:00Z",
  "emergencyType": "MEDICAL",
  "urgency": "HIGH",
  "location": {
    "latitude": 37.5665,
    "longitude": 126.9780,
    "address": "Seoul, Gangnam-gu, Teheran-ro"
  },
  "contactCenter": {
    "phone": "1588-1234",
    "available": true,
    "estimatedWaitTime": "30 seconds",
    "agentId": "AGENT_001"
  },
  "voiceCall": {
    "status": "CONNECTING",
    "phoneNumber": "+8212345678",
    "sessionId": "CALL-20260307-001"
  },
  "estimatedResponseTime": "2 minutes"
}

SOS Closure Request

json

{
  "cid": "SOS_20260307_001",
  "vin": "KMHSH81C7LU123456",
  "result": "POLICE_DISPATCHED",
  "completionTime": "2026-03-07T19:00:00Z",
  "agentId": "AGENT_001",
  "notes": "Police dispatched. Customer safe.",
  "emergencyServices": {
    "police": {
      "dispatched": true,
      "reportNumber": "20260307-001234",
      "officerName": "Kim Officer",
      "arrivalTime": "2026-03-07T18:50:00Z"
    }
  },
  "customerStatus": {
    "safe": true,
    "injuries": false,
    "medicalAttention": false
  },
  "followUpRequired": false
}

SOS Closure Response

json

{
  "cid": "SOS_20260307_001",
  "status": "CLOSED",
  "timestamp": "2026-03-07T19:05:00Z",
  "summary": {
    "emergencyType": "MEDICAL",
    "duration": "35 minutes",
    "servicesDispatched": ["POLICE"],
    "customerSafe": true,
    "agent": "Kim Counselor"
  }
}

SOS Status Response

json

{
  "cid": "SOS_20260307_001",
  "vin": "KMHSH81C7LU123456",
  "status": "CONNECTED",
  "timestamp": "2026-03-07T18:30:00Z",
  "emergencyType": "MEDICAL",
  "urgency": "HIGH",
  "location": {
    "latitude": 37.5665,
    "longitude": 126.9780,
    "address": "Seoul, Gangnam-gu, Teheran-ro",
    "accuracy": 5.2,
    "lastUpdate": "2026-03-07T18:30:00Z"
  },
  "description": "Driver chest pain, unable to drive",
  "contactNumber": "+82-10-1234-5678",
  "vehicleStatus": {
    "drivable": false,
    "engineStatus": "OFF",
    "batteryVoltage": 12.6,
    "fuelLevel": 45.2,
    "dtcCodes": [],
    "transmissionStatus": "PARK"
  },
  "voiceCall": {
    "sessionId": "CALL-20260307-001",
    "status": "CONNECTED",
    "startTime": "2026-03-07T18:31:00Z",
    "duration": 180,
    "agent": {
      "agentId": "AGENT_001",
      "name": "Kim Counselor",
      "extension": "801"
    },
    "recording": {
      "enabled": true,
      "url": "https://api.daddyhouse.net/recordings/CALL-001",
      "duration": 180
    }
  },
  "dispatchInfo": {
    "dispatched": true,
    "serviceType": "POLICE",
    "provider": "Gangnam Police Station",
    "estimatedArrival": "2026-03-07T18:45:00Z",
    "status": "DISPATCHED",
    "contactNumber": "112",
    "unitNumber": "PATROL-001"
  },
  "timeline": [
    {
      "status": "INITIATED",
      "timestamp": "2026-03-07T18:30:00Z",
      "description": "Emergency call initiated"
    },
    {
      "status": "CONNECTED",
      "timestamp": "2026-03-07T18:31:00Z",
      "description": "Connected to emergency agent"
    }
  ]
}

SOS History Response

json

{
  "vin": "KMHSH81C7LU123456",
  "incidents": [
    {
      "cid": "SOS_20260307_001",
      "timestamp": "2026-03-07T18:30:00Z",
      "emergencyType": "MEDICAL",
      "status": "CLOSED",
      "urgency": "HIGH",
      "duration": 2100,
      "location": {
        "latitude": 37.5665,
        "longitude": 126.9780,
        "address": "Seoul, Gangnam-gu, Teheran-ro"
      },
      "servicesDispatched": ["POLICE"],
      "customerSafe": true,
      "agentId": "AGENT_001",
      "completionTime": "2026-03-07T19:05:00Z",
      "notes": "Police dispatched. Customer safe."
    }
  ],
  "total": 1,
  "summary": {
    "totalIncidents": 1,
    "emergencyTypes": {
      "MEDICAL": 1
    },
    "averageResponseTime": "2 minutes",
    "customerSatisfaction": 5.0,
    "lastIncidentDate": "2026-03-07T19:05:00Z"
  }
}

SOS Statistics Response

json

{
  "period": "30d",
  "summary": {
    "totalIncidents": 125,
    "activeIncidents": 2,
    "resolvedToday": 8,
    "averageResponseTime": "1.5 minutes",
    "resolutionRate": 98.4,
    "customerSatisfaction": 4.8
  },
  "emergencyTypes": {
    "MEDICAL": { "count": 45, "percentage": 36.0 },
    "BREAKDOWN": { "count": 35, "percentage": 28.0 },
    "ACCIDENT": { "count": 25, "percentage": 20.0 },
    "SECURITY": { "count": 15, "percentage": 12.0 },
    "OTHER": { "count": 5, "percentage": 4.0 }
  },
  "servicesDispatched": {
    "POLICE": { "count": 40, "percentage": 32.0 },
    "AMBULANCE": { "count": 35, "percentage": 28.0 },
    "FIRE": { "count": 15, "percentage": 12.0 },
    "TOWING": { "count": 35, "percentage": 28.0 }
  },
  "timeStats": {
    "peakHours": ["18:00-22:00", "06:00-09:00"],
    "peakDays": ["FRIDAY", "SATURDAY"],
    "averageCallDuration": "12 minutes",
    "longestCallDuration": "45 minutes"
  },
  "agentStats": {
    "totalAgents": 15,
    "activeAgents": 8,
    "averageCallsPerAgent": 8.3,
    "topAgent": {
      "agentId": "AGENT_001",
      "name": "Kim Counselor",
      "handledIncidents": 15
    }
  },
  "generatedAt": "2026-03-07T20:00:00Z"
}

Agent SOS Performance Response

json

{
  "agentId": "AGENT_001",
  "agentName": "Kim Counselor",
  "period": "30d",
  "performance": {
    "totalHandled": 45,
    "averageHandlingTime": "12 minutes",
    "resolutionRate": 97.8,
    "customerSatisfaction": 4.9,
    "responseRate": 99.5,
    "firstCallResolution": 90.2
  },
  "emergencyBreakdown": {
    "MEDICAL": { "count": 20, "avgTime": "15 min", "satisfaction": 4.9 },
    "BREAKDOWN": { "count": 15, "avgTime": "10 min", "satisfaction": 4.8 },
    "ACCIDENT": { "count": 10, "avgTime": "20 min", "satisfaction": 5.0 }
  },
  "timeAnalysis": {
    "totalWorkHours": 180,
    "averageCallsPerHour": 2.5,
    "peakHours": ["18:00-22:00", "06:00-09:00"],
    "averageCallDuration": "12 minutes"
  },
  "qualityMetrics": {
    "complianceRate": 99.5,
    "documentationAccuracy": 98.2,
    "escalationRate": 2.2,
    "customerComplaints": 0
  },
  "rankings": {
    "teamRank": 1,
    "teamSize": 15,
    "percentile": 95
  },
  "lastActivity": "2026-03-07T19:05:00Z",
  "generatedAt": "2026-03-07T20:00:00Z"
}

Agent Active Incidents Response

json

{
  "agentId": "AGENT_001",
  "activeIncidents": [
    {
      "cid": "SOS_20260307_002",
      "vin": "KMHSH81C7LU123457",
      "emergencyType": "BREAKDOWN",
      "urgency": "MEDIUM",
      "status": "CONNECTED",
      "timestamp": "2026-03-07T19:30:00Z",
      "location": {
        "latitude": 37.4021,
        "longitude": 127.1023,
        "address": "Seoul, Songpa-gu, Olympic-ro"
      },
      "customerName": "Hong Gildong",
      "contactNumber": "+82-10-1234-5678",
      "callDuration": 600,
      "voiceCall": {
        "sessionId": "CALL-20260307-002",
        "status": "CONNECTED",
        "startTime": "2026-03-07T19:31:00Z"
      }
    }
  ],
  "total": 1,
  "summary": {
    "highUrgency": 0,
    "mediumUrgency": 1,
    "lowUrgency": 0,
    "averageHandlingTime": "10 minutes"
  }
}

SOS System Health Status Response

json

{
  "status": "HEALTHY",
  "timestamp": "2026-03-07T20:00:00Z",
  "systems": {
    "api": {
      "status": "OPERATIONAL",
      "responseTime": "120ms",
      "uptime": "99.99%"
    },
    "database": {
      "status": "OPERATIONAL",
      "responseTime": "45ms",
      "connections": 25
    },
    "voiceSystem": {
      "status": "OPERATIONAL",
      "activeCalls": 8,
      "queueLength": 2,
      "averageWaitTime": "30 seconds"
    },
    "dispatchSystem": {
      "status": "OPERATIONAL",
      "activeDispatches": 3,
      "averageResponseTime": "2 minutes"
    },
    "notificationSystem": {
      "status": "OPERATIONAL",
      "deliveryRate": "99.8%",
      "pendingNotifications": 0
    }
  },
  "metrics": {
    "totalIncidentsToday": 12,
    "activeIncidents": 2,
    "availableAgents": 7,
    "systemLoad": "35%"
  },
  "alerts": [
    {
      "level": "INFO",
      "message": "High call volume expected during evening hours",
      "timestamp": "2026-03-07T17:00:00Z"
    }
  ]
}

SOS Test Request

json

{
  "testType": "FULL_SYSTEM",
  "testVehicle": {
    "vin": "KMHSH81C7LU123456",
    "model": "BMW 320i",
    "year": 2022
  },
  "testScenarios": ["VOICE_CONNECT", "DATA_TRANSFER", "DISPATCH_SIMULATION"],
  "testParameters": {
    "timeout": 300,
    "retryAttempts": 3,
    "detailedLogging": true
  }
}

SOS Test Response

json

{
  "testId": "TEST-20260307-001",
  "testType": "FULL_SYSTEM",
  "status": "COMPLETED",
  "timestamp": "2026-03-07T20:00:00Z",
  "duration": 180,
  "results": {
    "voiceConnect": {
      "status": "PASSED",
      "responseTime": "2.1 seconds",
      "audioQuality": "EXCELLENT"
    },
    "dataTransfer": {
      "status": "PASSED",
      "responseTime": "150ms",
      "dataIntegrity": "VERIFIED"
    },
    "dispatchSimulation": {
      "status": "PASSED",
      "responseTime": "1.8 seconds",
      "notificationDelivered": true
    }
  },
  "overall": {
    "status": "PASSED",
    "score": 98.5,
    "recommendations": [
      "System operating optimally",
      "No issues detected"
    ]
  }
}

SOS Real-time Event (SSE)

json

{
  "eventId": "EVT_001",
  "type": "SOS_INITIATED",
  "timestamp": "2026-03-07T18:30:00Z",
  "priority": "HIGH",
  "data": {
    "cid": "SOS_20260307_001",
    "vin": "KMHSH81C7LU123456",
    "emergencyType": "MEDICAL",
    "urgency": "HIGH",
    "status": "INITIATED",
    "location": {
      "latitude": 37.5665,
      "longitude": 126.9780,
      "address": "Seoul, Gangnam-gu, Teheran-ro",
      "accuracy": 5.2
    },
    "customerInfo": {
      "name": "Hong Gildong",
      "phone": "+82-10-1234-5678",
      "passengerCount": 2
    },
    "vehicleInfo": {
      "make": "BMW",
      "model": "320i",
      "year": 2022,
      "condition": "PARKED"
    },
    "description": "Driver chest pain, unable to drive",
    "agentId": "AGENT_001"
  }
}

Security and Privacy

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
Breakdown support service usage permission confirmation

Data Security

All API communication encrypted with HTTPS/TLS
Security measures for vehicle breakdown information transmission
Secure storage of call recording files

Privacy Protection

Explicit consent for vehicle status information collection
Specify purpose of location information collection
Consent for call recording
Compliance with service history retention period policy

Access Control

VIN-based vehicle access permission verification
Counselor access permission management
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

Call Connection Failure: Attempt alternative call methods
Counselor Shortage: Queue guidance, suggest scheduled consultation
Call Quality: Notify when voice quality degrades

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
Legal Regulation Compliance
Service Integration

SOS(Breakdown Support Service) Service API Developer Guide ​

Service Overview ​

Service Features ​

Legal Requirements ​

Key Scenarios ​

Scenario 1: SOS Activation and Initial Data Transmission ​

Scenario 2: Voice Call Completion and Information Update ​

Scenario 3: Consultation Completion and Result Processing ​

Scenario 4: SOS Management and System Operations ​

Key Features ​

📱 Features to Implement in App ​

1. SOS Request and Monitoring ​

🏢 Features to Implement in Call Center ​

1. SOS Incident Management ​

2. System and Performance Analysis ​

Sequence Diagram ​

SOS (Real-time Events) System Flow ​

API Endpoints ​

SOS Statistics Query ​

SOS System Test ​

SOS Incident Closure ​

SOS Incident Status Query ​

SOS Incident History Query ​

Agent SOS Results Query ​

Agent Active SOS Incidents Query ​

SOS System Health Status Query ​

SOS Real-time Event Reception (SSE) ​

Data Models ​

SOS Incident Request ​

SOS Incident Response ​

SOS Closure Request ​

SOS Closure Response ​

SOS Status Response ​

SOS History Response ​

SOS Statistics Response ​

Agent SOS Performance Response ​

Agent Active Incidents Response ​

SOS System Health Status Response ​

SOS Test Request ​

SOS Test Response ​

SOS Real-time Event (SSE) ​

Security and Privacy ​

API Endpoints ​

Authentication and Authorization ​

Data Security ​

Privacy Protection ​

Access Control ​

Exception Handling ​

Network Related ​

Vehicle Status Related ​

Consultation Related ​

Test Setup ​

Deployment Considerations ​

SOS(Breakdown Support Service) Service API Developer Guide

Service Overview

Service Features

Legal Requirements

Key Scenarios

Scenario 1: SOS Activation and Initial Data Transmission

Scenario 2: Voice Call Completion and Information Update

Scenario 3: Consultation Completion and Result Processing

Scenario 4: SOS Management and System Operations

Key Features

📱 Features to Implement in App

1. SOS Request and Monitoring

🏢 Features to Implement in Call Center

1. SOS Incident Management

2. System and Performance Analysis

Sequence Diagram

SOS (Real-time Events) System Flow

API Endpoints

SOS Statistics Query

SOS System Test

SOS Incident Closure

SOS Incident Status Query

SOS Incident History Query

Agent SOS Results Query

Agent Active SOS Incidents Query

SOS System Health Status Query

SOS Real-time Event Reception (SSE)

Data Models

SOS Incident Request

SOS Incident Response

SOS Closure Request

SOS Closure Response

SOS Status Response

SOS History Response

SOS Statistics Response

Agent SOS Performance Response

Agent Active Incidents Response

SOS System Health Status Response

SOS Test Request

SOS Test Response

SOS Real-time Event (SSE)

Security and Privacy

API Endpoints

Authentication and Authorization

Data Security

Privacy Protection

Access Control

Exception Handling

Network Related

Vehicle Status Related

Consultation Related

Test Setup

Deployment Considerations