배터리 저전압 알림 API 개발자 가이드

서비스 개요

배터리 상태 알림 서비스는 차량 배터리 상태가 임계치 이하로 떨어졌을 때 이를 감지하여 차량 → 텔레매틱스 서버 → 사용자 애플리케이션으로 알림을 전달하는 이벤트 기반 서비스입니다.

서비스 특징

배터리 저전압 자동 감지 및 알림
엔진 시동 불량 방지
전기차 주행 불가 방지
상태 기반 경고 서비스
사용자 불편 및 비상 상황 감소

법적 요구사항

개인정보 보호법 준수
데이터 수집 동의 필수
알림 정책 준수

주요 시나리오

시나리오 1: 배터리 저전압 감지 및 경고 처리

엔티티별 API 흐름:

🚗 차량:

배터리 모니터링: 지속적인 배터리 전압 모니터링 (11.7V 감지)
저전압 감지: 11.8V 이하의 저전압 상태 자동 감지
이벤트 전송: 배터리 저전압 이벤트 전송
지속적 상태 모니터링: 지속적인 배터리 상태 모니터링 및 보고
임계치 검증: 정상 상태(>12.0V)와 저전압 상태(<11.8V) 구분

🏢 콜센터:

경고 티켓 생성: 배터리 저전압 경고 티켓 자동 생성
위험 수준 평가: 배터리 상태에 따른 위험 수준 평가
비상 호출 준비: 5분 이내 응답 없을 시 비상 호출 준비
후속 조치 관리: 필요한 후속 조치 관리 및 추적
상태 업데이트: 배터리 경고 상태 업데이트

📱 사용자 앱:

푸시 알림 수신: 즉각적인 배터리 저전압 경고 푸시 알림 수신
상태 조회: 현재 배터리 상태 즉시 조회
비상 호출 수신: 콜센터로부터 비상 호출 수신
실시간 이벤트 수신: SSE를 통한 배터리 상태 업데이트 실시간 수신
위험 상태 확인: 배터리 위험 상태 확인 및 대응

시나리오 2: 배터리 상태 관리 및 정보 조회

엔티티별 API 흐름:

📱 사용자 앱:

배터리 상태 조회: 실시간 배터리 전압 및 SOC 조회
상세 정보 확인: 상세 배터리 정보 및 건강 상태 확인
기록 조회: 과거 배터리 상태 기록 조회
분석 정보 조회: 배터리 성능 및 상태 분석 조회
예측 정보 조회: 배터리 수명 및 교체 시기 예측

🚗 차량:

상태 데이터 제공: 배터리 전압, SOC, 온도 포함 상세 데이터 제공
기록 데이터 저장: 배터리 상태 변화 기록 데이터 저장
실시간 상태 전송: 현재 배터리 상태 실시간 전송
진단 데이터 생성: 배터리 진단 관련 데이터 생성
상태 업데이트: 배터리 상태 변경 시 즉각 업데이트

🏢 콜센터:

상태 데이터 수신: 차량으로부터 배터리 상태 데이터 수신
분석 처리: 배터리 상태 데이터 분석 및 위험 평가
기록 관리: 배터리 상태 기록 데이터 관리
예측 모델링: 배터리 수명 및 교체 시기 예측
상담 지원: 배터리 상태 기반 상담 지원 제공

시나리오 3: 실시간 배터리 이벤트 모니터링

엔티티별 API 흐름:

🏢 콜센터:

실시간 이벤트 스트림: SSE를 통한 배터리 상태 업데이트 실시간 전송
이벤트 처리: 배터리 상태 변경 이벤트 즉각 처리
위험 감지: 실시간 배터리 위험 상태 감지
알림 생성: 상태 변경 기반 알림 생성
모니터링 대시보드: 실시간 배터리 상태 모니터링 대시보드 운영

📱 사용자 앱:

SSE 이벤트 수신: 실시간 배터리 상태 업데이트 수신
상태 변경 알림: 배터리 상태 변경 즉각 알림
실시간 표시: 현재 배터리 전압 및 SOC 실시간 표시
위험 경고: 위험 상태 변경 시 즉각 경고
상태 기록: 실시간 상태 변경 기록

🚗 차량:

