차량 상태 확인 API 개발자 가이드

서비스 개요

원격 차량 상태 서비스는 모바일 앱이나 웹 플랫폼을 통해 사용자가 차량의 현재 상태 정보를 원격으로 조회할 수 있는 텔레매틱스 서비스입니다.

서비스 특징

실시간 원격 차량 상태 조회
차량 제어 기능이 없는 조회 전용 서비스
사용자 편의 중심의 상태 확인
차량 이용 계획 수립 지원
차량 관리 효율성 향상

법적 요구사항

개인정보 보호법 준수
차량 상태 정보 수집에 대한 명시적 동의 필요
위치 정보에 대한 별도 동의 필요
데이터 보유 정책 준수

주요 시나리오

시나리오 1: 차량 상태 업데이트 요청 및 처리

엔티티별 API 흐름:

📱 앱 (사용자):

업데이트 요청: 최신 차량 상태 업데이트 요청
대시보드 조회: 표시를 위한 전체 차량 상태 조회
위치 확인: 현재 차량 위치 확인
이용 모니터링: 주행 거리 및 연료 레벨 모니터링 및 연료 상태 조회

시나리오 2: 직접 차량 상태 조회

엔티티별 API 흐름:

📱 앱 (사용자):

상태 조회: 전체 차량 상태 조회
대시보드 표시: 종합 차량 상태 대시보드 표시

🏢 콜센터:

상태 제공: 앱에 최신 차량 상태 제공
이력 조회: 분석을 위한 상태 변경 이력 조회
이벤트 스트리밍: SSE를 통한 실시간 상태 업데이트 제공

시나리오 3: 부품별 상세 상태 조회

엔티티별 API 흐름:

📱 앱 (사용자):

차량 위치 조회: 차량 위치 조회
연료 상태 조회: 연료/배터리 상태 조회
주행 거리 조회: 적산 거리계 조회

🏢 콜센터:

부품별 상태 제공: 각 부품별 상세 상태 제공
부품별 분석: 부품별 상태 분석 및 경고 생성

시나리오 4: 상태 이력 조회 및 분석

엔티티별 API 흐름:

📱 앱 (사용자):

이력 조회: 상태 변경 이력 조회
추이 차트 표시: 상태 변경 추이 차트 표시

🏢 콜센터:

이력 관리: 상태 변경 이력 자동 관리
패턴 분석: 상태 변경 패턴 분석
통계 생성: 상태 관련 통계 자동 생성

시나리오 5: 상태 알림 설정 및 관리

엔티티별 API 흐름:

📱 앱 (사용자):

알림 설정 조회: 알림 설정 조회
알림 설정 업데이트: 알림 설정 업데이트

🏢 콜센터:

설정 관리: 알림 설정 자동 관리
임계치 관리: 부품별 임계치 관리
알림 전송: 설정된 알림 자동 전송

시나리오 6: 실시간 상태 이벤트 수신

엔티티별 API 흐름:

📱 앱 (사용자):

SSE 연결: 실시간 상태 이벤트 스트림 연결
실시간 수신: 실시간으로 차량 상태 변경 수신

🏢 콜센터:

이벤트 스트림 제공: 실시간 상태 이벤트 스트림 제공
이벤트 전송: 실시간으로 상태 변경 이벤트 전송

시나리오 7: 상태 분석 및 통계

엔티티별 API 흐름:

📱 앱 (사용자):

분석 조회: 상태 분석 데이터 조회

🏢 콜센터:

상태 분석: 평균 엔진 온도, 배터리 건강 추이 등 분석
통계 제공: 상태 관련 통계 데이터 제공
정비 점수: 차량 정비 점수 계산

시나리오 8: 비상 상황 대응

엔티티별 API 흐름:

🏢 콜센터:

비상 알림 생성: 엔진 과열 등 비상 상황 감지 시 알림 생성
비상 연락: 사용자와 비상 전화 연락
견인차 지원: 비상 상황 시 견인차 출동 요청

📱 앱 (사용자):

비상 알림 수신: "엔진 과열이 감지되었습니다. 즉시 안전한 곳에 정차하십시오." 알림 수신

주요 기능

📱 앱 구현 기능

1. 차량 상태 조회 및 모니터링

전체 상태: 전체 차량 상태 조회
차량 위치: 현재 차량 위치 조회
연료 상태: 연료 또는 배터리 레벨 확인
주행 거리 조회: 차량 적산 거리 확인
상태 새로고침: 차량 상태 업데이트 요청
알림 모니터링: 활성 상태 알림 확인

