원격 공조 제어 API 개발자 가이드

서비스 개요

원격 공조 제어는 사용자가 탑승 전 모바일 앱을 통해 차량의 공조 시스템(HVAC)을 원격으로 제어하여 실내 온도를 쾌적한 상태로 미리 조절할 수 있는 텔레매틱스 서비스입니다.

서비스 특징

탑승 전 실내 온도 최적화
여름철 냉방 및 겨울철 난방 지원
전기차 배터리 효율 향상 및 주행 거리 연장
자동 종료 정책을 통한 배터리 보호
엔진 시동 없는 독립적 공조 작동 (EV/HEV)

법적 요구사항

차량 제어 기능에 따른 보안 정책 필수
개인정보 보호법 준수
위치 기반 제한 정책 적용
명령 호출 제한(Rate Limit) 적용

주요 시나리오

시나리오 1: 원격 공조 시작 및 안전 검증

엔티티별 API 흐름:

📱 앱 (사용자):

공조 시작 요청: 원격 공조 시작 요청
응답 수신: 202 Accepted 응답 수신
결과 알림: 푸시 알림을 통해 성공/실패 결과 수신
상태 확인: 성공 시 상태 확인, 실패 시 에러 메시지 확인

🚗 차량 (TCU):

명령 수신: 서버로부터 공조 시작 명령 수신
안전 검증: 문 열림, 배터리 레벨 등 안전 조건 확인
공조 제어: 안전 조건 충족 시 공조 시스템 가동
결과 전송: 실행 결과(성공/실패 코드 포함)를 서버로 전송

🏢 콜센터:

명령 처리: 공조 시작 명령 처리
상태 관리: 명령 상태 자동 관리 (PENDING → SUCCESS/FAIL)
결과 처리: 차량으로부터 수신된 결과 처리
에러 매핑: 기술적 에러 코드를 사용자 친화적 메시지로 변환
이력 저장: 명령 실행 이력 자동 저장
알림 전송: 푸시 알림을 통해 결과 전송

시나리오 2: 공조 상태 조회 및 모니터링

엔티티별 API 흐름:

📱 앱 (사용자):

상태 조회: 즉시 공조 상태 조회
상태 표시: 현재 공조 상태 정보 표시

🏢 콜센터:

상태 제공: 최신 공조 상태 제공
상태 관리: 공조 상태 정보 자동 관리

시나리오 3: 공조 제어 취소 및 정지

엔티티별 API 흐름:

📱 앱 (사용자):

취소 요청: 공조 제어 취소 요청
결과 확인: 취소 성공 메시지 확인

🚗 차량 (TCU):

취소 명령 수신: 서버로부터 취소 명령 수신
공조 정지: 공조 시스템 즉시 정지
결과 전송: 취소 결과를 서버로 전송

🏢 콜센터:

취소 처리: 취소 명령 처리
명령 전송: 차량으로 취소 명령 전송
이력 저장: 취소 이력 자동 저장

시나리오 4: 공조 제어 이력 조회

엔티티별 API 흐름:

🏢 콜센터:

이력 조회: 공조 제어 이력 조회
이력 제공: 기간별 제어 이력 정보 제공

시나리오 5: 공조 환경 설정 관리

엔티티별 API 흐름:

📱 앱 (사용자):

설정 조회: 공조 환경 설정 조회
설정 업데이트: 환경 설정 업데이트
결과 확인: 설정 업데이트 성공 확인

🏢 콜센터:

설정 관리: 환경 설정 자동 관리 및 환경 설정 업데이트
설정 저장: 사용자 환경 설정 보안 저장

시나리오 6: 공조 시스템 진단

엔티티별 API 흐름:

🏢 콜센터:

진단 조회: 공조 시스템 진단 조회
진단 정보 제공: 시스템 상태, 부품 상태, 마지막 점검 정보 제공

주요 기능

📱 앱 구현 기능

1. 원격 공조 제어 기능

공조 시작: 원격 공조 시작 요청
공조 취소: 공조 제어 취소 요청
상태 조회: 즉시 공조 상태 조회
결과 알림: 공조 제어 성공/실패 푸시 알림 수신

2. 환경 설정 관리 기능

