원격 시동 제어 API 개발자 가이드

서비스 개요

원격 시동 제어는 사용자가 모바일 애플리케이션을 통해 차량의 엔진을 원격으로 시동하거나 정지할 수 있는 텔레매틱스 서비스입니다.

서비스 특징

원격 시동/정지 제어 기능
탑승 전 차량 실내 환경 조성 (공조 제어 연동)
자동 엔진 종료 정책을 통한 보안 강화
보안 및 안전 정책 적용
국가별 규정 준수

법적 요구사항

차량 물리 제어 기능에 따른 강력한 보안 정책 필수
개인정보 보호법 준수
서버-차량 간 양방향 인증
명령 실행 감사 로그(Audit Log) 기록
국가별 원격 시동 관련 법규 준수

주요 시나리오

시나리오 1: 원격 시동 요청 및 실행

엔티티별 API 흐름:

📱 앱 (사용자):

시동 요청: Correlation ID 생성 후 요청
응답 수신: 202 Accepted 응답 수신
푸시 알림: 시동 제어 결과 푸시 알림 수신
UI 업데이트: 30초 이내 응답 시 UI 업데이트, 타임아웃 시 무시

🚗 차량 (TCU):

명령 수신: ECARUS로부터 시동 제어 명령 수신
안전 검증: 도어, 기어, 키 상태 등 안전 조건 검증
시동 실행: 조건 충족 시 엔진 시동 실행
결과 게시: 성공/실패 결과를 ECARUS로 게시

🏢 콜센터:

대리 요청: Correlation ID 생성 후 대리 요청
응답 수신: 202 Accepted 응답 수신
WebSocket 이벤트: 시동 제어 결과 실시간 수신

시나리오 2: 시동 제어 실패 및 안전 종료 처리

엔티티별 API 흐름:

📱 앱 (사용자):

명령 요청: 시동/정지 명령 요청
실패 알림: 푸시 알림을 통해 실패 원인 수신
상태 확인: 현재 엔진 상태 확인
명령 취소: 실행 중인 명령 취소

🚗 차량 (TCU):

안전 검증: 도어 열림, 주행 상태 등 안전 조건 검증
실패 처리: 안전 조건 위반 시 실패 사유 생성
결과 게시: 실패 결과를 ECARUS로 게시
자동 종료: 안전 조건 위반 시 엔진 자동 종료

🏢 콜센터:

이력 조회: 실패 이력 조회
진단 확인: 시스템 진단 확인
고객 지원: 실패 원인 분석 및 고객 안내

시나리오 3: 엔진 상태 모니터링 및 설정 관리

엔티티별 API 흐름:

📱 앱 (사용자):

상태 조회: 실시간 엔진 상태 확인
이력 조회: 시동 제어 이력 확인
실시간 모니터링: SSE 스트림을 통한 상태 변경 모니터링
명령 취소: 필요시 명령 취소

🚗 차량 (TCU):

상태 수집: 엔진 상태, 연료 레벨, 온도 등 실시간 수집
상태 전송: 수집된 상태 데이터를 ECARUS로 전송
설정 적용: 최대 가동 시간 등 사용자 설정값 적용
자동 이벤트: 엔진 종료 등 이벤트 자동 게시

🏢 콜센터:

상태 모니터링: 실시간 차량 엔진 상태 확인
설정 관리: 원격 시동 설정 관리 및 환경 설정 업데이트
진단 관리: 정기적 시스템 진단 수행
대리 정지: 비상시 대리 시동 정지

주요 기능

📱 앱 구현 기능

1. 원격 시동 제어 기능

시동 시작: 원격 시동 시작 요청
시동 정지: 원격 시동 정지 요청
명령 취소: 실행 중인 명령 취소 요청

2. 상태 모니터링 기능

상태 조회: 즉시 엔진 상태 조회
실시간 업데이트: SSE 스트림을 통한 실시간 상태 모니터링

3. 이력 관리 기능

이력 조회: 시동 제어 이력 조회
실패 분석: 실패 원인 확인 및 재시도

