원격 트렁크 제어 API 개발자 가이드

서비스 개요

원격 트렁크 제어는 사용자가 모바일 애플리케이션을 통해 차량의 트렁크를 원격으로 열거나 닫을 수 있는 텔레매틱스 서비스입니다.

서비스 특징

원격 트렁크 열기/닫기 제어 기능
물품 배송 및 수거를 위한 편의성 제공
스마트 배송 및 발렛 서비스 지원
강화된 보안 정책 적용
명령 및 이벤트 기반의 상태 구분

법적 요구사항

차량 보안 관련 기능에 따른 강력한 보안 정책 필수
개인정보 보호법 준수
명령 감사 로그(Command Audit Log) 기록 의무화
위치 기반 제한(Geo-fencing) 정책 적용

주요 시나리오

시나리오 1: 원격 트렁크 제어 요청 및 실행

엔티티별 API 흐름:

📱 앱 (사용자):

트렁크 열기: 원격 트렁크 열기 제어 요청
응답 수신: 202 Accepted 응답 수신
푸시 알림: 트렁크 제어 결과 푸시 알림 수신
UI 업데이트: 화면에 제어 결과 표시

🚗 차량 (TCU):

명령 수신: ECARUS로부터 트렁크 제어 명령 수신
안전 검증: 기어 상태(P단), 속도(0km/h), 장애물 감지 확인
모터 구동: 테일게이트 모터 구동을 통한 트렁크 개방
결과 게시: 성공/실패 결과를 ECARUS로 게시

🏢 콜센터:

대리 제어: 고객을 대신하여 트렁크 개방
상태 확인: 트렁크 상태 확인
결과 수신: 트렁크 제어 결과 수신

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

엔티티별 API 흐름:

📱 앱 (사용자):

명령 요청: 트렁크 열기 명령 요청
실패 알림: 푸시 알림을 통해 실패 원인 수신
상태 확인: 현재 트렁크 상태 확인
명령 취소: 실행 중인 명령 취소

🚗 차량 (TCU):

안전 검증: 주행 중이거나 후방 장애물 감지 여부 확인
실패 처리: 안전 조건 위반 시 실패 처리
결과 게시: 실패 결과 및 에러 코드 게시
안전 종료: 이상 상태 발생 시 자동 종료

🏢 콜센터:

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

시나리오 3: 트렁크 잠금 및 상태 모니터링

엔티티별 API 흐름:

📱 앱 (사용자):

트렁크 잠금: 원격 트렁크 잠금 제어 요청
상태 조회: 트렁크 상태 확인
사양 확인: 트렁크 사양 정보 확인
설정 관리: 트렁크 설정 조회 및 트렁크 설정 업데이트

🚗 차량 (TCU):

잠금 명령 수신: 트렁크 잠금 명령 수신
잠금 모터 구동: 트렁크 잠금 모터 구동
상태 전송: 잠금 상태 서버 전송
이벤트 게시: 상태 변경 이벤트 게시

🏢 콜센터:

상태 모니터링: 실시간 트렁크 상태 확인
사양 관리: 트렁크 사양 정보 관리
설정 관리: 고객 설정값 관리 및 트렁크 설정 업데이트
이력 관리: 제어 이력 관리

시나리오 4: 트렁크 진단 및 설정 관리

엔티티별 API 흐름:

📱 앱 (사용자):

진단 조회: 트렁크 시스템 진단 조회
사양 조회: 트렁크 사양 정보 조회
설정 조회: 트렁크 설정 조회
설정 업데이트: 트렁크 설정 업데이트

🚗 차량 (TCU):

진단 실행: 트렁크 관련 부품 상태 진단
사양 보고: 트렁크 사양 정보를 서버로 보고
설정 적용: 트렁크 설정값 자동 적용
상태 보고: 현재 트렁크 상태 보고

🏢 콜센터:

진단 관리: 시스템 진단 자동 관리
사양 관리: 트렁크 사양 정보 자동 관리
설정 지원: 고객 트렁크 설정 변경 지원 및 트렁크 설정 업데이트
문제 해결: 진단 결과 기반의 문제 해결

