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

서비스 개요

수동 진단 서비스는 고객이나 정비사가 차량의 이상 상태를 확인하기 위해 직접 진단을 요청하는 텔레매틱스 서비스입니다.

서비스 특징

사용자 직접 진단 요청 기능
실시간 진단 진행 상황 모니터링
상세 차량 진단 결과 확인
정비소 방문 전 원격 진단 지원
다양한 사용자 그룹 지원

법적 요구사항

개인정보 보호법 준수
차량 진단 데이터 수집 동의 필수
진단 권한 관리 정책 준수
차량 제어 관련 규정 준수

주요 시나리오

시나리오 1: 원격 전문가 진단 요청 및 동의

엔티티별 API 흐름:

🏢 콜센터:

세션 요청: 차량 진단 세션 생성 요청
진단 명령: 진단 명령 전송 (LIVE_STREAM, READ_DTC)
세션 종료: 진단 세션 종료 요청

📱 사용자 앱:

진단 동의: 원격 진단 실행에 대한 동의 제공
모니터링: 진단 진행 상황 실시간 확인

🚗 차량 (TCU):

진단 세션 수신: ECARUS로부터 진단 세션 요청 수신
실시간 데이터 전송: 라이브 데이터 스트리밍 (RPM, COOLANT_TEMP 등)
ECU 진단 실행: DTC 코드 판독 및 진단 데이터 수집
진단 세션 종료: 세션 종료 명령 처리

시나리오 2: 실시간 진단 데이터 스트리밍

엔티티별 API 흐름:

🏢 콜센터:

스트림 제어: CMD_LIVE_STREAM 또는 CMD_READ_DTC 명령 전송
데이터 수신: SSE를 통한 라이브 데이터 실시간 수신
분석: 수신된 진단 데이터 실시간 분석

📱 사용자 앱:

진단 진행 확인: 현재 진단 중인 항목 및 상태 확인
실시간 알림: 진단 진행 상황 푸시 알림 수신

🚗 차량 (TCU):

데이터 스트리밍 시작: 1초 간격으로 라이브 데이터 전송
ECU 통신: UDS 프로토콜을 사용한 ECU 데이터 요청
진단 데이터 전송: RPM, 온도 등 실시간 데이터 전송
DTC 코드 전송: 진단 오류 코드 전송

시나리오 3: 진단 관리 및 리포트 생성

엔티티별 API 흐름:

🏢 콜센터:

세션 조회: 활성 진단 세션 목록 조회
이력 조회: 과거 진단 이력 조회
DTC 조회: DTC 코드 목록 조회
리포트 조회: 최종 진단 결과 확인

📱 사용자 앱:

진단 결과 확인: 최종 진단 결과 및 리포트 확인
이력 관리: 과거 진단 이력 및 결과 조회

🚗 차량 (TCU):

진단 세션 관리: 세션 상태 유지 및 관리
데이터 저장: 진단 데이터 임시 저장

주요 기능

📱 앱 구현 기능

1. 진단 동의 관리

진단 동의: 원격 진단 실행에 대한 동의 제공
동의 상태: 현재 동의 상태 실시간 확인

2. 진단 상태 모니터링

실시간 상태: 현재 진단 진행 상황 실시간 표시

3. 진단 결과 확인

결과 조회: 최종 진단 결과 확인
이력 조회: 과거 진단 이력 및 결과 조회

🏢 콜센터 구현 기능

4. 관리자 기능

세션 관리: 전체 진단 세션 관리 및 모니터링
기술자 관리: 진단 기술자 권한 및 관리
품질 관리: 진단 품질 검증 및 개선
통계 분석: 진단 통계 및 성과 분석

시퀀스 다이어그램

수동 진단 시스템 흐름

수동 진단

API 엔드포인트

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

수동 진단 세션 시작

수동 진단 세션 요청

bash

curl -X POST "https://api.ecarus.run/api/v1/diagnosis/vehicles/KMHSH81C7LU123456/manual/session-request" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d" \
     -H "Content-Type: application/json" \
     -d '{"reason": "Engine Noise Check", "technicianId": "TECH_001"}'

진단 동의 제공

bash

