자동 진단(Automatic Diagnosis) API 개발자 가이드

서비스 개요

자동 진단 서비스는 차량이 이상 상태를 감지했을 때 운전자의 개입 없이 자동으로 진단 데이터를 생성하여 서버로 전송하는 텔레매틱스 기반 진단 서비스입니다.

서비스 특징

차량 이상 상태 자동 감지 및 진단
운전자 개입 없는 자동 진단 프로세스
실시간 고장 코드 분석 및 알림
예방 중심의 차량 관리 지원
다양한 트리거 기반의 자동 진단

법적 요구사항

개인정보 보호법 준수
차량 진단 데이터 수집 동의 필수
고장 정보 보유 기간 정책 준수
차량 제어 관련 규정 준수

주요 시나리오

시나리오 1: 자동 진단 모니터링

엔티티별 API 흐름:

📱 앱 (사용자):

최신 리포트: 최신 진단 결과 확인
건강 트렌드: 시간 경과에 따른 차량 건강 점수 분석
DTC 삭제: 정비 후 고장 코드 초기화

🚗 차량 (TCU):

자동 감지: 차량 이상 상태 자동 감지
데이터 전송: 진단 데이터를 ECARUS 서버로 전송

🏢 콜센터:

이력 조회: 차량 진단 기록 조회
DTC 상세: 상세 고장 코드 정보 획득
이벤트 모니터링: 진단 이벤트 실시간 감지

주요 기능

앱 기능

최신 리포트: 자동 진단 결과 상세 리포트 확인
실시간 상태: 현재 차량 진단 상태 확인
건강 트렌드: 차량 건강 점수 추이 분석
DTC 조회: 현재 활성화된 진단 고장 코드 확인
DTC 삭제: 정비 후 DTC 코드 삭제 및 초기화
이력 조회: 과거 자동 진단 기록 확인
실시간 모니터링: 자동 진단 실시간 이벤트 스트림 수신

콜센터 기능

DTC 관리: DTC 코드 목록 조회 및 상세 고장 코드 정보 확인
진단 이력: 차량 진단 기록 조회
이벤트 모니터링: 진단 이벤트 실시간 모니터링
진단 데이터 분석: 수신된 진단 데이터의 종합 분석 및 패턴 감지
위험 상태 판별: 심각도에 따른 차량 주행 가능 여부 판별
서비스 연계: 정비소 추천 및 비상 상황 시 긴급 출동 연계

시퀀스 다이어그램

자동 진단 시스템 흐름

자동 진단

API 엔드포인트

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

자동 진단

현재 DTC 조회

bash

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

DTC 삭제

bash

curl -X DELETE "https://api.ecarus.run/api/v1/diagnosis/vehicles/KMHSH81C7LU123456/auto/dtc" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d" \
     -H "Content-Type: application/json" \
     -d '{"codes": ["P0520", "P0301"], "reason": "After sensor replacement"}'

자동 진단 이력 조회

bash

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

실시간 진단 상태 조회

bash

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

차량 건강 점수 트렌드 조회

bash

curl -X GET "https://api.ecarus.run/api/v1/diagnosis/vehicles/KMHSH81C7LU123456/auto/health/trend?period=90d" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d"

DTC 관리

DTC 코드 상세 정보 조회

bash

curl -X GET "https://api.ecarus.run/api/v1/diagnosis/dtc/P0520" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d"

DTC 코드 목록 조회

bash

curl -X GET "https://api.ecarus.run/api/v1/diagnosis/dtc/list?limit=10" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d"

자동 진단 실시간 이벤트 수신 (SSE)

참고: 브라우저를 통해 접속하거나 전용 SSE 클라이언트 사용 권장

bash

curl -N -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d" \
     "https://api.ecarus.run/api/v1/diagnosis/vehicles/KMHSH81C7LU123456/auto/events"

데이터 모델

DTC (진단 고장 코드) 응답

현재 활성화된 진단 고장 코드 목록 응답 모델

json

{
  "vin": "KMHSH81C7LU123456",
  "timestamp": "2026-01-13T14:30:00Z",
  "dtc": [
    {
      "code": "P0520",
      "ecu": "ECM",
      "status": "ACTIVE",
      "description": "Engine Oil Pressure Sensor/Switch Circuit",
      "severity": "MEDIUM",
      "firstOccurrence": "2026-01-13T14:25:00Z",
      "occurrenceCount": 3,
      "lastOccurrence": "2026-01-13T14:30:00Z"
    },
    {
      "code": "P0301",
      "ecu": "ECM", 
      "status": "ACTIVE",
      "description": "Cylinder 1 Misfire Detected",
      "severity": "HIGH",
      "firstOccurrence": "2026-01-13T14:20:00Z",
      "occurrenceCount": 1,
      "lastOccurrence": "2026-01-13T14:30:00Z"
    }
  ],
  "totalCount": 2
}

자동 진단 리포트

최신 자동 진단 결과 상세 리포트