설정 조회: 공조 환경 설정 조회
설정 업데이트: 환경 설정 업데이트
개인화: 목표 온도, 모드, 풍량 등 개인 설정 관리

3. 상태 모니터링 기능

실시간 상태: 실시간 공조 상태 표시
에러 핸들링: 실패 시 사용자 친화적 에러 메시지 표시
안전 검증: 문 열림, 배터리 부족 등 안전 상태 확인

🏢 콜센터 구현 기능

1. 공조 제어 명령 처리 시스템

명령 처리: 공조 시작 명령 처리
취소 처리: 공조 취소 명령 처리
명령 큐: 명령 요청 큐 자동 관리
명령 라우팅: 차량으로 명령 자동 라우팅
상태 관리: 명령 상태 자동 관리 (PENDING → SUCCESS/FAIL)

2. 안전 검증 시스템

안전 조건 확인: 문 열림, 배터리 레벨 등 안전 조건 자동 확인
에러 핸들링: 안전 조건 위반 시 적절한 에러 코드 생성
에러 매핑: 기술적 에러 코드를 사용자 친화적 메시지로 변환
결과 전송: 검증 결과를 차량 및 앱으로 전송

3. 이력 관리 시스템

이력 저장: 공조 제어 이력 자동 저장
이력 조회: 기간별 제어 이력 조회 기능 제공
통계 생성: 공조 사용 통계 자동 생성
분석 리포트: 공조 사용 패턴 분석 리포트 생성

4. 환경 설정 관리 시스템

설정 관리: 사용자 환경 설정 자동 관리 및 환경 설정 업데이트
설정 저장: 개인화된 공조 설정 보안 저장
설정 동기화: 차량과 앱 간의 설정 동기화

5. 진단 시스템

시스템 진단: 공조 시스템 자동 진단
부품 상태 모니터링: 컴프레서, 팬, 센서 등 부품 상태 모니터링
정비 이력 관리: 마지막 정비 정보 관리
진단 리포트: 상세 진단 정보 제공

6. API 서비스 관리

API 응답 처리: 공조 제어 관련 API 응답 처리
요청 검증: API 요청 유효성 검증
성능 모니터링: API 응답 시간 및 가용성 모니터링
에러 핸들링: API 에러 및 예외 상황 처리
버전 관리: API 버전 관리 및 호환성 유지

7. 보안 및 개인정보 보호

공조 제어 동의: 공조 제어 기능 사용 동의 관리
개인정보 보호: 사용자 공조 설정 개인정보 보호
데이터 보안: 공조 제어 데이터의 안전한 처리
감사 로그: 공조 제어 접근 및 처리 감사 로그 유지
권한 관리: 사용자별 공조 제어 접근 권한 관리

시퀀스 다이어그램

원격 공조 제어 시스템 흐름

원격 공조 제어

API 엔드포인트

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

원격 공조 제어 시작 요청

bash

curl -X POST "https://api.ecarus.run/api/v1/remotecontrol/vehicles/KMHSH81C7LU123456/climate/start" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d" \
     -H "Content-Type: application/json" \
     -d '{"targetTemperature": 22.5, "mode": "AUTO", "fanSpeed": "MEDIUM", "duration": 1800}'

공조 제어 상태 조회

bash

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

원격 공조 제어 취소 요청

bash

curl -X POST "https://api.ecarus.run/api/v1/remotecontrol/vehicles/KMHSH81C7LU123456/climate/cancel" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d" \
     -H "Content-Type: application/json" \
     -d '{"reason": "사용자 취소 요청"}'

원격 공조 제어 정지 요청

bash

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

공조 제어 이력 조회

bash

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

공조 환경 설정 조회

bash

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

환경 설정 업데이트

bash

curl -X PUT "https://api.ecarus.run/api/v1/remotecontrol/vehicles/KMHSH81C7LU123456/climate/preferences" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d" \
     -H "Content-Type: application/json" \
     -d '{"targetTemperature": 22.0, "mode": "AUTO", "fanSpeed": "MEDIUM", "airCirculation": "AUTO", "ecoMode": false}'

공조 시스템 진단 정보 조회

bash

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

공조 제어 실시간 업데이트 수신 (SSE)

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

bash

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

