정기 진단(Scheduled Diagnosis) API 개발자 가이드

서비스 개요

정기 진단 서비스는 사전 정의된 일정에 따라 주기적으로 차량 상태를 점검하는 텔레매틱스 기반 차량 진단 서비스입니다.

서비스 특징

주기적인 자동 차량 상태 점검
예방 중심의 차량 관리
사용자 개입 없는 자동 실행
알림 중심의 결과 전달
배치 시스템 기반 운영

법적 요구사항

개인정보 보호법 준수
차량 진단 데이터 수집 동의 필수
정기 점검 동의 필수
데이터 보유 기간 정책 준수

주요 시나리오

시나리오 1: 월간 정기 진단 자동 실행 및 결과 알림

엔티티별 API 흐름:

🏢 콜센터:

스케줄 트리거: 월간 정기 진단 트리거
리포트 생성: 월간 리포트 자동 생성 및 저장
알림 전송: 푸시 알림을 통해 사용자에게 통보

📱 사용자 앱:

최신 리포트: 최신 정기 진단 리포트 조회
소모품 상태: 현재 소모품 상태 조회
정비 예약: 파악된 문제에 대한 정비 예약
스케줄 설정: 사용자 정의 진단 스케줄 설정

🚗 차량 (TCU):

진단 요청 수신: 서버로부터 진단 요청 수신
데이터 수집: 주행거리, 오일 수명, 타이어 공기압 등 데이터 수집
결과 전송: 진단 결과를 서버로 전송
절전 모드: 진단 완료 후 절전 모드로 전환

시나리오 2: 정기 진단 스케줄 관리 및 설정

엔티티별 API 흐름:

🏢 콜센터:

스케줄 조회: 현재 스케줄 설정 조회
스케줄 설정: 스케줄 설정 변경
통계 조회: 24개월 통계 조회
데이터 분석: 진단 데이터의 종합 분석
리포트 관리: 전체 월간 리포트 관리

📱 사용자 앱:

최신 리포트: 최신 정기 진단 리포트 조회
소모품 상태: 상세 소모품 분석
정비 예약: 정비 예약 실행
통계 확인: 정비 통계 확인

🚗 차량 (TCU):

스케줄 수신: 변경된 스케줄 정보 수신
스케줄 적용: 새로운 스케줄 자동 적용
정기 진단: 설정된 스케줄에 따라 정기 진단 실행
상태 보고: 진단 실행 상태 주기적 보고

시나리오 3: 소모품 상태 분석 및 정비 안내

엔티티별 API 흐름:

🏢 콜센터:

소모품 조회: 소모품 상태 조회
수명 계산: 사용량 기반 소모품 수명 계산
정비 필요 판별: 교체 시기 도달 여부 판별
알림 생성: 정비 필요 알림 자동 생성
비용 예측: 정비 비용 예측 및 통계 제공

📱 사용자 앱:

소모품 상태: 소모품 상태 확인
정비 예약: 정비 예약 실행

🚗 차량 (TCU):

소모품 데이터: 오일 수명, 타이어 공기압 등 데이터 수집
상태 계산: 현재 소모품 상태 계산
데이터 전송: 소모품 상태 정보 전송
warning 시그널: 소모품 교체 필요 시 경고 시그널 전송

주요 기능

📱 앱 구현 기능

4. 정비 서비스 연계

서비스 예약: 정비 예약 실행

🏢 콜센터 구현 기능

1. 정기 진단 스케줄링 시스템

스케줄 트리거: 월간 정기 진단 트리거
스케줄 설정: 글로벌 또는 차량별 스케줄 설정 변경

2. 자동 진단 실행 시스템

진단 요청: CMD_GET_CONSUMABLES 명령으로 차량 진단 요청
데이터 수집: 주행거리, 오일 수명, 타이어 공기압 등 데이터 수집
결과 처리: 진단 결과 자동 처리 및 저장
리포트 생성: 월간 리포트 자동 생성
알림 전송: 푸시 알림을 통해 결과 자동 전송

3. 리포트 관리 시스템