4. 알림 및 UI 기능

푸시 알림: 시동 제어 결과 푸시 알림 수신
타이머 관리: 30초 타임아웃 기반의 응답 처리
Correlation ID: 요청 추적을 위한 고유 ID 생성

🏢 콜센터 구현 기능

4. 고객 지원 기능

SSE 연결: 실시간 이벤트 수신
문제 해결: 시스템 진단 기반의 문제 해결 지원
보안 모니터링: 이상 접근 패턴 모니터링

🚗 차량(TCU) 처리 기능

1. 명령 실행 기능

시동 제어: 엔진 시동/정지 제어
안전 검증: 차량 상태에 따른 실행 조건 검증
결과 게시: MQTT를 통한 실행 결과 게시

2. 상태 관리 기능

상태 수집: 엔진 상태, 연료 레벨, 온도 수집
상태 전송: 실시간 상태 데이터 전송
자동 이벤트: 엔진 종료 등 이벤트 자동 게시

3. 안전 기능

안전 검증: 도어, 기어, 키 상태 검증
자동 종료: 안전 조건 위반 시 엔진 자동 종료

시퀀스 다이어그램

원격 시동 제어 시스템 흐름

원격 시동 제어

API 엔드포인트

헤더, 응답 코드 및 에러 형식은 공통 API 사양을 참조하십시오.

원격 시동 요청

bash

curl -X POST "https://api.ecarus.run/api/v1/remotecontrol/vehicles/KMHSH81C7LU123456/engine/start" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d" \
     -H "Content-Type: application/json" \
     -d '{"targetTemperature": 24.0, "climateControl": true, "duration": 1800}'

원격 시동 정지 요청

bash

curl -X POST "https://api.ecarus.run/api/v1/remotecontrol/vehicles/KMHSH81C7LU123456/engine/stop" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d" \
     -H "Content-Type: application/json" \
     -d '{"force": false, "reason": "User stop", "preserveClimate": false}'

시동 제어 취소 요청

bash

curl -X POST "https://api.ecarus.run/api/v1/remotecontrol/vehicles/KMHSH81C7LU123456/engine/cancel" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d" \
     -H "Content-Type: application/json" \
     -d '{"correlationId": "uuid-12345678", "reason": "사용자 취소", "force": false}'

공조 제어 상태 조회

bash

curl -X GET "https://api.ecarus.run/api/v1/remotecontrol/vehicles/KMHSH81C7LU123456/engine/status?includeDetails=true" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d"

시동 제어 이력 조회

bash

curl -X GET "https://api.ecarus.run/api/v1/remotecontrol/vehicles/KMHSH81C7LU123456/engine/history?period=24h&limit=50" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d"

원격 시동 설정 조회

bash

curl -X GET "https://api.ecarus.run/api/v1/remotecontrol/vehicles/KMHSH81C7LU123456/engine/config" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d"

원격 시동 설정 업데이트

bash

curl -X PUT "https://api.ecarus.run/api/v1/remotecontrol/vehicles/KMHSH81C7LU123456/engine/config" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d" \
     -H "Content-Type: application/json" \
     -d '{"remoteStartEnabled": true, "maxRunTime": 1800, "autoStopEnabled": true, "securityRequired": true, "climateControl": true}'

시동 시스템 진단 조회

bash

curl -X GET "https://api.ecarus.run/api/v1/remotecontrol/vehicles/KMHSH81C7LU123456/engine/diagnostics" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d"

원격 시동 상태 실시간 조회 (SSE)

참고: 브라우저를 통해 접속하거나 전용 SSE 클라이언트 사용을 권장합니다.

bash

curl -X GET "https://api.ecarus.run/api/v1/remotecontrol/vehicles/KMHSH81C7LU123456/engine/updates/stream" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d" \
     -H "Accept: text/event-stream"

데이터 모델

원격 시동 요청 (Start Request)

json

{
  "targetTemperature": 24.0,
  "climateControl": true,
  "duration": 1800
}