주요 기능

📱 앱 구현 기능

1. 원격 트렁크 제어 기능

트렁크 열기: 원격 트렁크 열기 제어 요청
트렁크 잠금: 원격 트렁크 잠금 제어 요청
명령 취소: 실행 중인 명령 취소 요청
상태 조회: 즉시 트렁크 상태 조회

2. 설정 관리 기능

설정 조회: 트렁크 설정 조회
설정 업데이트: 트렁크 설정 업데이트
사양 조회: 트렁크 사양 정보 조회

3. 실시간 모니터링 기능

실시간 업데이트: SSE 스트림을 통한 실시간 상태 모니터링
이벤트 처리: 트렁크 상태 변경 이벤트 실시간 처리
상태 표시: 트렁크 개폐 상태 실시간 표시

4. 알림 및 UI 기능

푸시 알림: 트렁크 제어 결과 푸시 알림 수신
에러 안내: 실패 시 사용자 친화적 에러 메시지 제공
상태 시각화: 트렁크 상태의 시각적 표현 제공

🏢 콜센터 구현 기능

1. 대리 트렁크 제어 기능

대리 열기: 고객을 대신하여 트렁크 개방
대리 잠금: 고객을 대신하여 트렁크 잠금
명령 취소: 명령 취소 처리
상태 확인: 트렁크 상태 확인

2. 이력 및 진단 관리 기능

이력 조회: 트렁크 제어 이력 조회
진단 조회: 트렁크 시스템 진단 조회
사양 조회: 트렁크 사양 정보 조회
통계 생성: 트렁크 제어 이용 통계 생성

3. 설정 관리 기능

설정 조회: 고객 트렁크 설정 확인
설정 업데이트: 고객 설정 변경 지원
설정 동기화: 차량과의 자동 설정 동기화

4. 고객 지원 기능

문제 해결: 트렁크 제어 실패 원인 분석
설정 지원: 고객 트렁크 설정 지원
보안 모니터링: 이상 접근 패턴 모니터링

🚗 차량(TCU) 처리 기능

1. 트렁크 제어 기능

명령 수신: 트렁크 제어 명령 수신
안전 검증: 기어 상태, 속도, 장애물 감지 확인
모터 구동: 테일게이트/잠금 모터 구동을 통한 제어 실행
결과 게시: 제어 결과 게시

2. 상태 관리 기능

상태 수집: 트렁크 상태 데이터 실시간 수집
이벤트 게시: 상태 변경 이벤트 게시
상태 보고: 현재 트렁크 상태 보고

3. 안전 기능

장애물 감지: 후방 초음파 센서를 통한 장애물 감지
끼임 방지: 끼임 발생 시 자동 정지 수행
안전 종료: 위험 상태 발생 시 자동 종료 수행

시퀀스 다이어그램

원격 트렁크 제어 시스템 흐름

원격 트렁크 제어

API 엔드포인트

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

트렁크 열기 요청

bash

curl -X POST "https://api.ecarus.run/api/v1/remotecontrol/vehicles/KMHSH81C7LU123456/trunk/open" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d" \
     -H "Content-Type: application/json" \
     -d '{"action": "OPEN"}'

트렁크 잠금 요청

bash

curl -X POST "https://api.ecarus.run/api/v1/remotecontrol/vehicles/KMHSH81C7LU123456/trunk/lock" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d" \
     -H "Content-Type: application/json" \
     -d '{"action": "LOCK"}'

트렁크 상태 조회

bash

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

트렁크 제어 취소 요청

bash

curl -X POST "https://api.ecarus.run/api/v1/remotecontrol/vehicles/KMHSH81C7LU123456/trunk/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/trunk/history?period=24h&limit=50" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d"

트렁크 사양 정보 조회

bash

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

트렁크 설정 조회

bash

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

트렁크 설정 업데이트

bash