curl -X POST "https://api.ecarus.run/api/v1/diagnosis/vehicles/KMHSH81C7LU123456/manual/consent" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d" \
     -H "Content-Type: application/json" \
     -d '{"allow": true, "requestId": "req_001"}'

수동 진단 세션 종료

bash

curl -X POST "https://api.ecarus.run/api/v1/diagnosis/vehicles/KMHSH81C7LU123456/manual/session-stop" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d" \
     -H "Content-Type: application/json" \
     -d '{"sessionId": "sess_001", "reason": "DIAGNOSIS_COMPLETED"}'

진단 명령 전송

bash

curl -X POST "https://api.ecarus.run/api/v1/diagnosis/vehicles/KMHSH81C7LU123456/manual/command" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d" \
     -H "Content-Type: application/json" \
     -d '{"cmd": "CMD_LIVE_STREAM", "pids": ["RPM", "COOLANT_TEMP"]}'

수동 진단 세션 리포트 조회

bash

curl -X GET "https://api.ecarus.run/api/v1/diagnosis/vehicles/KMHSH81C7LU123456/manual/session/sess_001/report" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d"

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

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

bash

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

데이터 모델

진단 세션 요청

json

{
  "vin": "KMHSH81C7LU123456",
  "reason": "Engine Noise Check",
  "technicianId": "TECH_001"
}

진단 명령

json

{
  "cmd": "CMD_LIVE_STREAM",
  "pids": ["RPM", "COOLANT_TEMP", "SPEED"],
  "sessionId": "sess_001"
}

진단 동의

json

{
  "allow": true,
  "requestId": "req_001",
  "timestamp": "2026-01-13T14:30:00Z"
}

진단 세션 상태

json

{
  "sessionId": "sess_001",
  "vin": "KMHSH81C7LU123456",
  "status": "ACTIVE",
  "startTime": "2026-01-13T14:30:00Z",
  "technicianId": "TECH_001",
  "reason": "Engine Noise Check",
  "consent": {
    "status": "GRANTED",
    "timestamp": "2026-01-13T14:31:00Z"
  },
  "currentCommand": {
    "cmd": "CMD_LIVE_STREAM",
    "status": "EXECUTING",
    "startTime": "2026-01-13T14:32:00Z"
  }
}

라이브 데이터 스트림 이벤트

json

{
  "eventType": "LIVE_DATA",
  "sessionId": "sess_001",
  "vin": "KMHSH81C7LU123456",
  "timestamp": "2026-01-13T14:32:00Z",
  "data": {
    "rpm": 2500,
    "coolantTemp": 85.5,
    "speed": 65.2,
    "fuelPressure": 45.8,
    "throttlePosition": 12.5
  }
}

진단 리포트

json

{
  "reportId": "report-12345",
  "sessionId": "sess_001",
  "vin": "KMHSH81C7LU123456",
  "timestamp": "2026-01-13T14:45:00Z",
  "summary": {
    "overallStatus": "WARNING",
    "dtcCount": 1,
    "criticalIssues": 0,
    "recommendations": ["Service center visit recommended"]
  },
  "dtc": [
    {
      "code": "P0520",
      "description": "Engine Oil Pressure Sensor/Switch Circuit",
      "severity": "MEDIUM",
      "occurrenceCount": 1
    }
  ],
  "liveData": {
    "averageRpm": 2200,
    "maxCoolantTemp": 92.5,
    "dataPoints": 150
  },
  "recommendations": [
    {
      "priority": "MEDIUM",
      "action": "INSPECT_OIL_PRESSURE_SENSOR",
      "description": "Check oil pressure sensor and wiring"
    }
  ]
}

보안 및 프라이버시

인증 및 권한 부여

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

데이터 보안

모든 API 통신은 HTTPS/TLS 암호화
라이브 데이터 스트리밍 보안 조치
전송 중 민감 차량 정보 보호

프라이버시 보호

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

접근 제어

VIN 기반 차량 접근 권한 확인
사용자별 진단 세션 접근 관리
기술자 역할 기반 접근 제어
이상 세션 감지 및 차단

예외 처리

네트워크 관련

연결 실패: 세션 타임아웃 및 재시도 처리
응답 지연: 실시간 데이터 스트리밍 지연 처리
서버 다운: 세션 유지 및 복구

차량 관련