targetTemperature: 목표 온도 (°C)
climateControl: 에어컨 제어 여부
duration: 가동 시간 (초 단위, 최대 3600)

원격 시동 정지 요청 (Stop Request)

json

{
  "force": false,
  "reason": "사용자 정지",
  "preserveClimate": false
}

reason: User stop, Emergency, System error, Security violation
force: 강제 정지 여부 (기본값: false)
preserveClimate: 에어컨 유지 여부

시동 취소 요청 (Cancellation Request)

json

{
  "correlationId": "uuid-12345678",
  "reason": "사용자 취소",
  "force": false
}

reason: User cancellation, Emergency stop, System error, Timeout
force: 강제 취소 여부 (기본값: false)

엔진 상태 요청 (Query Parameters)

includeDetails: true

includeDetails: 상세 정보 포함 여부

시동 제어 응답 (Control Response)

json

{
  "commandId": "cmd-uuid-12345",
  "vin": "KMHSH81C7LU123456",
  "status": "PENDING",
  "message": "명령 수신됨",
  "estimatedDuration": 5,
  "timestamp": "2026-01-12T08:30:00Z"
}

status: PENDING, IN_PROGRESS, SUCCESS, FAILED, TIMEOUT
estimatedDuration: 예상 실행 시간 (초)

엔진 상태 응답 (Status Response)

json

{
  "vin": "KMHSH81C7LU123456",
  "isRunning": true,
  "isRemoteStarted": true,
  "remainingTimeSec": 420,
  "startTime": "2026-01-12T08:30:00Z",
  "autoStopReason": null,
  "climateActive": true,
  "targetTemperature": 24.0,
  "currentTemperature": 18.5,
  "fuelLevel": 65.5,
  "engineTemperature": 85.2,
  "timestamp": "2026-01-12T08:33:00Z"
}

autoStopReason: DURATION_TIMEOUT, LOW_FUEL, HIGH_TEMPERATURE, USER_STOP, SECURITY_VIOLATION

시동 제어 이력 요청 (History Request)

period: 24h
limit: 50
offset: 0
action: START

period: 1h, 24h, 7d, 30d
action: START, STOP, CANCEL, STATUS_CHECK

시동 제어 이력 응답 (History Response)

json

{
  "vin": "KMHSH81C7LU123456",
  "history": [
    {
      "commandId": "cmd-uuid-12345",
      "action": "START",
      "status": "SUCCESS",
      "timestamp": "2026-01-12T08:30:00Z",
      "executionTime": 45,
      "duration": 585,
      "autoStopReason": "DURATION_TIMEOUT",
      "userId": "user-123",
      "source": "MOBILE_APP",
      "failureReason": null,
      "targetTemperature": 24.0
    }
  ],
  "total": 1,
  "hasMore": false
}

status: SUCCESS, FAILED, TIMEOUT, CANCELLED
source: MOBILE_APP, CALL_CENTER, WEB, VOICE_ASSISTANT

원격 시동 설정 응답 (Settings Response)

json

{
  "vin": "KMHSH81C7LU123456",
  "remoteStartEnabled": true,
  "maxRunTime": 1800,
  "autoStopEnabled": true,
  "securityRequired": true,
  "climateControl": true,
  "defaultTemperature": 22.0,
  "lowFuelThreshold": 15.0,
  "highTemperatureThreshold": 105.0,
  "updatedTime": "2026-01-12T10:00:00Z"
}

maxRunTime: 최대 가동 시간 (초)
lowFuelThreshold: 저연료 임계치 (%)
highTemperatureThreshold: 고온 임계치 (°C)

시동 시스템 진단 응답 (Diagnostics Response)

json

{
  "vin": "KMHSH81C7LU123456",
  "systemStatus": "NORMAL",
  "components": [
    {
      "id": "engine_control_01",
      "name": "Engine Control Module",
      "status": "ACTIVE",
      "health": 98,
      "lastMaintenance": "2025-06-15T00:00:00Z",
      "errorCodes": []
    },
    {
      "id": "remote_start_01",
      "name": "Remote Start Module",
      "status": "ACTIVE",
      "health": 95,
      "lastMaintenance": "2025-06-15T00:00:00Z",
      "errorCodes": []
    }
  ],
  "alerts": [],
  "lastCheck": "2026-01-12T08:30:00Z"
}