curl -X PUT "https://api.ecarus.run/api/v1/remotecontrol/vehicles/KMHSH81C7LU123456/trunk/config" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d" \
     -H "Content-Type: application/json" \
     -d '{"trunk": {"remoteControlEnabled": true, "antiPinchSensitivity": "HIGH", "openSpeed": "SLOW"}, "safety": {"obstacleDetectionEnabled": true, "minSafeDistance": 75.0, "speedLimitEnabled": true}}'

트렁크 시스템 진단 조회

bash

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

트렁크 제어 정보 실시간 업데이트 수신 (SSE)

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

bash

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

데이터 모델

트렁크 제어 요청 (Control Request)

json

{
  "action": "OPEN"
}

action: OPEN, CLOSE, STOP

트렁크 제어 응답 (Control Response)

json

{
  "commandId": "cmd-uuid-12345",
  "vin": "KMHSH81C7LU123456",
  "status": "PENDING",
  "message": "트렁크 제어 명령이 수신되었습니다.",
  "estimatedDuration": 10,
  "timestamp": "2026-01-12T14:30:00Z"
}

status: PENDING, PROCESSING, SUCCESS, FAILED, CANCELLED

트렁크 상태 응답 (Status Response)

json

{
  "vin": "KMHSH81C7LU123456",
  "isOpen": false,
  "isLocked": true,
  "isMoving": false,
  "hasPowerTailgate": true,
  "openingHeight": 0,
  "lastAction": "CLOSE",
  "timestamp": "2026-01-12T14:30:00Z"
}

openingHeight: 0-100% (0=완전 닫힘, 100=완전 열림)

트렁크 취소 요청 (Cancellation Request)

json

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

reason: User cancellation, Safety stop, System error, Emergency stop
force: 강제 취소 여부 (true인 경우 즉시 정지)

트렁크 제어 이력 요청 (History Request)

vin: KMHSH81C7LU123456
period: 24h
limit: 50
offset: 0

period: 1h, 24h, 7d, 30d

트렁크 제어 이력 응답

json

{
  "vin": "KMHSH81C7LU123456",
  "history": [
    {
      "commandId": "cmd-uuid-12345",
      "action": "OPEN",
      "timestamp": "2026-01-12T14:30:00Z",
      "status": "SUCCESS",
      "executionTime": 10,
      "userId": "user-123",
      "source": "APP"
    }
  ],
  "total": 1,
  "hasMore": false
}

source: APP, CALL_CENTER, SYSTEM
status: PENDING, PROCESSING, SUCCESS, FAILED, CANCELLED

트렁크 사양 정보 응답 (Specification Response)

json

{
  "vin": "KMHSH81C7LU123456",
  "trunkType": "POWER_TAILGATE",
  "maxOpeningHeight": 2000,
  "hasAntiPinch": true,
  "hasHandsFree": true,
  "loadCapacity": 500,
  "openingModes": ["MANUAL", "POWER", "HANDS_FREE"],
  "safetyFeatures": ["ANTI_PINCH", "OBSTACLE_DETECTION", "SPEED_LIMIT"]
}

trunkType: MANUAL, POWER_TAILGATE, ELECTRIC
maxOpeningHeight: 최대 개방 높이 (mm)
loadCapacity: 최대 적재 하중 (kg)

트렁크 설정 응답 (Settings Response)

json

{
  "vin": "KMHSH81C7LU123456",
  "trunk": {
    "remoteControlEnabled": true,
    "antiPinchSensitivity": "HIGH",
    "openSpeed": "SLOW",
    "autoCloseEnabled": true,
    "handsFreeEnabled": true
  },
  "safety": {
    "obstacleDetectionEnabled": true,
    "minSafeDistance": 75.0,
    "speedLimitEnabled": true,
    "maxOperatingSpeed": 5.0
  },
  "updatedTime": "2026-01-12T10:00:00Z"
}

antiPinchSensitivity: LOW, MEDIUM, HIGH
openSpeed: SLOW, NORMAL, FAST
maxOperatingSpeed: 최대 동작 속도 (km/h)

트렁크 진단 정보 응답 (Diagnostics Response)