데이터 모델

공조 제어 시작 요청 (Start Request)

json

{
  "userId": "user123",
  "targetTemperature": 22.5,
  "mode": "AUTO",
  "fanSpeed": "MEDIUM",
  "airCirculation": "AUTO",
  "ecoMode": false,
  "duration": 1800,
  "reason": "출발 전 사전 냉방",
  "priority": "NORMAL"
}

공조 제어 시작 응답 (Start Response)

json

{
  "commandId": "cmd-uuid-12345",
  "vin": "KMHSH81C7LU123456",
  "userId": "user123",
  "status": "PENDING",
  "estimatedDuration": 1800,
  "batteryImpact": {
    "estimatedConsumption": 2.5,
    "unit": "kWh",
    "currentSOC": 75.5,
    "estimatedSOCAfter": 73.0
  },
  "timestamp": "2026-01-12T08:30:00Z",
  "expiresAt": "2026-01-12T08:35:00Z"
}

공조 제어 상태 응답 (Status Response)

json

{
  "vin": "KMHSH81C7LU123456",
  "commandId": "cmd-uuid-12345",
  "userId": "user123",
  "isRunning": true,
  "currentTemperature": 18.5,
  "targetTemperature": 22.0,
  "mode": "AUTO",
  "fanSpeed": "MEDIUM",
  "airCirculation": "AUTO",
  "ecoMode": false,
  "remainingTime": 1500,
  "elapsedTime": 300,
  "batterySOC": 75.5,
  "batteryImpact": {
    "consumed": 0.5,
    "unit": "kWh",
    "currentSOC": 75.5,
    "estimatedSOCAfter": 73.0
  },
  "hvacSystemStatus": "NORMAL",
  "timestamp": "2026-01-12T08:45:00Z"
}

공조 제어 취소/정지 요청

json

{
  "commandId": "cmd-uuid-12345",
  "reason": "사용자 취소 요청",
  "force": false,
  "userId": "user123"
}

공조 제어 이력 요청

json

{
  "period": "24h",
  "limit": 50
}

공조 제어 이력 응답

json

{
  "vin": "KMHSH81C7LU123456",
  "userId": "user123",
  "history": [
    {
      "commandId": "cmd-uuid-12345",
      "startTime": "2026-01-12T08:30:45Z",
      "endTime": "2026-01-12T09:00:00Z",
      "duration": 1745,
      "status": "COMPLETED",
      "targetTemperature": 22.5,
      "mode": "AUTO",
      "fanSpeed": "MEDIUM",
      "airCirculation": "AUTO",
      "ecoMode": false,
      "batteryImpact": {
        "consumed": 2.3,
        "unit": "kWh",
        "startSOC": 75.5,
        "endSOC": 73.2
      },
      "reason": "출발 전 사전 냉방",
      "success": true
    }
  ],
  "total": 1,
  "pagination": {
    "page": 1,
    "limit": 50,
    "hasMore": false
  }
}

공조 환경 설정 응답

json

{
  "vin": "KMHSH81C7LU123456",
  "userId": "user123",
  "preferences": {
    "targetTemperature": 22.0,
    "mode": "AUTO",
    "fanSpeed": "MEDIUM",
    "airCirculation": "AUTO",
    "ecoMode": false,
    "defaultDuration": 1800,
    "maxDuration": 3600,
    "autoStart": {
      "enabled": true,
      "schedule": [
        {
          "dayOfWeek": "MONDAY",
          "time": "08:00",
          "targetTemperature": 22.0,
          "duration": 900
        }
      ]
    },
    "notifications": {
      "completion": true,
      "lowBattery": true,
      "error": true
    }
  },
  "updatedTime": "2026-01-12T10:00:00Z"
}

공조 시스템 진단 응답

json