status: ACTIVE, INACTIVE, ERROR, MAINTENANCE_REQUIRED
health: 0-100 점수

엔진 상태 업데이트 (SSE)

json

{
  "type": "ENGINE_STATUS_UPDATE",
  "vin": "KMHSH81C7LU123456",
  "timestamp": "2026-01-12T08:33:00Z",
  "data": {
    "isRunning": true,
    "remainingTimeSec": 420,
    "climateActive": true,
    "changeType": "STARTED",
    "previousState": {
      "isRunning": false,
      "remainingTimeSec": 0
    },
    "currentTemperature": 18.5,
    "targetTemperature": 24.0
  }
}

type: ENGINE_STATUS_UPDATE, COMMAND_STATUS_UPDATE, SYSTEM_ALERT
changeType: STARTED, STOPPED, TIMEOUT_WARNING, LOW_FUEL_WARNING

보안 및 프라이버시

인증 및 권한 부여

사용자 인증 토큰 필요 (JWT/OAuth2)
차량 접근 권한 확인
원격 시동 제어 권한 확인

데이터 보안

모든 API 통신은 HTTPS/TLS 암호화
명령 위조 방지를 위한 Command Signing 적용
서버-차량 간 양방향 인증 수행
mTLS 기반의 통신 보안 강화

프라이버시 보호

차량 제어 이력 수집에 대한 명시적 동의
위치 정보 수집 목적 명시
명령 실행 이력 보존 기간 정책 준수

접근 제어

VIN 기반 차량 접근 권한 확인
다중 요소 인증(MFA) 요구
명령 호출 제한(Rate Limit) 적용
이상 접근 패턴 감지 및 차단

예외 처리

네트워크 관련

연결 실패: 오프라인 모드 지원, 마지막 상태 캐싱
응답 지연: 로딩 인디케이터, 타임아웃 처리
서버 다운: 에러 메시지 표시, 재시도 제안

차량 상태 관련

차량 오프라인: 명령 전송 실패 알림, 큐 처리
조건 미충족: 안전 조건 미충족 시 명령 거부
주행 중: 주행 중 시동 제어 제한

보안 관련

인증 실패: 재인증 요청, 보안 강화 안내
권한 없음: 권한 부족 사유 명확히 표시
의심스러운 접근: 계정 잠금 및 알림

명령 실행 관련

자동 종료: 종료 사유 명확히 표시
타임아웃: 명령 유효 시간(TTL) 만료 알림
일부 성공: 일부 기능만 작동 시 상세 안내

테스트 설정

Base URL: https://api.ecarus.run/api/v1/remotecontrol
인증 토큰: sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d
샘플 VIN: KMHSH81C7LU123456

대화형 API 테스트를 위해 Swagger UI를 사용하십시오.

배포 고려사항

앱 스토어 등록

차량 제어 관련 권한 요청
생체 인증 권한 요청
위치 정보 수집에 대한 명확한 설명

법규 준수

개인정보 보호법 준수
차량 원격 제어 관련 법규 확인
국가별 원격 시동 관련 법령 준수

차량 호환성

다양한 차종 지원
OEM별 엔진 제어 방식 차이 고려
내연기관/전기차/하이브리드 지원

원격 시동 제어 API 개발자 가이드 ​

서비스 개요 ​

서비스 특징 ​

법적 요구사항 ​

주요 시나리오 ​

시나리오 1: 원격 시동 요청 및 실행 ​

시나리오 2: 시동 제어 실패 및 안전 종료 처리 ​

시나리오 3: 엔진 상태 모니터링 및 설정 관리 ​

주요 기능 ​

📱 앱 구현 기능 ​

1. 원격 시동 제어 기능 ​