2. 상태 이력 및 분석

이력 조회: 과거 상태 변경 이력 조회
SSE 스트림: 실시간 상태 업데이트 스트림 연결

3. 상태 분석 조회

분석 데이터 조회: 상태 분석 데이터 조회
정비 점수: 차량 정비 점수 확인
효율성 분석: 차량 효율성 관련 분석 정보 확인

🏢 콜센터 구현 기능

1. 차량 상태 데이터 수집 시스템

데이터 수신: 실시간 차량 상태 데이터 수신
데이터 저장: 상태 데이터의 안전한 저장
상태 관리: 최신 상태 자동 관리
품질 관리: 상태 데이터 품질 및 정확성 관리
데이터 검증: 상태 데이터 유효성 검증

2. 상태 이력 관리 시스템

이력 수집: 상태 변경 이력 자동 수집
이력 관리: 상태 이력 자동 관리
패턴 분석: 상태 변경 패턴 자동 분석
통계 생성: 상태 관련 통계 자동 생성

3. 알림 및 경고 시스템

알림 설정 관리: 알림 설정 자동 관리
임계치 관리: 부품별 임계치 자동 관리
알림 생성: 상태 이상 감지 시 알림 자동 생성
푸시 알림: 사용자 앱으로 푸시 알림 자동 전송
비상 알림: 비상 상황에 대한 즉각적인 알림

4. 상태 분석 시스템

상태 분석: 상태 분석 자동 실행
통계 생성: 상태 관련 통계 자동 생성
정비 점수: 차량 정비 점수 자동 계산
효율성 분석: 차량 효율성 자동 분석

5. API 서비스 관리

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

6. 보안 및 프라이버시

상태 수집 동의: 차량 상태 데이터 수집 동의 관리
프라이버시 보호: 사용자 차량 상태 정보 프라이버시 보호
데이터 보안: 차량 상태 데이터의 안전한 처리
감사 로깅: 상태 정보 접근 및 처리에 대한 감사 로그 유지
접근 제어: 사용자별 상태 정보 접근 권한 관리

7. 시스템 운영 및 모니터링

시스템 상태 모니터링: 차량 상태 시스템 24시간 모니터링
데이터 품질 관리: 상태 데이터 품질 및 정확성 관리
센서 상태 모니터링: 차량 센서 통신 상태 모니터링
예외 처리: 네트워크, 센서, 데이터 처리 예외 대응
시스템 최적화: 상태 데이터 처리 로직 최적화

8. 데이터 분석 및 통계

상태 패턴 분석: 차량 상태 변경 패턴 자동 분석
이용 통계: 상태 조회 이용 통계 자동 생성
고장 통계: 차량 고장 관련 통계 자동 생성
서비스 품질 분석: 상태 서비스 품질 자동 분석
개선 권장 사항: 서비스 개선 권장 사항 자동 생성

시퀀스 다이어그램

차량 상태 시스템 흐름

차량 상태

API 엔드포인트

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

전체 차량 상태 조회

bash

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

차량 위치 조회

bash

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

연료 상태 조회

bash

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

주행 거리 조회

bash

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

차량 상태 변경 이력 조회

bash

curl -X GET "https://api.ecarus.run/api/v1/information/vehicles/KMHSH81C7LU123456/status/history?limit=10" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d"

차량 상태 업데이트 요청

bash

curl -X POST "https://api.ecarus.run/api/v1/information/vehicles/KMHSH81C7LU123456/status/refresh" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d"

차량 상태 알림 조회

bash

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

데이터 모델

차량 상태 정보 응답

json