최신 리포트: 최신 리포트 제공
리포트 목록: 과거 리포트 목록 제공 (12개월)
리포트 생성: 월간 리포트 자동 생성 및 저장
데이터 분석: 진단 데이터의 종합 분석
리포트 저장: 모든 리포트의 영구 저장

4. 소모품 분석 시스템

소모품 상태: 소모품 상태 조회
통계 조회: 차량별 정비 통계 조회

5. 통계 및 분석 시스템

통계 조회: 24개월 통계 조회
비용 분석: 정비 비용 및 예상 비용 분석
패턴 분석: 차량 상태 변화 패턴 분석
성과 리포트: 정기 진단 서비스 성과 리포트 생성
개선 제안: 데이터 기반 서비스 개선 제안 생성

6. 정비 서비스 연계 시스템

정비 예약: 정비 예약 접수
예약 관리: 정비 예약 상태 및 이력 관리
서비스 제공자: 정비소 및 서비스 제공자 정보 관리
만족도 분석: 정비 서비스 만족도 분석
비용 관리: 정비 비용 및 예상 비용 관리

시퀀스 다이어그램

정기 진단 시스템 흐름

정기 진단

API 엔드포인트

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

정기 진단 리포트 조회

소모품 상태 조회

bash

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

정기 진단 서비스

정기 진단 예약

bash

curl -X POST "https://api.ecarus.run/api/v1/diagnosis/vehicles/KMHSH81C7LU123456/scheduled/maintenance/schedule" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d" \
     -H "Content-Type: application/json" \
     -d '{"serviceType": "OIL_CHANGE", "preferredDate": "2026-01-20", "preferredTime": "10:00"}'

월간 진단 트리거

bash

curl -X POST "https://api.ecarus.run/api/v1/diagnosis/scheduled/monthly-trigger" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d"

스케줄 설정

bash

curl -X POST "https://api.ecarus.run/api/v1/diagnosis/vehicles/KMHSH81C7LU123456/scheduled/config" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d" \
     -H "Content-Type: application/json" \
     -d '{"scheduleType": "MONTHLY", "dayOfMonth": 15, "time": "03:00", "enabled": true}'

진단 통계 조회

bash

curl -X GET "https://api.ecarus.run/api/v1/diagnosis/vehicles/KMHSH81C7LU123456/scheduled/statistics?period=24m" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d"

데이터 모델

정기 진단 리포트

json

{
  "reportId": "report-12345",
  "vin": "KMHSH81C7LU123456",
  "reportDate": "2026-01-15",
  "summary": {
    "overallStatus": "NORMAL",
    "healthScore": 92,
    "consumablesChecked": 8,
    "issuesFound": 0,
    "maintenanceNeeded": false
  },
  "consumables": [
    {
      "item": "ENGINE_OIL",
      "status": "NORMAL",
      "remainingLife": 75,
      "nextService": "2026-04-15",
      "currentMileage": 45230
    },
    {
      "item": "BRAKE_PADS",
      "status": "WARNING",
      "remainingLife": 25,
      "nextService": "2026-02-20",
      "currentMileage": 45230
    }
  ],
  "recommendations": [
    {
      "priority": "MEDIUM",
      "item": "BRAKE_PADS",
      "action": "SCHEDULE_INSPECTION",
      "description": "Brake pads approaching replacement time"
    }
  ],
  "generatedAt": "2026-01-15T03:30:00Z"
}

소모품 상태

json

{
  "vin": "KMHSH81C7LU123456",
  "timestamp": "2026-01-13T14:30:00Z",
  "consumables": [
    {
      "item": "ENGINE_OIL",
      "status": "NORMAL",
      "remainingLife": 75,
      "unit": "percentage",
      "currentMileage": 45230,
      "lastService": "2025-10-15",
      "nextService": "2026-04-15",
      "estimatedCost": "80-120"
    },
    {
      "item": "BRAKE_PADS",
      "status": "WARNING",
      "remainingLife": 25,
      "unit": "percentage",
      "currentMileage": 45230,
      "lastService": "2024-08-20",
      "nextService": "2026-02-20",
      "estimatedCost": "200-350"
    },
    {
      "item": "AIR_FILTER",
      "status": "NORMAL",
      "remainingLife": 60,
      "unit": "percentage",
      "currentMileage": 45230,
      "lastService": "2025-07-10",
      "nextService": "2026-03-10",
      "estimatedCost": "40-80"
    }
  ],
  "summary": {
    "totalItems": 8,
    "normalItems": 6,
    "warningItems": 2,
    "criticalItems": 0,
    "nextMaintenance": "2026-02-20"
  }
}