json

{
  "reportId": "report-12345",
  "vin": "KMHSH81C7LU123456",
  "timestamp": "2026-01-13T14:30:00Z",
  "summary": {
    "overallStatus": "WARNING",
    "healthScore": 75,
    "dtcCount": 2,
    "criticalCount": 0,
    "highCount": 1,
    "mediumCount": 1,
    "lowCount": 0
  },
  "dtc": [
    {
      "code": "P0520",
      "ecu": "ECM",
      "status": "ACTIVE",
      "description": "Engine Oil Pressure Sensor/Switch Circuit",
      "severity": "MEDIUM",
      "occurrenceCount": 3,
      "freezeFrame": {
        "rpm": 2500,
        "speed": 65,
        "temperature": 85,
        "load": 45
      }
    }
  ],
  "ecuStatus": {
    "ECM": {
      "status": "NORMAL",
      "softwareVersion": "v2.1.5",
      "lastUpdate": "2026-01-10T10:00:00Z"
    },
    "BCM": {
      "status": "NORMAL",
      "softwareVersion": "v1.8.2"
    },
    "TCU": {
      "status": "NORMAL",
      "softwareVersion": "v3.0.1"
    }
  },
  "vehicleStatus": {
    "ignition": "ON",
    "mileage": 45230,
    "batteryVoltage": 14.2,
    "fuelLevel": 65.5,
    "engineTemperature": 85.0
  },
  "recommendations": [
    {
      "priority": "HIGH",
      "action": "SERVICE_CENTER_VISIT",
      "description": "Engine oil pressure sensor inspection needed",
      "estimatedCost": "150-300"
    }
  ]
}

자동 진단 이력

과거 자동 진단 기록 목록

json

{
  "vin": "KMHSH81C7LU123456",
  "period": "30d",
  "history": [
    {
      "reportId": "report-12345",
      "timestamp": "2026-01-13T14:30:00Z",
      "overallStatus": "WARNING",
      "healthScore": 75,
      "dtcCount": 2,
      "criticalIssues": 0
    },
    {
      "reportId": "report-12344", 
      "timestamp": "2026-01-10T09:15:00Z",
      "overallStatus": "NORMAL",
      "healthScore": 92,
      "dtcCount": 0,
      "criticalIssues": 0
    }
  ],
  "pagination": {
    "total": 15,
    "limit": 10,
    "offset": 0,
    "hasMore": true
  }
}

실시간 진단 상태

현재 차량 진단 상태 정보

json

{
  "vin": "KMHSH81C7LU123456",
  "timestamp": "2026-01-13T14:30:00Z",
  "status": "ACTIVE",
  "healthScore": 75,
  "activeDtcCount": 2,
  "lastDiagnosis": "2026-01-13T14:30:00Z",
  "nextScheduledCheck": "2026-01-13T15:00:00Z",
  "systemStatus": {
    "obd": "ONLINE",
    "ecu": "ONLINE",
    "sensors": "NORMAL"
  }
}

차량 건강 점수 트렌드

차량 건강 점수 시계열 데이터

json

{
  "vin": "KMHSH81C7LU123456",
  "period": "90d",
  "trend": [
    {
      "date": "2026-01-13",
      "healthScore": 75,
      "dtcCount": 2,
      "criticalCount": 0
    },
    {
      "date": "2026-01-12",
      "healthScore": 78,
      "dtcCount": 1,
      "criticalCount": 0
    }
  ],
  "summary": {
    "averageScore": 82.5,
    "minScore": 75,
    "maxScore": 95,
    "trendDirection": "STABLE"
  }
}

DTC 코드 상세 정보

특정 DTC 코드의 상세 설명

json

{
  "code": "P0520",
  "description": "Engine Oil Pressure Sensor/Switch Circuit",
  "category": "ENGINE",
  "severity": "MEDIUM",
  "symptoms": [
    "Engine warning light on",
    "Oil pressure warning",
    "Engine performance degradation"
  ],
  "causes": [
    "Oil pressure sensor failure",
    "Wiring issues",
    "Oil pump failure"
  ],
  "recommendations": [
    "Service center visit recommended",
    "Check oil level"
  ],
  "estimatedCost": "150-400"
}

DTC 코드 목록

DTC 코드 검색 결과 목록

json

{
  "codes": [
    {
      "code": "P0520",
      "description": "Engine Oil Pressure Sensor/Switch Circuit",
      "category": "ENGINE",
      "severity": "MEDIUM"
    },
    {
      "code": "P0301", 
      "description": "Cylinder 1 Misfire Detected",
      "category": "IGNITION",
      "severity": "HIGH"
    }
  ],
  "pagination": {
    "total": 245,
    "limit": 10,
    "offset": 0,
    "hasMore": true
  }
}

실시간 진단 이벤트 (SSE)

자동 진단 실시간 이벤트 스트림

json