{
  "vin": "KMHSH81C7LU123456",
  "userId": "user123",
  "hvacSystemStatus": "NORMAL",
  "overallHealth": 96.5,
  "components": [
    {
      "id": "COMP_001",
      "name": "Compressor",
      "status": "ACTIVE",
      "health": 95,
      "temperature": 45.2,
      "pressure": 120.5,
      "lastMaintenance": "2025-06-15T00:00:00Z",
      "nextMaintenance": "2026-06-15T00:00:00Z",
      "warnings": []
    },
    {
      "id": "BLOWER_001",
      "name": "Blower Motor",
      "status": "ACTIVE",
      "health": 98,
      "speed": 1500,
      "voltage": 12.3,
      "lastMaintenance": "2025-08-20T00:00:00Z",
      "nextMaintenance": "2026-08-20T00:00:00Z",
      "warnings": []
    },
    {
      "id": "FILTER_001",
      "name": "Cabin Air Filter",
      "status": "ACTIVE",
      "health": 85,
      "contaminationLevel": 15,
      "lastReplacement": "2025-03-10T00:00:00Z",
      "nextReplacement": "2026-03-10T00:00:00Z",
      "warnings": [
        {
          "code": "FILTER_REPLACEMENT_SOON",
          "message": "3개월 이내 필터 교체 권장",
          "severity": "LOW"
        }
      ]
    }
  ],
  "sensors": [
    {
      "id": "TEMP_IN_001",
      "name": "Interior Temperature Sensor",
      "status": "ACTIVE",
      "value": 18.5,
      "unit": "°C",
      "calibration": "VALID"
    },
    {
      "id": "TEMP_OUT_001",
      "name": "Exterior Temperature Sensor",
      "status": "ACTIVE",
      "value": 12.3,
      "unit": "°C",
      "calibration": "VALID"
    }
  ],
  "errors": [],
  "warnings": [
    {
      "code": "FILTER_REPLACEMENT_SOON",
      "message": "항균 필터 교체 권장",
      "severity": "LOW",
      "component": "FILTER_001"
    }
  ],
  "lastCheck": "2026-01-12T08:30:00Z",
  "nextCheck": "2026-01-19T08:30:00Z"
}

공조 제어 실시간 업데이트 수신 (SSE)

json

{
  "type": "CLIMATE_STATUS_UPDATE",
  "vin": "KMHSH81C7LU123456",
  "userId": "user123",
  "commandId": "cmd-uuid-12345",
  "timestamp": "2026-01-12T08:45:00Z",
  "data": {
    "isRunning": true,
    "currentTemperature": 18.5,
    "targetTemperature": 22.0,
    "mode": "AUTO",
    "fanSpeed": "MEDIUM",
    "airCirculation": "AUTO",
    "ecoMode": false,
    "remainingTime": 1500,
    "elapsedTime": 300,
    "batterySOC": 75.5,
    "batteryImpact": {
      "consumed": 0.5,
      "unit": "kWh",
      "currentSOC": 75.5,
      "estimatedSOCAfter": 73.0
    },
    "hvacSystemStatus": "NORMAL",
    "alerts": []
  }
}

보안 및 프라이버시

인증 및 권한 부여

사용자 인증 토큰 필요 (JWT/OAuth2)
차량 접근 권한 확인
공조 제어 권한 확인

데이터 보안

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

프라이버시 보호

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

접근 제어

VIN 기반 차량 접근 권한 확인
명령 호출 제한(Rate Limit) 적용
위치 기반 제한 정책 적용

예외 처리

네트워크 관련

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

차량 상태 관련

차량 오프라인: 명령 전송 실패 알림, 큐 처리
배터리 부족: 실행 불가 알림, 충전 권장
차량 문 열림: 보안상 실행 불가 알림

명령 실행 관련

명령 실패: 실패 원인 명확히 표시
일부 성공: 일부 기능만 작동 시 상세 안내
자동 종료: 종료 원인 명확히 표시

테스트 설정

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

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

배포 고려사항

앱 스토어 등록

차량 제어 권한 요청
위치 정보 수집에 대한 명확한 설명
배터리 최적화 관련 권한 확인

법규 준수

개인정보 보호법 준수
차량 제어 관련 법규 확인
명령 호출 제한(Rate Limit) 정책 준수

차량 호환성

내연기관/전기차/하이브리드 지원
OEM별 공조 시스템 차이 고려
차종별 기능 제한 사항 반영

원격 공조 제어 API 개발자 가이드 ​

서비스 개요 ​

서비스 특징 ​

법적 요구사항 ​

주요 시나리오 ​

시나리오 1: 원격 공조 시작 및 안전 검증 ​