차량 시동 꺼짐: 세션 종료 알림
ECU 응답 없음: 부분 진단 결과 알림
진단 실패: 에러 알림 및 재시도 안내

세션 관련

세션 타임아웃: 자동 세션 종료
동의 타임아웃: 동의 부재로 인한 세션 취소
다중 세션: 동시 중복 세션 방지

데이터 관련

데이터 유실: 라이브 데이터 유실 알림
데이터 손상: 데이터 무결성 검증
전송 지연: 실시간 데이터 지연 처리

테스트 설정

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

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

배포 고려사항

앱 스토어 등록

원격 진단 권한 요청
푸시 알림 권한 요청
원격 진단 기능에 대한 명확한 설명

법규 준수

개인정보 보호법 준수
수동 진단 동의 필수
진단 권한 관리 정책 준수
차량 제어 관련 규정 준수

차량 호환성

다양한 차종 지원
ECU 통신 프로토콜 차이 고려
OEM별 진단 프로토콜 차이 반영
실시간 데이터 전송 능력 고려

세션 관리

세션 타임아웃 정책 설정
중복 세션 방지 메커니즘
세션 복구 및 페일오버 시스템
세션 감사 로그 및 모니터링

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

서비스 개요 ​

서비스 특징 ​

법적 요구사항 ​

주요 시나리오 ​

시나리오 1: 원격 전문가 진단 요청 및 동의 ​

시나리오 2: 실시간 진단 데이터 스트리밍 ​

시나리오 3: 진단 관리 및 리포트 생성 ​

주요 기능 ​

📱 앱 구현 기능 ​

1. 진단 동의 관리 ​

2. 진단 상태 모니터링 ​

3. 진단 결과 확인 ​

🏢 콜센터 구현 기능 ​

1. 진단 세션 관리 ​

2. 진단 명령 제어 ​

3. 진단 관리 및 분석 ​

4. 관리자 기능 ​

시퀀스 다이어그램 ​

수동 진단 시스템 흐름 ​

API 엔드포인트 ​

수동 진단 세션 시작 ​

수동 진단 세션 요청 ​

진단 동의 제공 ​

수동 진단 세션 종료 ​

진단 명령 전송 ​

진단 명령 전송 ​

수동 진단 세션 리포트 조회 ​

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

데이터 모델 ​

진단 세션 요청 ​

진단 명령 ​

진단 동의 ​

진단 세션 상태 ​

라이브 데이터 스트림 이벤트 ​

진단 리포트 ​

보안 및 프라이버시 ​

인증 및 권한 부여 ​

데이터 보안 ​

프라이버시 보호 ​

접근 제어 ​

예외 처리 ​

네트워크 관련 ​

차량 관련 ​

세션 관련 ​

데이터 관련 ​

테스트 설정 ​

배포 고려사항 ​

앱 스토어 등록 ​

법규 준수 ​

차량 호환성 ​

세션 관리 ​

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

서비스 개요

서비스 특징

법적 요구사항

주요 시나리오

시나리오 1: 원격 전문가 진단 요청 및 동의

시나리오 2: 실시간 진단 데이터 스트리밍

시나리오 3: 진단 관리 및 리포트 생성

주요 기능

📱 앱 구현 기능

1. 진단 동의 관리

2. 진단 상태 모니터링

3. 진단 결과 확인

🏢 콜센터 구현 기능

1. 진단 세션 관리

2. 진단 명령 제어

3. 진단 관리 및 분석

4. 관리자 기능

시퀀스 다이어그램

수동 진단 시스템 흐름

API 엔드포인트

수동 진단 세션 시작

수동 진단 세션 요청

진단 동의 제공

수동 진단 세션 종료

진단 명령 전송

진단 명령 전송

수동 진단 세션 리포트 조회

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

데이터 모델

진단 세션 요청

진단 명령

진단 동의

진단 세션 상태

라이브 데이터 스트림 이벤트

진단 리포트

보안 및 프라이버시

인증 및 권한 부여

데이터 보안

프라이버시 보호

접근 제어

예외 처리

네트워크 관련

차량 관련

세션 관련

데이터 관련

테스트 설정

배포 고려사항

앱 스토어 등록

법규 준수

차량 호환성

세션 관리