{
  "vin": "KMHSH81C7LU123456",
  "userId": "user123",
  "timestamp": "2026-01-13T14:30:00Z",
  "status": {
    "ignition": "OFF",
    "engine": "STOPPED",
    "transmission": "PARK",
    "doors": {
      "driver": "CLOSED",
      "passenger": "CLOSED",
      "rearLeft": "CLOSED",
      "rearRight": "CLOSED",
      "trunk": "CLOSED"
    },
    "windows": {
      "driver": "CLOSED",
      "passenger": "CLOSED",
      "rearLeft": "CLOSED",
      "rearRight": "CLOSED"
    },
    "lights": {
      "headlights": "OFF",
      "parkingLights": "OFF",
      "brakeLights": "OFF",
      "turnSignals": {
        "left": "OFF",
        "right": "OFF"
      },
      "hazardLights": "OFF"
    },
    "security": {
      "immobilizer": "ACTIVE",
      "alarm": "DISARMED",
      "locked": true
    },
    "climate": {
      "airConditioning": "OFF",
      "heating": "OFF",
      "fanSpeed": 0,
      "temperature": 22.5,
      "unit": "CELSIUS"
    }
  },
  "location": {
    "latitude": 37.4021,
    "longitude": 127.1087,
    "altitude": 15.2,
    "accuracy": 5.0,
    "timestamp": "2026-01-13T14:30:00Z"
  },
  "fuel": {
    "level": 65.5,
    "range": 320,
    "unit": "PERCENTAGE",
    "type": "GASOLINE",
    "estimatedRefill": "2026-01-20T00:00:00Z"
  },
  "battery": {
    "level": 85.2,
    "voltage": 12.6,
    "health": "GOOD",
    "charging": false,
    "estimatedLife": 24,
    "unit": "PERCENTAGE"
  },
  "odometer": {
    "total": 48200,
    "trip": 125,
    "unit": "KILOMETERS",
    "lastReset": "2020-01-01T00:00:00Z"
  },
  "sensors": {
    "tirePressure": {
      "frontLeft": 32.5,
      "frontRight": 32.8,
      "rearLeft": 31.9,
      "rearRight": 32.2,
      "unit": "PSI",
      "status": "NORMAL"
    },
    "engineTemperature": 95.2,
    "coolantTemperature": 88.5,
    "oilPressure": 45.8,
    "unit": "CELSIUS"
  },
  "alerts": [
    {
      "alertId": "alert-001",
      "type": "LOW_FUEL",
      "severity": "MEDIUM",
      "message": "연료 레벨이 20% 미만입니다.",
      "timestamp": "2026-01-13T14:30:00Z",
      "acknowledged": false
    }
  ]
}

차량 위치 정보 응답

json

{
  "vin": "KMHSH81C7LU123456",
  "userId": "user123",
  "timestamp": "2026-01-13T14:30:00Z",
  "location": {
    "latitude": 37.4021,
    "longitude": 127.1087,
    "altitude": 15.2,
    "accuracy": 5.0,
    "heading": 185.5,
    "speed": 0,
    "unit": "KM/H"
  },
  "address": {
    "country": "South Korea",
    "city": "Seoul",
    "district": "Gangnam-gu",
    "street": "Teheran-ro",
    "building": "123",
    "postalCode": "06234"
  },
  "geofence": {
    "withinGeofence": true,
    "geofenceId": "home-001",
    "geofenceName": "Home",
    "distanceFromCenter": 150,
    "unit": "METERS"
  },
  "parking": {
    "isParked": true,
    "parkingDuration": 28500,
    "parkingType": "STREET",
    "parkingLocation": {
      "floor": "B2",
      "zone": "A-15",
      "coordinates": {
        "latitude": 37.4021,
        "longitude": 127.1087
      }
    }
  },
  "lastUpdate": "2026-01-13T14:30:00Z"
}

연료/배터리 상태 정보 응답

json

{
  "vin": "KMHSH81C7LU123456",
  "userId": "user123",
  "timestamp": "2026-01-13T14:30:00Z",
  "fuel": {
    "level": 65.5,
    "range": 320,
    "unit": "PERCENTAGE",
    "type": "GASOLINE",
    "capacity": 50,
    "currentVolume": 32.75,
    "volumeUnit": "LITERS",
    "consumption": {
      "average": 8.5,
      "current": 7.2,
      "unit": "L/100KM"
    },
    "estimatedRefill": {
      "date": "2026-01-20T00:00:00Z",
      "mileage": 50900,
      "remainingRange": 320
    },
    "lastRefill": {
      "date": "2026-01-10T00:00:00Z",
      "mileage": 47500,
      "volume": 45,
      "cost": 65000
    }
  },
  "battery": {
    "level": 85.2,
    "voltage": 12.6,
    "health": "GOOD",
    "charging": false,
    "estimatedLife": 24,
    "unit": "PERCENTAGE",
    "temperature": 25.5,
    "temperatureUnit": "CELSIUS",
    "capacity": 60,
    "currentCapacity": 51.12,
    "capacityUnit": "AH",
    "chargeCycles": 145,
    "lastCharge": {
      "date": "2026-01-13T08:00:00Z",
      "duration": 7200,
      "durationUnit": "SECONDS",
      "chargeLevel": 90.5
    },
    "estimatedReplacement": {
      "date": "2028-01-13T00:00:00Z",
      "mileage": 95000
    }
  },
  "alerts": [
    {
      "alertId": "alert-001",
      "type": "LOW_FUEL",
      "severity": "MEDIUM",
      "message": "연료 레벨이 20% 미만입니다.",
      "threshold": 20,
      "currentValue": 65.5,
      "timestamp": "2026-01-13T14:30:00Z",
      "acknowledged": false
    },
    {
      "alertId": "alert-002",
      "type": "BATTERY_HEALTH",
      "severity": "LOW",
      "message": "배터리 상태가 양호하지만 노화가 진행 중입니다.",
      "healthScore": 75,
      "timestamp": "2026-01-13T14:30:00Z",
      "acknowledged": true
    }
  ]
}