정비 스케줄

json

{
  "bookingId": "booking-12345",
  "vin": "KMHSH81C7LU123456",
  "serviceType": "OIL_CHANGE",
  "preferredDate": "2026-01-20",
  "preferredTime": "10:00",
  "status": "CONFIRMED",
  "serviceCenter": {
    "id": "center-001",
    "name": "DaddyHouse Service Center",
    "address": "123 Service Road, Seoul",
    "phone": "02-1234-5678"
  },
  "estimatedCost": "100-150",
  "estimatedDuration": "45 minutes",
  "createdAt": "2026-01-13T14:30:00Z",
  "confirmedAt": "2026-01-13T15:00:00Z"
}

진단 통계

json

{
  "vin": "KMHSH81C7LU123456",
  "period": "24m",
  "statistics": {
    "totalDiagnoses": 24,
    "normalReports": 18,
    "warningReports": 6,
    "criticalReports": 0,
    "maintenanceEvents": 8,
    "totalMaintenanceCost": 1250.50,
    "averageMonthlyCost": 52.10,
    "healthScoreTrend": {
      "current": 92,
      "average": 88.5,
      "best": 95,
      "worst": 75
    },
    "consumableReplacements": [
      {
        "item": "ENGINE_OIL",
        "count": 3,
        "totalCost": 360.00,
        "averageInterval": "6 months"
      },
      {
        "item": "BRAKE_PADS",
        "count": 1,
        "totalCost": 280.00,
        "averageInterval": "24 months"
      }
    ]
  },
  "generatedAt": "2026-01-13T14:30:00Z"
}

스케줄 설정

json

{
  "vin": "KMHSH81C7LU123456",
  "scheduleType": "MONTHLY",
  "enabled": true,
  "schedule": {
    "dayOfMonth": 15,
    "time": "03:00",
    "timezone": "Asia/Seoul"
  },
  "nextExecution": "2026-02-15T03:00:00Z",
  "lastExecution": "2026-01-15T03:00:00Z",
  "executionHistory": [
    {
      "date": "2026-01-15",
      "status": "COMPLETED",
      "reportId": "report-12345"
    },
    {
      "date": "2025-12-15",
      "status": "COMPLETED",
      "reportId": "report-12344"
    }
  ],
  "updatedAt": "2026-01-13T14:30:00Z"
}

보안 및 프라이버시

인증 및 권한 부여

사용자 인증 토큰 필요 (JWT/OAuth2)
차량 접근 권한 확인
정기 진단 동의 확인
정비 예약 권한 확인

데이터 보안

모든 API 통신은 HTTPS/TLS 암호화
정기 진단 데이터 전송 보안
개인 정비 정보 보호

프라이버시 보호

정기 진단 시 명시적 동의 필수
진단 목적 명시
데이터 보유 기간 정책 준수
사용자 데이터 삭제 권한 보장

접근 제어

VIN 기반 차량 접근 권한 확인
사용자별 스케줄 접근 관리
정비 예약 접근 제어
이상 스케줄 패턴 감지

예외 처리

스케줄 관련

스케줄 실패: 자동 재시도 및 에러 알림
스케줄 충돌: 중복 스케줄 실행 방지
스케줄 타임아웃: 자동 재스케줄링

차량 관련

차량 시동 꺼짐: 스케줄 실행 연기
배터리 저전압: 스케줄 실행 취소
진단 실패: 에러 알림 및 재시도

데이터 관련

데이터 유실: 데이터 복구 및 재실행
데이터 손상: 데이터 무결성 검증
분석 실패: 기본 리포트 생성

알림 관련

알림 실패: 대체 알림 수단 활용
알림 중복: 중복 알림 방지
알림 무시: 사용자 설정 반영

테스트 설정

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

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

배포 고려사항