시나리오 2: 공조 상태 조회 및 모니터링 ​

시나리오 3: 공조 제어 취소 및 정지 ​

시나리오 4: 공조 제어 이력 조회 ​

시나리오 5: 공조 환경 설정 관리 ​

시나리오 6: 공조 시스템 진단 ​

주요 기능 ​

📱 앱 구현 기능 ​

1. 원격 공조 제어 기능 ​

2. 환경 설정 관리 기능 ​

3. 상태 모니터링 기능 ​

🏢 콜센터 구현 기능 ​

1. 공조 제어 명령 처리 시스템 ​

2. 안전 검증 시스템 ​

3. 이력 관리 시스템 ​

4. 환경 설정 관리 시스템 ​

5. 진단 시스템 ​

6. API 서비스 관리 ​

7. 보안 및 개인정보 보호 ​

시퀀스 다이어그램 ​

원격 공조 제어 시스템 흐름 ​

API 엔드포인트 ​

원격 공조 제어 시작 요청 ​

공조 제어 상태 조회 ​

원격 공조 제어 취소 요청 ​

원격 공조 제어 정지 요청 ​

공조 제어 이력 조회 ​

공조 환경 설정 조회 ​

환경 설정 업데이트 ​

공조 시스템 진단 정보 조회 ​

공조 제어 실시간 업데이트 수신 (SSE) ​

데이터 모델 ​

공조 제어 시작 요청 (Start Request) ​

공조 제어 시작 응답 (Start Response) ​

공조 제어 상태 응답 (Status Response) ​

공조 제어 취소/정지 요청 ​

공조 제어 이력 요청 ​

공조 제어 이력 응답 ​

공조 환경 설정 응답 ​

공조 시스템 진단 응답 ​

공조 제어 실시간 업데이트 수신 (SSE) ​

보안 및 프라이버시 ​

인증 및 권한 부여 ​

데이터 보안 ​

프라이버시 보호 ​

접근 제어 ​

예외 처리 ​

네트워크 관련 ​

차량 상태 관련 ​

명령 실행 관련 ​

테스트 설정 ​

배포 고려사항 ​

앱 스토어 등록 ​

법규 준수 ​

차량 호환성 ​

원격 공조 제어 API 개발자 가이드

서비스 개요

서비스 특징

법적 요구사항

주요 시나리오

시나리오 1: 원격 공조 시작 및 안전 검증

시나리오 2: 공조 상태 조회 및 모니터링

시나리오 3: 공조 제어 취소 및 정지

시나리오 4: 공조 제어 이력 조회

시나리오 5: 공조 환경 설정 관리

시나리오 6: 공조 시스템 진단

주요 기능

📱 앱 구현 기능

1. 원격 공조 제어 기능

2. 환경 설정 관리 기능

3. 상태 모니터링 기능

🏢 콜센터 구현 기능

1. 공조 제어 명령 처리 시스템

2. 안전 검증 시스템

3. 이력 관리 시스템

4. 환경 설정 관리 시스템

5. 진단 시스템

6. API 서비스 관리

7. 보안 및 개인정보 보호

시퀀스 다이어그램

원격 공조 제어 시스템 흐름

API 엔드포인트

원격 공조 제어 시작 요청

공조 제어 상태 조회

원격 공조 제어 취소 요청

원격 공조 제어 정지 요청

공조 제어 이력 조회

공조 환경 설정 조회

환경 설정 업데이트

공조 시스템 진단 정보 조회

공조 제어 실시간 업데이트 수신 (SSE)

데이터 모델

공조 제어 시작 요청 (Start Request)

공조 제어 시작 응답 (Start Response)

공조 제어 상태 응답 (Status Response)

공조 제어 취소/정지 요청

공조 제어 이력 요청

공조 제어 이력 응답

공조 환경 설정 응답

공조 시스템 진단 응답

공조 제어 실시간 업데이트 수신 (SSE)

보안 및 프라이버시

인증 및 권한 부여

데이터 보안

프라이버시 보호

접근 제어

예외 처리

네트워크 관련

차량 상태 관련

명령 실행 관련

테스트 설정

배포 고려사항

앱 스토어 등록

법규 준수

차량 호환성