지속적 상태 모니터링: 지속적인 배터리 상태 모니터링
이벤트 생성: 상태 변경 시 자동 이벤트 생성
실시간 전송: 상태 변경 데이터 실시간 전송
임계치 모니터링: 위험 임계치 지속 모니터링
상태 보고: 주기적 상태 보고

시나리오 4: 정비 예약 및 후속 조치

엔티티별 API 흐름:

📱 사용자 앱:

정비 예약: 배터리 교체 예약
예약 확인: 예약 상태 및 시간 확인
서비스 연계: 정비소 서비스와 자동 연계
후속 조치 확인: 필요한 후속 조치 확인
예약 관리: 예약 변경 및 취소 관리

🏢 콜센터:

서비스 호콜: 사용자에게 서비스 호콜 연결
예약 처리: 배터리 교체 예약 처리
후속 조치 관리: 필요한 후속 조치 관리
상태 업데이트: 배터리 경고 상태 업데이트
서비스 제공자 연계: 정비소 등 서비스 제공자 연계

🚗 차량:

서비스 준비: 정비 서비스를 위한 차량 상태 준비
상태 정보 제공: 서비스에 필요한 상세 상태 정보 제공
진단 데이터 전송: 정비소로 진단 데이터 전송
상태 모니터링: 서비스 전후 상태 모니터링
완료 보고: 서비스 완료 상태 보고

주요 기능

📱 앱 구현 기능

1. 실시간 배터리 상태 모니터링

상태 조회: 실시간 배터리 전압 및 잔량 표시
상세 정보 확인: 배터리 상태 경고 수준 표시
실시간 이벤트 수신: SSE를 통한 실시간 상태 업데이트 수신
온도 모니터링: 실시간 배터리 온도 모니터링

2. 알림 수신 및 관리

푸시 알림 수신: 배터리 저전압 경고 푸시 알림 즉각 수신
비상 호출 수신: 콜센터로부터 비상 호출 수신
알림 유형 관리: 저전압, 잔량 부족, 상태 복구 알림 관리
알림 설정: 알림 수준(경고/위험) 설정 및 관리
알림 무시 기능: 일시적 알림 무시 기능

3. 배터리 정보 조회 및 분석

기록 조회: 과거 배터리 상태 이력 조회
분석 조회: 배터리 성능 및 상태 분석 조회
예측 조회: 배터리 수명 및 교체 시기 예측
트렌드 분석: 배터리 상태 변화 트렌드 분석
성능 평가: 배터리 효율 및 수명 평가

4. 정비 서비스 연계

정비 예약: 배터리 교체 예약
정비소 연계: 배터리 이상 시 정비소 예약 연계
서비스 상태 추적: 예약된 서비스 진행 상황 실시간 추적
후속 조치 안내: 필요한 후속 조치 안내 및 예약
서비스 이력 관리: 과거 정비 서비스 이력 관리

5. 설정 및 개인화

알림 수준 설정: 경고/위험 수준별 알림 설정
알림 주기 설정: 알림 발생 주기 및 시간 설정
차량별 설정: 다수 차량 이용 시 차별화된 배터리 상태 알림 설정
위치 기반 설정: 위치 기반 알림 설정
개인화 프로필: 사용자별 알림 프로필 설정

🏢 콜센터 구현 기능

1. 배터리 상태 모니터링 시스템

실시간 상태 수신: 차량 배터리 상태 실시간 수신
상태 분석: 자동 배터리 상태 분석
위험 감지: 저전압 및 잔량 부족 위험 자동 감지
상태 기록: 모든 배터리 상태 변화 기록
성능 모니터링: 실시간 배터리 성능 모니터링

2. 알림 생성 및 전송 시스템

이벤트 기반 알림: 배터리 상태 이벤트 기반 알림 자동 생성
푸시 알림: 사용자 앱으로 실시간 푸시 알림 전송
비상 호출: 5분 이내 무응답 시 비상 호출 자동 연결
알림 우선순위 관리: 위험 수준별 알림 우선순위 관리
알림 채널 관리: 다중 채널 알림 (Push, Call)

3. 배터리 데이터 분석 시스템

기록 관리: 배터리 상태 기록 관리
분석 처리: 배터리 성능 및 상태 분석 처리
예측 모델: 배터리 수명 및 교체 시기 예측
트렌드 분석: 배터리 상태 변화 트렌드 분석
성과 리포팅: 배터리 상태 알림 서비스 성과 분석

