소모품 교체 알림 API 개발자 가이드
서비스 개요
소모품 교체 알림 서비스는 차량 소모품을 모니터링하고 모바일 앱이나 웹 플랫폼을 통해 교체 알림 및 정비 권장 사항을 제공하는 텔레매틱스 서비스입니다.
서비스 특징
- 소모품 라이프사이클 모니터링
- 교체 주기 알림
- 정비 일정 예약 지원
- 교체 비용 추정
- 정비소 추천
법적 요구사항
- 개인정보 보호법 준수
- 차량 데이터 수집에 대한 명시적 동의 필요
- 데이터 보유 정책 준수
- 정비 기록 보호
주요 시나리오
시나리오 1: 소모품 상태 업데이트 요청 및 처리
엔티티별 API 흐름:
📱 앱 (사용자):
- 상태 조회: 현재 소모품 상태 조회
- 상태 확인: 상태 업데이트 진행 상황 확인 (진행 중/완료)
- 알림 수신: 교체 주기 알림 수신
🚗 차량 (TCU):
- 센서 데이터 수집: 모든 센서로부터 소모품 상태 데이터 수집
- 데이터 전송: 서버로 소모품 상태 데이터 전송
- 교체 감지: 교체가 필요한 품목 감지
🏢 콜센터:
- 중복 요청 방지: 중복 요청 방지 로직 적용
- 명령 전송: 차량으로 소모품 상태 업데이트 명령 전송
- 데이터 처리: 수신된 소모품 데이터 처리 및 검증
- 교체 분석: 교체 요구 사항 분석
- 알림 생성: 교체 알림 생성
- 저장: 타임스탬프와 함께 소모품 데이터 저장
시나리오 2: 실시간 소모품 상태 조회
엔티티별 API 흐름:
📱 앱 (사용자):
- 상태 조회: 현재 소모품 상태 조회
- 상태 표시: 모든 소모품의 상태 표시
- 교체 표시: 교체 주기 인디케이터 표시
🏢 콜센터:
- 상태 제공: 최신 소모품 상태 제공
- 상태 관리: 소모품 상태 자동 관리
- 데이터 캐싱: 소모품 데이터의 효율적 캐싱
- 상태 분석: 소모품 사용 패턴 분석
시나리오 3: 소모품 이력 조회
엔티티별 API 흐름:
📱 앱 (사용자):
- 라이프사이클 조회: 소모품 라이프사이클 상태 조회
- 이력 표시: 교체 이력 타임라인 표시
- 패턴 분석: 소모품 사용 패턴 분석 표시
🏢 콜센터:
- 이력 관리: 소모품 교체 이력 자동 관리
- 패턴 분석: 소모품 사용 패턴 분석
- 통계 생성: 교체 통계 생성
시나리오 4: 교체 알림 및 경고
엔티티별 API 흐름:
📱 앱 (사용자):
- 알림 설정: 교체 알림 설정
- 알림 수신: 교체 주기 알림 수신
- 알림 관리: 알림 기본 설정 관리
🏢 콜센터:
- 알림 모니터링: 교체 요구 사항에 대한 소모품 모니터링
- 알림 생성: 교체 알림 생성
- 푸시 알림: 사용자 앱으로 푸시 알림 전송
- 에스컬레이션: 심각한 교체 요구 사항 에스컬레이션
시나리오 5: 정비 일정 예약
엔티티별 API 흐름:
📱 앱 (사용자):
- 일정 요청: 정비 일정 예약 요청
- 정비소 선택: 선호하는 정비소 선택
- 예약 확정: 정비 예약 확정
🏢 콜센터:
- 일정 처리: 정비 일정 예약 요청 처리
- 정비소 조율: 정비소와 일정 조율
- 예약 확인: 예약 상세 정보 확인
- 알림 관리: 예약 리마인더 관리
시나리오 6: 비용 추정 및 견적
엔티티별 API 흐름:
📱 앱 (사용자):
- 비용 조회: 교체 비용 추정 조회
- 견적 요청: 상세 견적 요청
- 비교: 정비소별 가격 비교
🏢 콜센터:
- 비용 분석: 교체 비용 분석
- 견적 생성: 상세 견적 생성
- 가격 비교: 가격 비교 정보 제공
- 할인 정보: 할인 정보 제공
시나리오 7: 실시간 교체 이벤트
엔티티별 API 흐름:
📱 앱 (사용자):
- SSE 연결: 실시간 교체 이벤트 스트림 연결
- 실시간 수신: 실시간으로 소모품 상태 변경 수신
🏢 콜센터:
- 이벤트 스트림 제공: 실시간 교체 이벤트 스트림 제공
- 이벤트 전송: 실시간으로 교체 상태 변경 이벤트 전송
시나리오 8: 정비소 추천
엔티티별 API 흐름:
📱 앱 (사용자):
- 추천 조회: 정비소 추천 조회
- 센터 선택: 선호하는 정비소 선택
- 리뷰 표시: 정비소 리뷰 표시
🏢 콜센터:
- 추천 생성: 정비소 추천 생성
- 품질 분석: 정비소 품질 분석
- 가용성 확인: 정비소 예약 가능 여부 확인
- 리뷰 관리: 정비소 리뷰 관리
주요 기능
📱 앱 구현 기능
1. 소모품 상태 모니터링
- 상태 조회: 현재 소모품 상태 조회
- 상태 표시: 모든 소모품의 상태 표시
- 교체 인디케이터: 교체 주기 인디케이터 표시
- 실시간 업데이트: 실시간 소모품 상태 업데이트
- 진척도 표시: 소모품 라이프사이클 진척도 표시
2. 교체 이력
- 라이프사이클 조회: 소모품 라이프사이클 조회
- 타임라인 표시: 교체 이력 타임라인 표시
- 패턴 분석: 소모품 사용 패턴 분석 표시
- 통계: 교체 통계 표시
3. 알림 및 통지
- 알림 설정: 교체 알림 설정
- 알림 수신: 교체 주기 알림 수신
- 알림 관리: 알림 기본 설정 관리
- 알림 이력: 알림 이력 표시
4. 정비 일정 관리
- 일정 요청: 정비 일정 예약 요청
- 정비소 선택: 선호하는 정비소 선택
- 예약 확정: 정비 예약 확정
- 캘린더 연동: 사용자 캘린더와 연동
5. 비용 추정
- 비용 조회: 교체 비용 추정 조회
- 견적 표시: 상세 견적 표시
- 가격 비교: 정비소별 가격 비교
- 예산 계획: 교체 예산 계획 수립
6. 정비소 추천
- 추천 조회: 정비소 추천 조회
- 센터 표시: 추천 정비소 표시
- 리뷰 표시: 정비소 리뷰 표시
- 위치 표시: 정비소 위치 표시
7. 실시간 이벤트 수신
- SSE 연결: 실시간 교체 이벤트 스트림 연결
- 실시간 수신: 실시간으로 소모품 상태 변경 수신
- 이벤트 처리: 수신된 이벤트 처리 및 표시
🏢 콜센터 구현 기능
1. 소모품 데이터 수집 시스템
- 데이터 수신: 실시간 소모품 상태 데이터 수신
- 데이터 저장: 소모품 데이터의 안전한 저장
- 상태 관리: 최신 소모품 상태 자동 관리
- 품질 관리: 소모품 데이터 품질 및 정확성 관리
- 데이터 검증: 소모품 데이터 유효성 검증
2. 교체 이력 관리 시스템
- 이력 수집: 교체 이력 자동 수집
- 라이프사이클 관리: 교체 이력 자동 관리
- 패턴 분석: 소모품 사용 패턴 자동 분석
- 통계 생성: 교체 통계 자동 생성
3. 알림 및 통지 시스템
- 알림 모니터링: 교체 요구 사항에 대한 소모품 모니터링
- 알림 생성: 교체 알림 자동 생성
- 푸시 알림: 사용자 앱으로 푸시 알림 자동 전송
- 알림 에스컬레이션: 심각한 교체 요구 사항 에스컬레이션
- 알림 설정: 알림 설정 관리
4. 정비 일정 예약 시스템
- 일정 처리: 정비 일정 예약 요청 처리
- 정비소 조율: 정비소와 일정 조율
- 예약 관리: 정비 예약 관리
- 알림 관리: 예약 리마인더 관리
- 캘린더 연동: 캘린더 시스템과 연동
5. 비용 추정 시스템
- 비용 분석: 교체 비용 자동 분석
- 견적 생성: 상세 견적 생성
- 가격 비교: 가격 비교 정보 제공
- 할인 관리: 할인 정보 관리
- 예산 계획: 예산 계획 도구 제공
6. 정비소 추천 시스템
- 추천 생성: 정비소 추천 생성
- 품질 분석: 정비소 품질 분석
- 가용성 관리: 정비소 예약 가능 여부 관리
- 리뷰 관리: 정비소 리뷰 관리
- 위치 서비스: 정비소 위치 서비스 제공
7. API 서비스 관리
- API 응답 처리: 교체 알림 관련 API 요청 처리
- 요청 검증: API 요청 유효성 검증
- 성능 모니터링: API 응답 시간 및 가용성 모니터링
- 에러 핸들링: API 에러 및 예외 처리
- 버전 관리: API 버전 및 호환성 관리
8. 보안 및 프라이버시
- 소모품 데이터 동의: 소모품 데이터 수집 동의 관리
- 프라이버시 보호: 사용자 소모품 데이터 프라이버시 보호
- 데이터 보안: 소모품 데이터의 안전한 처리
- 감사 로깅: 소모품 데이터 접근에 대한 감사 로그 유지
- 접근 제어: 사용자별 교체 알림 접근 권한 관리
9. 시스템 운영 및 모니터링
- 시스템 상태 모니터링: 교체 알림 시스템 24시간 모니터링
- 데이터 품질 관리: 소모품 데이터 품질 및 정확성 관리
- 센서 상태 모니터링: 소모품 센서 통신 상태 모니터링
- 예외 처리: 네트워크, 센서, 데이터 처리 예외 대응
- 시스템 최적화: 소모품 데이터 처리 로직 최적화
10. 데이터 분석 및 통계
- 패턴 분석: 소모품 사용 패턴 자동 분석
- 이용 통계: 교체 알림 이용 통계 자동 생성
- 서비스 품질 분석: 교체 알림 서비스 품질 자동 분석
- 개선 권장 사항: 서비스 개선 권장 사항 자동 생성
시퀀스 다이어그램
소모품 교체 알림 시스템 흐름