2. 상태 모니터링 기능 ​

3. 이력 관리 기능 ​

4. 알림 및 UI 기능 ​

🏢 콜센터 구현 기능 ​

1. 대리 제어 기능 ​

2. 설정 관리 기능 ​

3. 이력 및 진단 기능 ​

4. 고객 지원 기능 ​

🚗 차량(TCU) 처리 기능 ​

1. 명령 실행 기능 ​

2. 상태 관리 기능 ​

3. 안전 기능 ​

시퀀스 다이어그램 ​

원격 시동 제어 시스템 흐름 ​

API 엔드포인트 ​

원격 시동 요청 ​

원격 시동 정지 요청 ​

시동 제어 취소 요청 ​

공조 제어 상태 조회 ​

시동 제어 이력 조회 ​

원격 시동 설정 조회 ​

원격 시동 설정 업데이트 ​

시동 시스템 진단 조회 ​

원격 시동 상태 실시간 조회 (SSE) ​

데이터 모델 ​

원격 시동 요청 (Start Request) ​

원격 시동 정지 요청 (Stop Request) ​

시동 취소 요청 (Cancellation Request) ​

엔진 상태 요청 (Query Parameters) ​

시동 제어 응답 (Control Response) ​

엔진 상태 응답 (Status Response) ​

시동 제어 이력 요청 (History Request) ​

시동 제어 이력 응답 (History Response) ​

원격 시동 설정 응답 (Settings Response) ​

시동 시스템 진단 응답 (Diagnostics Response) ​

엔진 상태 업데이트 (SSE) ​

보안 및 프라이버시 ​

인증 및 권한 부여 ​

데이터 보안 ​

프라이버시 보호 ​

접근 제어 ​

예외 처리 ​

네트워크 관련 ​

차량 상태 관련 ​

보안 관련 ​

명령 실행 관련 ​

테스트 설정 ​

배포 고려사항 ​

앱 스토어 등록 ​

법규 준수 ​

차량 호환성 ​

원격 시동 제어 API 개발자 가이드

서비스 개요

서비스 특징

법적 요구사항

주요 시나리오

시나리오 1: 원격 시동 요청 및 실행

시나리오 2: 시동 제어 실패 및 안전 종료 처리

시나리오 3: 엔진 상태 모니터링 및 설정 관리

주요 기능

📱 앱 구현 기능

1. 원격 시동 제어 기능

2. 상태 모니터링 기능

3. 이력 관리 기능

4. 알림 및 UI 기능

🏢 콜센터 구현 기능

1. 대리 제어 기능

2. 설정 관리 기능

3. 이력 및 진단 기능

4. 고객 지원 기능

🚗 차량(TCU) 처리 기능

1. 명령 실행 기능

2. 상태 관리 기능

3. 안전 기능

시퀀스 다이어그램

원격 시동 제어 시스템 흐름

API 엔드포인트

원격 시동 요청

원격 시동 정지 요청

시동 제어 취소 요청

공조 제어 상태 조회

시동 제어 이력 조회

원격 시동 설정 조회

원격 시동 설정 업데이트

시동 시스템 진단 조회

원격 시동 상태 실시간 조회 (SSE)

데이터 모델

원격 시동 요청 (Start Request)

원격 시동 정지 요청 (Stop Request)

시동 취소 요청 (Cancellation Request)

엔진 상태 요청 (Query Parameters)

시동 제어 응답 (Control Response)

엔진 상태 응답 (Status Response)

시동 제어 이력 요청 (History Request)

시동 제어 이력 응답 (History Response)

원격 시동 설정 응답 (Settings Response)

시동 시스템 진단 응답 (Diagnostics Response)

엔진 상태 업데이트 (SSE)

보안 및 프라이버시

인증 및 권한 부여

데이터 보안

프라이버시 보호

접근 제어

예외 처리

네트워크 관련

차량 상태 관련

보안 관련

명령 실행 관련

테스트 설정

배포 고려사항

앱 스토어 등록

법규 준수

차량 호환성