앱 스토어 등록

정기 진단 권한 요청
푸시 알림 권한 요청
주기적 진단 기능에 대한 명확한 설명

법규 준수

개인정보 보호법 준수
정기 진단 동의 필수
정기 점검 동의 요건 준수
데이터 보유 기간 정책 준수

차량 호환성

다양한 차종 지원
소모품 센서 차이 고려
OEM별 진단 프로토콜 차이 반영
예약 실행을 위한 배터리 용량 고려

배치 시스템 운영

배치 작업 스케줄링 최적화
대규모 차량 처리 능력 확보
시스템 자원 관리
실패 복구 및 재시도 메커니즘

정기 진단(Scheduled Diagnosis) API 개발자 가이드 ​

서비스 개요 ​

서비스 특징 ​

법적 요구사항 ​

주요 시나리오 ​

시나리오 1: 월간 정기 진단 자동 실행 및 결과 알림 ​

시나리오 2: 정기 진단 스케줄 관리 및 설정 ​

시나리오 3: 소모품 상태 분석 및 정비 안내 ​

주요 기능 ​

📱 앱 구현 기능 ​

1. 정기 진단 결과 확인 ​

2. 소모품 상태 관리 ​

3. 스케줄 관리 ​

4. 정비 서비스 연계 ​

🏢 콜센터 구현 기능 ​

1. 정기 진단 스케줄링 시스템 ​

2. 자동 진단 실행 시스템 ​

3. 리포트 관리 시스템 ​

4. 소모품 분석 시스템 ​

5. 통계 및 분석 시스템 ​

6. 정비 서비스 연계 시스템 ​

시퀀스 다이어그램 ​

정기 진단 시스템 흐름 ​

API 엔드포인트 ​

정기 진단 리포트 조회 ​

최신 정기 진단 리포트 조회 ​

소모품 상태 조회 ​

정기 진단 서비스 ​

정기 진단 예약 ​

월간 진단 트리거 ​

스케줄 설정 ​

진단 통계 조회 ​

데이터 모델 ​

정기 진단 리포트 ​

소모품 상태 ​

정비 스케줄 ​

진단 통계 ​

스케줄 설정 ​

보안 및 프라이버시 ​

인증 및 권한 부여 ​

데이터 보안 ​

프라이버시 보호 ​

접근 제어 ​

예외 처리 ​

스케줄 관련 ​

차량 관련 ​

데이터 관련 ​

알림 관련 ​

테스트 설정 ​

배포 고려사항 ​

앱 스토어 등록 ​

법규 준수 ​

차량 호환성 ​

배치 시스템 운영 ​

정기 진단(Scheduled Diagnosis) API 개발자 가이드

서비스 개요

서비스 특징

법적 요구사항

주요 시나리오

시나리오 1: 월간 정기 진단 자동 실행 및 결과 알림

시나리오 2: 정기 진단 스케줄 관리 및 설정

시나리오 3: 소모품 상태 분석 및 정비 안내

주요 기능

📱 앱 구현 기능

1. 정기 진단 결과 확인

2. 소모품 상태 관리

3. 스케줄 관리

4. 정비 서비스 연계

🏢 콜센터 구현 기능

1. 정기 진단 스케줄링 시스템

2. 자동 진단 실행 시스템

3. 리포트 관리 시스템

4. 소모품 분석 시스템

5. 통계 및 분석 시스템

6. 정비 서비스 연계 시스템

시퀀스 다이어그램

정기 진단 시스템 흐름

API 엔드포인트

정기 진단 리포트 조회

최신 정기 진단 리포트 조회

소모품 상태 조회

정기 진단 서비스

정기 진단 예약

월간 진단 트리거

스케줄 설정

진단 통계 조회

데이터 모델

정기 진단 리포트

소모품 상태

정비 스케줄

진단 통계

스케줄 설정

보안 및 프라이버시

인증 및 권한 부여

데이터 보안

프라이버시 보호

접근 제어

예외 처리

스케줄 관련

차량 관련

데이터 관련

알림 관련

테스트 설정

배포 고려사항

앱 스토어 등록

법규 준수

차량 호환성

배치 시스템 운영