4. 서비스 연계 시스템

경고 티켓 생성: 배터리 저전압 경고 티켓 자동 생성
정비 예약: 배터리 교체 예약 처리
정비소 연계: 배터리 이상 시 정비소 자동 연계
서비스 호콜: 사용자에게 서비스 호콜 연결
후속 조치 관리: 필요한 후속 조치 관리 및 추적

5. 상태 복구 관리 시스템

복구 감지: 배터리 상태 복구 자동 감지
알림 해제: 경고 알림 자동 해제
복구 알림: 사용자에게 상태 복구 알림 전송
복구 분석: 배터리 복구 원인 분석
정상 상태 확인: 정상 상태 복귀 확인

6. 예측 및 예방 시스템

방전 예측: 배터리 방전 시점 예측
수명 예측: 배터리 수명 및 교체 시기 예측
위험 평가: 배터리 고장 위험 자동 평가
예방 알림: 예방 차원의 알림 생성
정비 추천: 최적 정비 시점 추천

7. 데이터 관리 및 보안

데이터 수집: 배터리 상태 데이터 자동 수집
데이터 저장: 배터리 기록 데이터의 안전한 저장
데이터 분석: 배터리 데이터의 종합 분석
프라이버시 보호: 사용자 배터리 정보 프라이버시 보호
감사 로그: 배터리 데이터 접근 및 처리 감사 로그

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

시스템 상태 모니터링: 배터리 상태 알림 시스템 24시간 모니터링
API 성능 모니터링: API 응답 시간 및 가용성 모니터링
데이터 무결성 관리: 배터리 데이터 무결성 검증
예외 처리: 네트워크, 센서, 알림 예외 처리
시스템 최적화: 배터리 상태 알림 처리 로직 최적화

시퀀스 다이어그램

배터리 상태 알림 시스템 흐름

배터리 상태 알림

API 엔드포인트

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

배터리 상태 조회

bash

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

상세 배터리 상태 조회

bash

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

배터리 기록 조회

bash

curl -X GET "https://api.ecarus.run/api/v1/information/vehicles/KMHSH81C7LU123456/battery/history?period=30d" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d"

배터리 분석 조회

bash

curl -X GET "https://api.ecarus.run/api/v1/information/vehicles/KMHSH81C7LU123456/battery/analytics?period=30d" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d"

배터리 예측 조회

bash

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

데이터 모델

배터리 상태 정보

json

{
  "vin": "KNXXXXXXX",
  "batteryStatus": {
    "batteryType": "12V",
    "voltage": 12.1,
    "soc": 75,
    "health": "GOOD",
    "temperature": 25.5,
    "isCharging": false
  },
  "vehicleStatus": {
    "ignition": "OFF",
    "parkingDuration": 72,
    "lastDriveTime": "2026-01-10T18:30:00Z"
  },
  "timestamp": "2026-01-13T14:30:00Z"
}

알림 설정 정보

json

{
  "userId": "user123",
  "vin": "KNXXXXXXX",
  "notificationSettings": {
    "alertLevel": "WARNING",
    "enablePush": true,
    "ignoreDuration": 3600,
    "reminderInterval": 1800,
    "soundEnabled": true
  },
  "lastUpdated": "2026-01-13T14:30:00Z"
}

배터리 기록 응답

json

{
  "history": [
    {
      "timestamp": "2026-01-13T14:30:00Z",
      "voltage": 12.1,
      "soc": 75,
      "health": "GOOD",
      "temperature": 25.5,
      "chargingStatus": "NOT_CHARGING",
      "eventType": "STATUS_UPDATE"
    },
    {
      "timestamp": "2026-01-13T10:15:00Z",
      "voltage": 11.9,
      "soc": 68,
      "health": "FAIR",
      "temperature": 22.3,
      "chargingStatus": "CHARGING",
      "eventType": "LOW_VOLTAGE_WARNING"
    }
  ],
  "total": 45,
  "summary": {
    "totalRecords": 2,
    "avgVoltage": 12.0,
    "avgSoc": 71.5,
    "minVoltage": 11.9,
    "maxVoltage": 12.1,
    "warningCount": 1,
    "criticalCount": 0
  }
}