주행 거리 정보 응답

json

{
  "vin": "KMHSH81C7LU123456",
  "userId": "user123",
  "timestamp": "2026-01-13T14:30:00Z",
  "odometer": {
    "total": 48200,
    "trip": 125,
    "unit": "KILOMETERS",
    "lastReset": {
      "date": "2020-01-01T00:00:00Z",
      "mileage": 0
    },
    "daily": {
      "today": 125,
      "yesterday": 85,
      "average": 95
    },
    "weekly": {
      "thisWeek": 425,
      "lastWeek": 380,
      "average": 402
    },
    "monthly": {
      "thisMonth": 1850,
      "lastMonth": 1620,
      "average": 1735
    },
    "yearly": {
      "thisYear": 48200,
      "lastYear": 42500,
      "average": 45350
    }
  },
  "trip": {
    "currentTrip": {
      "id": "trip-001",
      "startTime": "2026-01-13T12:00:00Z",
      "startMileage": 48075,
      "duration": 9000,
      "durationUnit": "SECONDS",
      "distance": 125,
      "averageSpeed": 50,
      "maxSpeed": 85,
      "speedUnit": "KM/H",
      "fuelConsumed": 9.0,
      "fuelUnit": "LITERS",
      "efficiency": 7.2,
      "efficiencyUnit": "L/100KM"
    },
    "lastTrips": [
      {
        "id": "trip-000",
        "date": "2026-01-12T18:30:00Z",
        "distance": 85,
        "duration": 5400,
        "fuelConsumed": 6.8,
        "efficiency": 8.0
      }
    ]
  },
  "maintenance": {
    "nextService": {
      "type": "OIL_CHANGE",
      "dueMileage": 50000,
      "dueDate": "2026-02-10T00:00:00Z",
      "remainingMileage": 1800,
      "remainingDays": 25,
      "urgency": "MEDIUM"
    },
    "lastService": {
      "type": "OIL_CHANGE",
      "mileage": 45000,
      "date": "2025-06-15T00:00:00Z",
      "provider": "공식 서비스 센터",
      "cost": 85000
    }
  },
  "alerts": [
    {
      "alertId": "alert-001",
      "type": "MILEAGE_MILESTONE",
      "severity": "INFO",
      "message": "차량이 48,000km 주행 거리에 도달했습니다.",
      "mileage": 48200,
      "timestamp": "2026-01-13T14:30:00Z",
      "acknowledged": false
    }
  ]
}

보안 및 프라이버시

인증 및 권한 부여

사용자 인증 토큰 필요 (JWT/OAuth2)
차량 접근 권한 확인
상태 조회 권한 확인

데이터 보안

모든 API 통신은 HTTPS/TLS 암호화
차량 상태 데이터 전송 시 보안 대책 적용
민감한 위치 정보에 대한 별도 동의 절차

프라이버시 보호

차량 상태 정보 수집에 대한 명시적 동의
위치 정보 수집에 대한 별도 동의 필요
데이터 보유 정책 준수
사용자 요청 시 데이터 삭제 권한 보장

접근 제어

VIN 기반 차량 접근 권한 확인
사용자별 상태 정보 접근 권한 관리
이상 접근 패턴 감지

예외 처리

네트워크 관련

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

차량 상태 관련

차량 OFF: 마지막 저장된 상태 표시
장기간 데이터 미수신: 데이터 업데이트 필요 알림
센서 오류: 센서 오류 알림, 기본값 표시

온디맨드 조회 관련

차량 Wake-up 실패: Wake-up 실패 알림
응답 타임아웃: 타임아웃 처리
배터리 소모 우려: 배터리 소모 주의 알림

권한 관련

인증 실패: 재인증 요청
권한 부족: 권한 부족에 대한 명확한 설명 제공
위치 정보 권한: 위치 정보 접근 권한 부족 알림

테스트 설정

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

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

배포 고려사항

앱 스토어 등록