{
  "eventType": "DIAGNOSIS_EVENT",
  "eventId": "event-67890",
  "vin": "KMHSH81C7LU123456",
  "timestamp": "2026-01-13T14:30:00Z",
  "data": {
    "type": "NEW_DTC_DETECTED",
    "dtc": {
      "code": "P0520",
      "description": "Engine Oil Pressure Sensor/Switch Circuit",
      "severity": "MEDIUM"
    },
    "healthScore": 75
  }
}

보안 및 프라이버시

인증 및 권한 부여

사용자 인증 토큰 필요 (JWT/OAuth2)
차량 접근 권한 확인
진단 데이터 수신 권한 확인

데이터 보안

모든 API 통신은 HTTPS/TLS 암호화
진단 데이터 전송 시 보안 조치
민감 차량 정보는 서버에만 저장

프라이버시 보호

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

접근 제어

VIN 기반 차량 접근 권한 확인
사용자별 진단 데이터 접근 권한 관리
이상 접근 패턴 감지

예외 처리

네트워크 관련

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

차량 상태 관련

차량 시동 꺼짐: 마지막으로 저장된 진단 결과 표시
ECU 응답 없음: 일부 ECU 응답 없음을 알림
진단 실패: 진단 실패 알림 및 재시도 안내

데이터 관련

데이터 손상: 진단 데이터 손상 알림
분석 실패: 진단 분석 실패 알림
DTC 오류: DTC 코드 오류 처리

알림 관련

알림 실패: 알림 전송 실패 시 재시도
알림 중복: 중복 알림 방지 처리
알림 무시: 사용자 알림 무시 설정 반영

테스트 설정

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

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

배포 고려사항

앱 스토어 등록

차량 진단 데이터 수집 권한 요청
푸시 알림 권한 요청
차량 상태 모니터링 기능에 대한 명확한 설명

법규 준수

개인정보 보호법 준수
진단 데이터 수집 동의 필수
고장 정보 보유 기간 정책 준수
차량 제어 관련 규정 준수

차량 호환성

다양한 차종 지원
ECU 유형별 진단 방법 차이 고려
OEM별 진단 프로토콜 차이 반영
진단 가능 항목 차이 고려

자동 진단(Automatic Diagnosis) API 개발자 가이드 ​

서비스 개요 ​

서비스 특징 ​

법적 요구사항 ​

주요 시나리오 ​

시나리오 1: 자동 진단 모니터링 ​

주요 기능 ​

앱 기능 ​

콜센터 기능 ​

시퀀스 다이어그램 ​

자동 진단 시스템 흐름 ​

API 엔드포인트 ​

자동 진단 ​

현재 DTC 조회 ​

DTC 삭제 ​

최신 자동 진단 리포트 조회 ​

자동 진단 이력 조회 ​

실시간 진단 상태 조회 ​

차량 건강 점수 트렌드 조회 ​

DTC 관리 ​

DTC 코드 상세 정보 조회 ​

DTC 코드 목록 조회 ​

자동 진단 실시간 이벤트 수신 (SSE) ​

데이터 모델 ​

DTC (진단 고장 코드) 응답 ​

자동 진단 리포트 ​

자동 진단 이력 ​

실시간 진단 상태 ​

차량 건강 점수 트렌드 ​

DTC 코드 상세 정보 ​

DTC 코드 목록 ​

실시간 진단 이벤트 (SSE) ​

보안 및 프라이버시 ​

인증 및 권한 부여 ​

데이터 보안 ​

프라이버시 보호 ​

접근 제어 ​

예외 처리 ​

네트워크 관련 ​

차량 상태 관련 ​

데이터 관련 ​

알림 관련 ​

테스트 설정 ​

배포 고려사항 ​

앱 스토어 등록 ​

법규 준수 ​

차량 호환성 ​

자동 진단(Automatic Diagnosis) API 개발자 가이드

서비스 개요

서비스 특징

법적 요구사항

주요 시나리오

시나리오 1: 자동 진단 모니터링

주요 기능

앱 기능

콜센터 기능

시퀀스 다이어그램

자동 진단 시스템 흐름

API 엔드포인트

자동 진단

현재 DTC 조회

DTC 삭제

최신 자동 진단 리포트 조회

자동 진단 이력 조회

실시간 진단 상태 조회

차량 건강 점수 트렌드 조회

DTC 관리

DTC 코드 상세 정보 조회

DTC 코드 목록 조회

자동 진단 실시간 이벤트 수신 (SSE)

데이터 모델

DTC (진단 고장 코드) 응답

자동 진단 리포트

자동 진단 이력

실시간 진단 상태

차량 건강 점수 트렌드

DTC 코드 상세 정보

DTC 코드 목록

실시간 진단 이벤트 (SSE)

보안 및 프라이버시

인증 및 권한 부여

데이터 보안

프라이버시 보호

접근 제어

예외 처리

네트워크 관련

차량 상태 관련

데이터 관련

알림 관련

테스트 설정

배포 고려사항

앱 스토어 등록

법규 준수

차량 호환성