배터리 분석 응답

json

{
  "period": "30d",
  "trends": {
    "voltageTrend": "STABLE",
    "healthTrend": "IMPROVING",
    "socTrend": "STABLE"
  },
  "statistics": {
    "avgVoltage": 12.05,
    "minVoltage": 11.8,
    "maxVoltage": 12.6,
    "avgTemperature": 24.5,
    "chargeCycles": 15,
    "dischargeCycles": 320,
    "avgDailyDrain": 2.5
  },
  "performance": {
    "efficiency": 92.5,
    "reliability": 98.2,
    "healthScore": 85.5,
    "capacityRetention": 94.2
  },
  "recommendations": [
    "배터리 성능이 양호합니다.",
    "충전 패턴 최적화로 수명을 연장할 수 있습니다.",
    "정기적인 배터리 점검을 권장합니다."
  ],
  "generatedAt": "2026-01-13T14:30:00Z"
}

배터리 예측 응답

json

{
  "current": {
    "voltage": 12.1,
    "soc": 75,
    "temperature": 25.5,
    "timestamp": "2026-01-13T14:30:00Z"
  },
  "prediction": {
    "timeToEmpty": {
      "estimatedHours": 72.5,
      "estimatedTime": "2026-01-16T14:30:00Z",
      "confidence": 0.85
    },
    "healthScore": {
      "current": 85,
      "predicted": 82,
      "trend": "STABLE"
    },
    "nextService": {
      "date": "2026-07-15",
      "remainingDays": 183,
      "urgency": "LOW"
    },
    "failureRisk": {
      "level": "LOW",
      "probability": 0.05,
      "factors": ["age", "usage_pattern"]
    }
  },
  "scenarios": [
    {
      "type": "NORMAL_USAGE",
      "timeToEmptyHours": 72.5,
      "confidence": 0.85
    },
    {
      "type": "HEAVY_USAGE",
      "timeToEmptyHours": 48.0,
      "confidence": 0.75
    },
    {
      "type": "MINIMAL_USAGE",
      "timeToEmptyHours": 96.0,
      "confidence": 0.90
    }
  ],
  "model": {
    "algorithm": "LINEAR_REGRESSION",
    "accuracy": 0.85,
    "lastUpdated": "2026-01-13T09:00:00Z",
    "trainingDataPoints": 450
  }
}

배터리 상세 정보

json

{
  "vin": "KNXXXXXXX",
  "battery": {
    "batteryType": "12V",
    "voltage": 12.1,
    "soc": 75,
    "health": "GOOD",
    "temperature": 25.5,
    "isCharging": false,
    "chargeRate": 0.0,
    "dischargeRate": 0.2,
    "estimatedLife": 365,
    "lastCharge": "2026-01-12T18:30:00Z",
    "age": "2.5 years",
    "cycleCount": 150
  },
  "diagnostics": {
    "cellBalance": true,
    "internalResistance": 0.015,
    "capacity": 60.0,
    "maxCapacity": 65.0,
    "currentCapacity": 48.75,
    "capacityRetention": 75.0
  },
  "maintenance": {
    "nextServiceDate": "2026-07-15",
    "recommendedReplacement": "2026-12-15",
    "warrantyExpiry": "2027-01-15",
    "lastServiceDate": "2025-07-15"
  },
  "timestamp": "2026-01-13T14:30:00Z"
}

보안 및 프라이버시

인증 및 권한 부여

사용자 인증 토큰 필요 (JWT/OAuth2)
차량 접근 권한 확인
알림 수신 권한 확인

데이터 보안

모든 API 통신은 HTTPS/TLS 암호화
배터리 상태 정보 전송 시 보안 조치
민감 정보는 서버에만 저장

프라이버시 보호

배터리 상태 정보 수집에 대한 명시적 동의
데이터 수집 목적 명시
데이터 보유 기간 정책 준수
사용자 요청 시 데이터 삭제 권한 보장

접근 제어

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

예외 처리

네트워크 관련

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

센서 관련

센서 오류: 센서 오류 알림, 기본값 표시
데이터 부정확: 데이터 신뢰도 낮음 알림
배터리 고장: 배터리 고장 알림, 정비 안내

알림 관련