차량 상태 조회 권한 요청
위치 정보 수집 권한 요청 (선택 사항)
차량 상태 모니터링 기능에 대한 명확한 설명

법규 준수

개인정보 보호법 준수
차량 상태 정보 수집에 대한 명시적 동의 필요
위치 정보에 대한 별도 동의 필요
데이터 보유 정책 준수

차량 호환성

다양한 차종 지원
내연기관/전기차/하이브리드 지원
OEM별 상태 정보 형식 차이 반영 고려
센서 유형별 데이터 처리 차이 고려

차량 상태 확인 API 개발자 가이드 ​

서비스 개요 ​

서비스 특징 ​

법적 요구사항 ​

주요 시나리오 ​

시나리오 1: 차량 상태 업데이트 요청 및 처리 ​

시나리오 2: 직접 차량 상태 조회 ​

시나리오 3: 부품별 상세 상태 조회 ​

시나리오 4: 상태 이력 조회 및 분석 ​

시나리오 5: 상태 알림 설정 및 관리 ​

시나리오 6: 실시간 상태 이벤트 수신 ​

시나리오 7: 상태 분석 및 통계 ​

시나리오 8: 비상 상황 대응 ​

주요 기능 ​

📱 앱 구현 기능 ​

1. 차량 상태 조회 및 모니터링 ​

2. 상태 이력 및 분석 ​

3. 상태 분석 조회 ​

🏢 콜센터 구현 기능 ​

1. 차량 상태 데이터 수집 시스템 ​

2. 상태 이력 관리 시스템 ​

3. 알림 및 경고 시스템 ​

4. 상태 분석 시스템 ​

5. API 서비스 관리 ​

6. 보안 및 프라이버시 ​

7. 시스템 운영 및 모니터링 ​

8. 데이터 분석 및 통계 ​

시퀀스 다이어그램 ​

차량 상태 시스템 흐름 ​

API 엔드포인트 ​

전체 차량 상태 조회 ​

차량 위치 조회 ​

연료 상태 조회 ​

주행 거리 조회 ​

차량 상태 변경 이력 조회 ​

차량 상태 업데이트 요청 ​

차량 상태 알림 조회 ​

데이터 모델 ​

차량 상태 정보 응답 ​

차량 위치 정보 응답 ​

연료/배터리 상태 정보 응답 ​

주행 거리 정보 응답 ​

보안 및 프라이버시 ​

인증 및 권한 부여 ​

데이터 보안 ​

프라이버시 보호 ​

접근 제어 ​

예외 처리 ​

네트워크 관련 ​

차량 상태 관련 ​

온디맨드 조회 관련 ​

권한 관련 ​

테스트 설정 ​

배포 고려사항 ​

앱 스토어 등록 ​

법규 준수 ​

차량 호환성 ​

차량 상태 확인 API 개발자 가이드

서비스 개요

서비스 특징

법적 요구사항

주요 시나리오

시나리오 1: 차량 상태 업데이트 요청 및 처리

시나리오 2: 직접 차량 상태 조회

시나리오 3: 부품별 상세 상태 조회

시나리오 4: 상태 이력 조회 및 분석

시나리오 5: 상태 알림 설정 및 관리

시나리오 6: 실시간 상태 이벤트 수신

시나리오 7: 상태 분석 및 통계

시나리오 8: 비상 상황 대응

주요 기능

📱 앱 구현 기능

1. 차량 상태 조회 및 모니터링

2. 상태 이력 및 분석

3. 상태 분석 조회

🏢 콜센터 구현 기능

1. 차량 상태 데이터 수집 시스템

2. 상태 이력 관리 시스템

3. 알림 및 경고 시스템

4. 상태 분석 시스템

5. API 서비스 관리

6. 보안 및 프라이버시

7. 시스템 운영 및 모니터링

8. 데이터 분석 및 통계

시퀀스 다이어그램

차량 상태 시스템 흐름

API 엔드포인트

전체 차량 상태 조회

차량 위치 조회

연료 상태 조회

주행 거리 조회

차량 상태 변경 이력 조회

차량 상태 업데이트 요청

차량 상태 알림 조회

데이터 모델

차량 상태 정보 응답

차량 위치 정보 응답

연료/배터리 상태 정보 응답

주행 거리 정보 응답

보안 및 프라이버시

인증 및 권한 부여

데이터 보안

프라이버시 보호

접근 제어

예외 처리

네트워크 관련

차량 상태 관련

온디맨드 조회 관련

권한 관련

테스트 설정

배포 고려사항

앱 스토어 등록

법규 준수

차량 호환성