json

{
  "vin": "KMHSH81C7LU123456",
  "systemStatus": "NORMAL",
  "components": [
    {
      "name": "Trunk Motor",
      "status": "ACTIVE",
      "health": 98,
      "lastMaintenance": "2025-06-15T00:00:00Z",
      "operatingHours": 850
    },
    {
      "name": "Anti-Pinch Sensor",
      "status": "ACTIVE",
      "health": 95,
      "lastCalibration": "2025-12-01T00:00:00Z",
      "sensitivityLevel": "HIGH"
    },
    {
      "name": "Obstacle Sensor",
      "status": "ACTIVE",
      "health": 100,
      "lastTest": "2026-01-10T14:30:00Z"
    }
  ],
  "alerts": [],
  "lastCheck": "2026-01-12T14:30:00Z"
}

systemStatus: NORMAL, WARNING, ERROR, OFFLINE
component.status: ACTIVE, INACTIVE, ERROR, MAINTENANCE_REQUIRED

트렁크 업데이트 알림 (SSE)

json

{
  "type": "TRUNK_STATUS_UPDATE",
  "vin": "KMHSH81C7LU123456",
  "timestamp": "2026-01-12T14:30:10Z",
  "data": {
    "isOpen": true,
    "isLocked": false,
    "isMoving": false,
    "openingHeight": 100,
    "changeType": "OPENED"
  }
}

type: TRUNK_STATUS_UPDATE, TRUNK_COMMAND_RESULT, TRUNK_SAFETY_ALERT
changeType: OPENED, CLOSED, STOPPED, OBSTRUCTION_DETECTED, SAFETY_STOP

보안 및 프라이버시

인증 및 권한 부여

사용자 인증 토큰 필요 (JWT/OAuth2)
차량 접근 권한 확인
트렁크 제어 권한 확인
다중 요소 인증(MFA) 지원

데이터 보안

모든 API 통신은 HTTPS/TLS 암호화
명령 위조 방지를 위한 Command Signing 적용
mTLS 기반의 통신 보안 강화

프라이버시 보호

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

접근 제어

VIN 기반 차량 접근 권한 확인
다중 요소 인증(MFA) 요구
명령 호출 제한(Rate Limit) 적용
위치 기반 제한(Geo-fencing) 적용

예외 처리

네트워크 관련

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

차량 상태 관련

차량 오프라인: 명령 전송 실패 알림, 큐 처리
주행 중: 기능 제한 알림 및 안내 메시지 표시
배터리 부족: 전동 테일게이트 작동 제한 알림

보안 관련

인증 실패: 재인증 요청, 보안 강화 안내
권한 없음: 권한 부족 사유 명확히 표시
위치 제한: Geo-fencing 영역 밖에서 제어 제한 알림

명령 실행 관련

물리적 장애물: 트렁크 액추에이터 에러 알림
타임아웃: 명령 유효 시간(TTL) 만료 알림
일부 성공: 일부 기능만 작동 시 상세 안내

테스트 설정

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

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

배포 고려사항

앱 스토어 등록

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

법규 준수

개인정보 보호법 준수
차량 보안 관련 규정 확인
명령 감사 로그(Command Audit Log) 관련 법령 준수

차량 호환성

다양한 차종 지원
전동 테일게이트 유무에 따른 기능 차이 반영
OEM별 트렁크 제어 방식 차이 고려

원격 트렁크 제어 API 개발자 가이드 ​

서비스 개요 ​

서비스 특징 ​

법적 요구사항 ​

주요 시나리오 ​

시나리오 1: 원격 트렁크 제어 요청 및 실행 ​

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

시나리오 3: 트렁크 잠금 및 상태 모니터링 ​

시나리오 4: 트렁크 진단 및 설정 관리 ​

주요 기능 ​

📱 앱 구현 기능 ​

1. 원격 트렁크 제어 기능 ​

2. 설정 관리 기능 ​

3. 실시간 모니터링 기능 ​

4. 알림 및 UI 기능 ​