중복 알림: 디바운스 처리를 통한 중복 알림 방지
알림 실패: 알림 전송 실패 시 재시도
사용자 무시: 사용자 무시 설정 반영

테스트 설정

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

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

배포 고려사항

앱 스토어 등록

배터리 상태 모니터링 권한 요청
푸시 알림 권한 요청
위치 정보 수집에 대한 명확한 설명

법규 준수

개인정보 보호법 준수
데이터 수집 동의 필수
알림 정책 준수

차량 호환성

다양한 차종 지원
내연기관/전기차/하이브리드 지원
배터리 유형별 기능 차이 반영

배터리 저전압 알림 API 개발자 가이드 ​

서비스 개요 ​

서비스 특징 ​

법적 요구사항 ​

주요 시나리오 ​

시나리오 1: 배터리 저전압 감지 및 경고 처리 ​

시나리오 2: 배터리 상태 관리 및 정보 조회 ​

시나리오 3: 실시간 배터리 이벤트 모니터링 ​

시나리오 4: 정비 예약 및 후속 조치 ​

주요 기능 ​

📱 앱 구현 기능 ​

1. 실시간 배터리 상태 모니터링 ​

2. 알림 수신 및 관리 ​

3. 배터리 정보 조회 및 분석 ​

4. 정비 서비스 연계 ​

5. 설정 및 개인화 ​

🏢 콜센터 구현 기능 ​

1. 배터리 상태 모니터링 시스템 ​

2. 알림 생성 및 전송 시스템 ​

3. 배터리 데이터 분석 시스템 ​

4. 서비스 연계 시스템 ​

5. 상태 복구 관리 시스템 ​

6. 예측 및 예방 시스템 ​

7. 데이터 관리 및 보안 ​

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

시퀀스 다이어그램 ​

배터리 상태 알림 시스템 흐름 ​

API 엔드포인트 ​

배터리 상태 조회 ​

상세 배터리 상태 조회 ​

배터리 기록 조회 ​

배터리 분석 조회 ​

배터리 예측 조회 ​

데이터 모델 ​

배터리 상태 정보 ​

알림 설정 정보 ​

배터리 기록 응답 ​

배터리 분석 응답 ​

배터리 예측 응답 ​

배터리 상세 정보 ​

보안 및 프라이버시 ​

인증 및 권한 부여 ​

데이터 보안 ​

프라이버시 보호 ​

접근 제어 ​

예외 처리 ​

네트워크 관련 ​

센서 관련 ​

알림 관련 ​

테스트 설정 ​

배포 고려사항 ​

앱 스토어 등록 ​

법규 준수 ​

차량 호환성 ​

배터리 저전압 알림 API 개발자 가이드

서비스 개요

서비스 특징

법적 요구사항

주요 시나리오

시나리오 1: 배터리 저전압 감지 및 경고 처리

시나리오 2: 배터리 상태 관리 및 정보 조회

시나리오 3: 실시간 배터리 이벤트 모니터링

시나리오 4: 정비 예약 및 후속 조치

주요 기능

📱 앱 구현 기능

1. 실시간 배터리 상태 모니터링

2. 알림 수신 및 관리

3. 배터리 정보 조회 및 분석

4. 정비 서비스 연계

5. 설정 및 개인화

🏢 콜센터 구현 기능

1. 배터리 상태 모니터링 시스템

2. 알림 생성 및 전송 시스템

3. 배터리 데이터 분석 시스템

4. 서비스 연계 시스템

5. 상태 복구 관리 시스템

6. 예측 및 예방 시스템

7. 데이터 관리 및 보안

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

시퀀스 다이어그램

배터리 상태 알림 시스템 흐름

API 엔드포인트

배터리 상태 조회

상세 배터리 상태 조회

배터리 기록 조회

배터리 분석 조회

배터리 예측 조회

데이터 모델

배터리 상태 정보

알림 설정 정보

배터리 기록 응답

배터리 분석 응답

배터리 예측 응답

배터리 상세 정보

보안 및 프라이버시

인증 및 권한 부여

데이터 보안

프라이버시 보호

접근 제어

예외 처리

네트워크 관련

센서 관련

알림 관련

테스트 설정

배포 고려사항

앱 스토어 등록

법규 준수

차량 호환성