API 엔드포인트
헤더, 응답 코드 및 에러 형식은 공통 API 사양을 참조하십시오.
현재 소모품 상태 조회
bash
curl -X GET "https://api.ecarus.run/api/v1/information/vehicles/KMHSH81C7LU123456/consumables/status" \
-H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d"소모품 라이프사이클 조회
bash
curl -X GET "https://api.ecarus.run/api/v1/information/vehicles/KMHSH81C7LU123456/consumables/lifecycle" \
-H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d"소모품 교체 리셋
bash
curl -X POST "https://api.ecarus.run/api/v1/information/vehicles/KMHSH81C7LU123456/consumables/reset" \
-H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d" \
-H "Content-Type: application/json" \
-d '{"consumableType": "engineOil", "resetMileage": 45000}'소모품 추천 조회
bash
curl -X GET "https://api.ecarus.run/api/v1/information/vehicles/KMHSH81C7LU123456/consumables/recommendations" \
-H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d"소모품 교체 알림 설정
bash
curl -X PUT "https://api.ecarus.run/api/v1/information/vehicles/KMHSH81C7LU123456/consumables/alerts" \
-H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d" \
-H "Content-Type: application/json" \
-d '{"advanceWarningDays": 30, "criticalWarningDays": 7, "notificationTypes": ["PUSH", "EMAIL"]}'데이터 모델
소모품 상태 정보 응답
json
{
"vin": "KMHSH81C7LU123456",
"userId": "user123",
"timestamp": "2026-01-13T14:30:00Z",
"consumables": {
"engineOil": {
"status": "DUE_SOON",
"currentLevel": 75,
"replacementInterval": 10000,
"lastReplacement": {
"date": "2025-06-15T00:00:00Z",
"mileage": 38200
},
"nextReplacement": {
"estimatedDate": "2026-02-10T00:00:00Z",
"estimatedMileage": 50000,
"remainingMileage": 1800,
"remainingDays": 28
},
"recommendedProduct": "5W-30 합성유",
"estimatedCost": 85000
},
"oilFilter": {
"status": "GOOD",
"replacementInterval": 10000,
"lastReplacement": {
"date": "2025-06-15T00:00:00Z",
"mileage": 38200
},
"nextReplacement": {
"estimatedDate": "2026-02-10T00:00:00Z",
"estimatedMileage": 50000,
"remainingMileage": 1800,
"remainingDays": 28
},
"recommendedProduct": "순정 오일 필터",
"estimatedCost": 15000
},
"airFilter": {
"status": "GOOD",
"replacementInterval": 20000,
"lastReplacement": {
"date": "2025-01-10T00:00:00Z",
"mileage": 30000
},
"nextReplacement": {
"estimatedDate": "2026-07-15T00:00:00Z",
"estimatedMileage": 60000,
"remainingMileage": 11800,
"remainingDays": 183
},
"recommendedProduct": "하이플로우 에어 필터",
"estimatedCost": 25000
},
"brakePads": {
"status": "MONITOR",
"currentThickness": {
"front": 6.5,
"rear": 7.2
},
"minimumThickness": 3.0,
"lastReplacement": {
"date": "2024-03-20T00:00:00Z",
"mileage": 25000
},
"nextReplacement": {
"estimatedDate": "2026-09-01T00:00:00Z",
"estimatedMileage": 65000,
"remainingMileage": 16800,
"remainingDays": 231
},
"recommendedProduct": "세라믹 브레이크 패드",
"estimatedCost": 180000
},
"tires": {
"status": "GOOD",
"currentTread": {
"frontLeft": 7.5,
"frontRight": 7.8,
"rearLeft": 6.9,
"rearRight": 7.2
},
"minimumTread": 2.0,
"lastReplacement": {
"date": "2023-12-01T00:00:00Z",
"mileage": 20000
},
"nextReplacement": {
"estimatedDate": "2027-06-01T00:00:00Z",
"estimatedMileage": 90000,
"remainingMileage": 41800,
"remainingDays": 500
},
"recommendedProduct": "사계절 투어링 타이어",
"estimatedCost": 600000
},
"battery": {
"status": "GOOD",
"health": 85,
"voltage": 12.6,
"replacementInterval": 36,
"lastReplacement": {
"date": "2023-06-15T00:00:00Z",
"mileage": 15000
},
"nextReplacement": {
"estimatedDate": "2026-12-01T00:00:00Z",
"estimatedMileage": 75000,
"remainingMileage": 26800,
"remainingDays": 322
},
"recommendedProduct": "AGM 배터리",
"estimatedCost": 150000
}
},
"summary": {
"totalItems": 6,
"dueSoon": 1,
"monitor": 1,
"good": 4,
"totalEstimatedCost": 1055000,
"nextDueDate": "2026-02-10T00:00:00Z",
"nextDueItem": "engineOil"
},
"alerts": [
{
"alertId": "alert-001",
"type": "REPLACEMENT_DUE",
"severity": "MEDIUM",
"consumable": "engineOil",
"message": "엔진 오일 교체 주기가 28일 남았습니다.",
"dueDate": "2026-02-10T00:00:00Z",
"remainingMileage": 1800,
"estimatedCost": 85000,
"timestamp": "2026-01-13T14:30:00Z",
"acknowledged": false
}
]
}소모품 교체 이력 응답
json
{
"vin": "KMHSH81C7LU123456",
"userId": "user123",
"period": "24m",
"limit": 10,
"offset": 0,
"history": [
{
"replacementId": "replace-001",
"timestamp": "2025-06-15T10:00:00Z",
"mileage": 38200,
"consumable": "engineOil",
"product": "5W-30 합성유",
"cost": 85000,
"serviceCenter": {
"name": "공식 서비스 센터",
"address": "서울시 서비스로 123"
},
"warranty": {
"duration": "6m",
"mileage": 10000
}
},
{
"replacementId": "replace-002",
"timestamp": "2025-01-10T14:30:00Z",
"mileage": 30000,
"consumable": "airFilter",
"product": "하이플로우 에어 필터",
"cost": 25000,
"serviceCenter": {
"name": "퀵 서비스 샵",
"address": "서울시 퀵레인 456"
},
"warranty": {
"duration": "12m",
"mileage": 20000
}
}
],
"total": 15,
"hasMore": true,
"nextOffset": 10,
"statistics": {
"totalCost": 1250000,
"averageCostPerReplacement": 83333,
"mostFrequentReplacement": "engineOil",
"totalReplacements": 15
}
}소모품 교체 알림 설정 응답
json
{
"vin": "KMHSH81C7LU123456",
"userId": "user123",
"timestamp": "2026-01-13T14:30:00Z",
"alerts": {
"timing": {
"advanceWarningDays": 30,
"criticalWarningDays": 7,
"immediateWarningDays": 1
},
"notifications": {
"pushEnabled": true,
"emailEnabled": true,
"smsEnabled": false,
"inAppEnabled": true,
"severityFilter": ["MEDIUM", "HIGH", "CRITICAL"]
},
"consumables": {
"engineOil": {"enabled": true, "advanceDays": 30},
"oilFilter": {"enabled": true, "advanceDays": 30},
"airFilter": {"enabled": true, "advanceDays": 60},
"brakePads": {"enabled": true, "advanceDays": 90},
"tires": {"enabled": true, "advanceDays": 120},
"battery": {"enabled": true, "advanceDays": 90}
},
"schedule": {
"quietHours": {
"start": "22:00",
"end": "07:00",
"criticalAlertsEnabled": true
},
"frequency": {
"dailySummary": false,
"weeklySummary": true,
"monthlySummary": true
}
}
},
"previousSettings": {
"timing": {
"advanceWarningDays": 21,
"criticalWarningDays": 3
}
},
"validation": {
"isValid": true,
"warnings": [
"사전 알림 기간이 길어 다수 품목에 대한 빈번한 알림이 발생할 수 있습니다."
],
"errors": []
}
}보안 및 프라이버시
인증 및 권한 부여
- 사용자 인증 토큰 필요 (JWT/OAuth2)
- 차량 접근 권한 확인
- 교체 알림 조회 권한 확인
데이터 보안
- 모든 API 통신은 HTTPS/TLS 암호화
- 소모품 데이터의 안전한 전송
- 민감한 정비 정보 보호
프라이버시 보호
- 소모품 데이터 수집에 대한 명시적 동의
- 데이터 보유 정책 준수
- 사용자 요청 시 데이터 삭제 권한 보장
접근 제어
- VIN 기반 차량 접근 권한 확인
- 사용자별 교체 알림 접근 권한 관리
- 이상 접근 패턴 감지
예외 처리
네트워크 관련
- 연결 실패: 오프라인 모드 지원, 마지막 소모품 데이터 캐싱
- 응답 지연: 로딩 인디케이터, 타임아웃 처리
- 서버 다운: 에러 메시지 표시, 재시도 제안
센서 관련
- 센서 오작동: 센서 오작동 알림
- 센서 데이터 무효: 무효 센서 데이터 알림
- 센서 통신 오류: 센서 통신 오류 알림
소모품 관련
- 교체 기한 초과: 기한 초과 교체 알림
- 예상 밖 마모: 예상 밖의 마모 패턴 알림
- 품질 이슈: 제품 품질 이슈 알림
권한 관련
- 인증 실패: 재인증 요청
- 권한 부족: 권한 부족에 대한 명확한 설명 제공
- 교체 알림 접근 권한: 교체 알림 접근 권한 부족 알림
테스트 설정
Base URL: https://api.ecarus.run/api/v1/information
인증 토큰: sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d
샘플 VIN: KMHSH81C7LU123456
대화형 API 테스트를 위해 Swagger UI를 사용하십시오.
배포 고려사항
앱 스토어 등록
- 소모품 데이터 수집 권한 요청
- 푸시 알림 권한 요청
- 소모품 교체 알림 기능에 대한 명확한 설명
법규 준수
- 개인정보 보호법 준수
- 소모품 데이터 수집에 대한 명시적 동의 필요
- 데이터 보유 정책 준수
- 정비 기록 보호
차량 호환성
- 다양한 차종 지원
- 다양한 소모품 유형 지원
- OEM별 소모품 구현 차이 반영 고려
- 센서 통신 프로토콜 차이 반영 고려