🏢 콜센터 구현 기능 ​

1. 대리 트렁크 제어 기능 ​

2. 이력 및 진단 관리 기능 ​

3. 설정 관리 기능 ​

4. 고객 지원 기능 ​

🚗 차량(TCU) 처리 기능 ​

1. 트렁크 제어 기능 ​

2. 상태 관리 기능 ​

3. 안전 기능 ​

시퀀스 다이어그램 ​

원격 트렁크 제어 시스템 흐름 ​

API 엔드포인트 ​

트렁크 열기 요청 ​

트렁크 잠금 요청 ​

트렁크 상태 조회 ​

트렁크 제어 취소 요청 ​

트렁크 제어 이력 조회 ​

트렁크 사양 정보 조회 ​

트렁크 설정 조회 ​

트렁크 설정 업데이트 ​

트렁크 시스템 진단 조회 ​

트렁크 제어 정보 실시간 업데이트 수신 (SSE) ​

데이터 모델 ​

트렁크 제어 요청 (Control Request) ​

트렁크 제어 응답 (Control Response) ​

트렁크 상태 응답 (Status Response) ​

트렁크 취소 요청 (Cancellation Request) ​

트렁크 제어 이력 요청 (History Request) ​

트렁크 제어 이력 응답 ​

트렁크 사양 정보 응답 (Specification Response) ​

트렁크 설정 응답 (Settings Response) ​

트렁크 진단 정보 응답 (Diagnostics Response) ​

트렁크 업데이트 알림 (SSE) ​

보안 및 프라이버시 ​

인증 및 권한 부여 ​

데이터 보안 ​

프라이버시 보호 ​

접근 제어 ​

예외 처리 ​

네트워크 관련 ​

차량 상태 관련 ​

보안 관련 ​

명령 실행 관련 ​

테스트 설정 ​

배포 고려사항 ​

앱 스토어 등록 ​

법규 준수 ​

차량 호환성 ​

원격 트렁크 제어 API 개발자 가이드

서비스 개요

서비스 특징

법적 요구사항

주요 시나리오

시나리오 1: 원격 트렁크 제어 요청 및 실행

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

시나리오 3: 트렁크 잠금 및 상태 모니터링

시나리오 4: 트렁크 진단 및 설정 관리

주요 기능

📱 앱 구현 기능

1. 원격 트렁크 제어 기능

2. 설정 관리 기능

3. 실시간 모니터링 기능

4. 알림 및 UI 기능

🏢 콜센터 구현 기능

1. 대리 트렁크 제어 기능

2. 이력 및 진단 관리 기능

3. 설정 관리 기능

4. 고객 지원 기능

🚗 차량(TCU) 처리 기능

1. 트렁크 제어 기능

2. 상태 관리 기능

3. 안전 기능

시퀀스 다이어그램

원격 트렁크 제어 시스템 흐름

API 엔드포인트

트렁크 열기 요청

트렁크 잠금 요청

트렁크 상태 조회

트렁크 제어 취소 요청

트렁크 제어 이력 조회

트렁크 사양 정보 조회

트렁크 설정 조회

트렁크 설정 업데이트

트렁크 시스템 진단 조회

트렁크 제어 정보 실시간 업데이트 수신 (SSE)

데이터 모델

트렁크 제어 요청 (Control Request)

트렁크 제어 응답 (Control Response)

트렁크 상태 응답 (Status Response)

트렁크 취소 요청 (Cancellation Request)

트렁크 제어 이력 요청 (History Request)

트렁크 제어 이력 응답

트렁크 사양 정보 응답 (Specification Response)

트렁크 설정 응답 (Settings Response)

트렁크 진단 정보 응답 (Diagnostics Response)

트렁크 업데이트 알림 (SSE)

보안 및 프라이버시

인증 및 권한 부여

데이터 보안

프라이버시 보호

접근 제어

예외 처리

네트워크 관련

차량 상태 관련

보안 관련

명령 실행 관련

테스트 설정

배포 고려사항

앱 스토어 등록

법규 준수

차량 호환성