Skip to content

소모품 교체 알림 API 개발자 가이드

서비스 개요

소모품 교체 알림 서비스는 차량 소모품을 모니터링하고 모바일 앱이나 웹 플랫폼을 통해 교체 알림 및 정비 권장 사항을 제공하는 텔레매틱스 서비스입니다.

서비스 특징

  • 소모품 라이프사이클 모니터링
  • 교체 주기 알림
  • 정비 일정 예약 지원
  • 교체 비용 추정
  • 정비소 추천

법적 요구사항

  • 개인정보 보호법 준수
  • 차량 데이터 수집에 대한 명시적 동의 필요
  • 데이터 보유 정책 준수
  • 정비 기록 보호

주요 시나리오

시나리오 1: 소모품 상태 업데이트 요청 및 처리

엔티티별 API 흐름:

📱 앱 (사용자):

  1. 상태 조회: 현재 소모품 상태 조회
  2. 상태 확인: 상태 업데이트 진행 상황 확인 (진행 중/완료)
  3. 알림 수신: 교체 주기 알림 수신

🚗 차량 (TCU):

  1. 센서 데이터 수집: 모든 센서로부터 소모품 상태 데이터 수집
  2. 데이터 전송: 서버로 소모품 상태 데이터 전송
  3. 교체 감지: 교체가 필요한 품목 감지

🏢 콜센터:

  1. 중복 요청 방지: 중복 요청 방지 로직 적용
  2. 명령 전송: 차량으로 소모품 상태 업데이트 명령 전송
  3. 데이터 처리: 수신된 소모품 데이터 처리 및 검증
  4. 교체 분석: 교체 요구 사항 분석
  5. 알림 생성: 교체 알림 생성
  6. 저장: 타임스탬프와 함께 소모품 데이터 저장

시나리오 2: 실시간 소모품 상태 조회

엔티티별 API 흐름:

📱 앱 (사용자):

  1. 상태 조회: 현재 소모품 상태 조회
  2. 상태 표시: 모든 소모품의 상태 표시
  3. 교체 표시: 교체 주기 인디케이터 표시

🏢 콜센터:

  1. 상태 제공: 최신 소모품 상태 제공
  2. 상태 관리: 소모품 상태 자동 관리
  3. 데이터 캐싱: 소모품 데이터의 효율적 캐싱
  4. 상태 분석: 소모품 사용 패턴 분석

시나리오 3: 소모품 이력 조회

엔티티별 API 흐름:

📱 앱 (사용자):

  1. 라이프사이클 조회: 소모품 라이프사이클 상태 조회
  2. 이력 표시: 교체 이력 타임라인 표시
  3. 패턴 분석: 소모품 사용 패턴 분석 표시

🏢 콜센터:

  1. 이력 관리: 소모품 교체 이력 자동 관리
  2. 패턴 분석: 소모품 사용 패턴 분석
  3. 통계 생성: 교체 통계 생성

시나리오 4: 교체 알림 및 경고

엔티티별 API 흐름:

📱 앱 (사용자):

  1. 알림 설정: 교체 알림 설정
  2. 알림 수신: 교체 주기 알림 수신
  3. 알림 관리: 알림 기본 설정 관리

🏢 콜센터:

  1. 알림 모니터링: 교체 요구 사항에 대한 소모품 모니터링
  2. 알림 생성: 교체 알림 생성
  3. 푸시 알림: 사용자 앱으로 푸시 알림 전송
  4. 에스컬레이션: 심각한 교체 요구 사항 에스컬레이션

시나리오 5: 정비 일정 예약

엔티티별 API 흐름:

📱 앱 (사용자):

  1. 일정 요청: 정비 일정 예약 요청
  2. 정비소 선택: 선호하는 정비소 선택
  3. 예약 확정: 정비 예약 확정

🏢 콜센터:

  1. 일정 처리: 정비 일정 예약 요청 처리
  2. 정비소 조율: 정비소와 일정 조율
  3. 예약 확인: 예약 상세 정보 확인
  4. 알림 관리: 예약 리마인더 관리

시나리오 6: 비용 추정 및 견적

엔티티별 API 흐름:

📱 앱 (사용자):

  1. 비용 조회: 교체 비용 추정 조회
  2. 견적 요청: 상세 견적 요청
  3. 비교: 정비소별 가격 비교

🏢 콜센터:

  1. 비용 분석: 교체 비용 분석
  2. 견적 생성: 상세 견적 생성
  3. 가격 비교: 가격 비교 정보 제공
  4. 할인 정보: 할인 정보 제공

시나리오 7: 실시간 교체 이벤트

엔티티별 API 흐름:

📱 앱 (사용자):

  1. SSE 연결: 실시간 교체 이벤트 스트림 연결
  2. 실시간 수신: 실시간으로 소모품 상태 변경 수신

🏢 콜센터:

  1. 이벤트 스트림 제공: 실시간 교체 이벤트 스트림 제공
  2. 이벤트 전송: 실시간으로 교체 상태 변경 이벤트 전송

시나리오 8: 정비소 추천

엔티티별 API 흐름:

📱 앱 (사용자):

  1. 추천 조회: 정비소 추천 조회
  2. 센터 선택: 선호하는 정비소 선택
  3. 리뷰 표시: 정비소 리뷰 표시

🏢 콜센터:

  1. 추천 생성: 정비소 추천 생성
  2. 품질 분석: 정비소 품질 분석
  3. 가용성 확인: 정비소 예약 가능 여부 확인
  4. 리뷰 관리: 정비소 리뷰 관리

주요 기능

📱 앱 구현 기능

1. 소모품 상태 모니터링

  • 상태 조회: 현재 소모품 상태 조회
  • 상태 표시: 모든 소모품의 상태 표시
  • 교체 인디케이터: 교체 주기 인디케이터 표시
  • 실시간 업데이트: 실시간 소모품 상태 업데이트
  • 진척도 표시: 소모품 라이프사이클 진척도 표시

2. 교체 이력

  • 라이프사이클 조회: 소모품 라이프사이클 조회
  • 타임라인 표시: 교체 이력 타임라인 표시
  • 패턴 분석: 소모품 사용 패턴 분석 표시
  • 통계: 교체 통계 표시

3. 알림 및 통지

  • 알림 설정: 교체 알림 설정
  • 알림 수신: 교체 주기 알림 수신
  • 알림 관리: 알림 기본 설정 관리
  • 알림 이력: 알림 이력 표시

4. 정비 일정 관리

  • 일정 요청: 정비 일정 예약 요청
  • 정비소 선택: 선호하는 정비소 선택
  • 예약 확정: 정비 예약 확정
  • 캘린더 연동: 사용자 캘린더와 연동

5. 비용 추정

  • 비용 조회: 교체 비용 추정 조회
  • 견적 표시: 상세 견적 표시
  • 가격 비교: 정비소별 가격 비교
  • 예산 계획: 교체 예산 계획 수립

6. 정비소 추천

  • 추천 조회: 정비소 추천 조회
  • 센터 표시: 추천 정비소 표시
  • 리뷰 표시: 정비소 리뷰 표시
  • 위치 표시: 정비소 위치 표시

7. 실시간 이벤트 수신


🏢 콜센터 구현 기능

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별 소모품 구현 차이 반영 고려
  • 센서 통신 프로토콜 차이 반영 고려

Released under the MIT License.