월간 주행 리포트 API 개발자 가이드

서비스 개요

월간 리포트 서비스는 모바일 앱이나 웹 플랫폼을 통해 사용자에게 월간 주행 통계 및 분석 리포트를 제공하는 텔레매틱스 서비스입니다.

서비스 특징

월간 주행 통계 및 분석
연비 분석 및 추이
주행 행동 분석
차량 건강 상태 리포트
맞춤형 권장 사항

법적 요구사항

개인정보 보호법 준수
주행 데이터 수집에 대한 명시적 동의 필요
위치 정보에 대한 별도 동의 필요
데이터 보유 정책 준수

주요 시나리오

시나리오 1: 월간 리포트 생성 및 전달

엔티티별 API 흐름:

📱 앱 (사용자):

최신 리포트 조회: 최신 운전 습관 리포트 조회
리포트 목록 조회: 월간 리포트 이력 목록 조회
리포트 공유: 특정 리포트 공유

🏢 콜센터:

요청 처리: 월간 리포트 생성 요청 처리
데이터 수집: 지난 한 달간의 주행 데이터 수집
리포트 생성: 종합 월간 리포트 생성
전달: 사용자 앱으로 리포트 전송
저장: 향후 접근을 위해 리포트 저장

시나리오 2: 주행 통계 분석

엔티티별 API 흐름:

📱 앱 (사용자):

통계 요청: 최신 월간 주행 통계 요청
차트 표시: 주행 통계 차트 표시
추이 분석: 주행 추이 분석 표시

🏢 콜센터:

데이터 분석: 월간 주행 패턴 분석
통계 생성: 종합 통계 생성
추이 계산: 주행 추이 계산
인사이트: 주행 인사이트 및 권장 사항 제공

시나리오 3: 연비 분석

엔티티별 API 흐름:

📱 앱 (사용자):

연비 요청: 최신 리포트에서 연비 분석 요청
연비 표시: 연비 차트 표시
비교: 연비 비교 데이터 표시

🏢 콜센터:

연비 분석: 월간 연비 패턴 분석
비교 데이터: 연비 비교 데이터 생성
최적화 팁: 연료 최적화 권장 사항 제공

시나리오 4: 주행 행동 분석

엔티티별 API 흐름:

📱 앱 (사용자):

행동 요청: 최신 리포트에서 주행 행동 분석 요청
행동 점수: 주행 행동 점수 표시
개선 팁: 주행 개선 권장 사항 표시

🏢 콜센터:

행동 분석: 월간 주행 행동 패턴 분석
점수 계산: 주행 행동 점수 계산
개선 권장 사항: 맞춤형 주행 개선 팁 제공

시나리오 5: 차량 건강 리포트

엔티티별 API 흐름:

📱 앱 (사용자):

건강 요청: 최신 리포트에서 차량 건강 분석 요청
건강 상태: 차량 건강 상태 표시
정비 권장 사항: 정비 권장 사항 표시

🏢 콜센터:

건강 분석: 월간 차량 건강 상태 분석
이상 감지: 잠재적 차량 문제 감지
정비 계획: 정비 계획 권장 사항 제공

시나리오 6: 리포트 이력 및 비교

엔티티별 API 흐름:

📱 앱 (사용자):

이력 요청: 리포트 이력 목록 조회
비교: 전월 대비 비교 데이터 표시
추이 분석: 장기적 추이 표시

🏢 콜센터:

이력 관리: 월간 리포트 이력 관리
비교 데이터: 전월 대비 비교 데이터 생성
추이 분석: 장기적 주행 추이 분석

주요 기능

📱 앱 구현 기능

1. 리포트 요청 및 관리

최신 리포트 조회: 최신 운전 습관 리포트 조회
리포트 목록 조회: 월간 리포트 이력 목록 조회
리포트 공유: 특정 리포트 공유

2. 통계 및 분석 표시

통계 표시: 종합 주행 통계 표시
차트 시각화: 다양한 통계 차트 표시
추이 분석: 주행 추이 분석 표시
비교: 전월 대비 비교 데이터 표시

3. 연비 분석

연비 표시: 연비 분석 결과 표시
연비 추이: 연비 추이 표시
최적화 팁: 연료 최적화 권장 사항 표시
비교: 연비 비교 데이터 표시

4. 주행 행동 분석

행동 점수: 주행 행동 점수 표시
행동 분석: 상세 행동 분석 표시
개선 팁: 주행 개선 권장 사항 표시
진척도 추적: 행동 개선 진척도 추적

5. 차량 건강 모니터링

건강 상태: 차량 건강 상태 표시
이상 감지: 감지된 차량 문제 표시
정비 권장 사항: 정비 권장 사항 표시
서비스 이력: 서비스 이력 표시

🏢 콜센터 구현 기능

1. 월간 리포트 생성 시스템

리포트 처리: 월간 리포트 생성 요청 처리
데이터 수집: 종합 주행 데이터 수집
리포트 생성: 상세 월간 리포트 생성
전달 관리: 사용자에 대한 리포트 전달 관리
저장 관리: 리포트 저장 및 아카이빙 관리

2. 주행 통계 분석

통계 생성: 종합 주행 통계 생성
패턴 분석: 주행 패턴 분석
추이 계산: 주행 추이 계산
인사이트 생성: 주행 인사이트 및 권장 사항 생성

3. 연비 분석

연비 분석: 연비 패턴 분석
비교 데이터 생성: 연비 비교 데이터 생성
최적화 분석: 연료 최적화 분석 제공
추천 엔진: 연료 최적화 권장 사항 생성

4. 주행 행동 분석

행동 분석: 주행 행동 패턴 분석
점수 계산: 주행 행동 점수 계산
개선 분석: 행동 개선 분석 제공
개인화: 맞춤형 권장 사항 생성

5. 차량 건강 분석

건강 모니터링: 차량 건강 상태 모니터링
이상 감지: 잠재적 차량 문제 감지
정비 계획: 정비 계획 수립 지원
서비스 권장 사항: 서비스 권장 사항 생성

6. API 서비스 관리

API 응답 처리: 월간 리포트 관련 API 요청 처리
요청 검증: API 요청 유효성 검증
성능 모니터링: API 응답 시간 및 가용성 모니터링
에러 핸들링: API 에러 및 예외 처리
버전 관리: API 버전 및 호환성 관리

7. 데이터 보안 및 프라이버시

데이터 수집 동의: 주행 데이터 수집 동의 관리
프라이버시 보호: 사용자 주행 데이터 프라이버시 보호
데이터 보안: 안전한 주행 데이터 처리
감사 로깅: 데이터 접근에 대한 감사 로그 유지
접근 제어: 사용자 접근 권한 관리

8. 시스템 운영 및 모니터링

시스템 상태 모니터링: 월간 리포트 시스템 24시간 모니터링
데이터 품질 관리: 데이터 품질 및 정확성 관리
성능 최적화: 리포트 생성 성능 최적화
예외 처리: 시스템 예외 및 에러 처리
시스템 확장: 대용량 처리를 위한 시스템 확장 지원

9. 데이터 분석 및 통계

패턴 분석: 주행 패턴 통계 분석
이용 통계: 월간 리포트 이용 통계 생성
서비스 품질 분석: 서비스 품질 지표 분석
개선 권장 사항: 서비스 개선 권장 사항 생성

시퀀스 다이어그램

월간 리포트 시스템 흐름

월간 리포트

API 엔드포인트

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

운전 습관 리포트 목록 조회

bash

curl -X GET "https://api.ecarus.run/api/v1/information/vehicles/KMHSH81C7LU123456/driving-behavior-report/list" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d"

운전 습관 리포트 공유

bash

curl -X POST "https://api.ecarus.run/api/v1/information/vehicles/KMHSH81C7LU123456/driving-behavior-report/report-001/share" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d" \
     -H "Content-Type: application/json" \
     -d '{"shareTo": "user@example.com", "platform": "EMAIL"}'

데이터 모델

월간 리포트 요청 응답

json

{
  "vin": "KMHSH81C7LU123456",
  "userId": "user123",
  "reportId": "report-001",
  "month": "2026-01",
  "format": "PDF",
  "language": "ko",
  "status": "PROCESSING",
  "estimatedCompletion": "2026-01-15T14:30:00Z",
  "createdAt": "2026-01-13T14:30:00Z"
}

월간 리포트 상태 응답

json

{
  "vin": "KMHSH81C7LU123456",
  "userId": "user123",
  "reportId": "report-001",
  "status": "COMPLETED",
  "progress": 100,
  "createdAt": "2026-01-13T14:30:00Z",
  "completedAt": "2026-01-13T14:35:00Z",
  "downloadUrl": "https://api.ecarus.run/api/v1/information/vehicles/KMHSH81C7LU123456/monthly-report/download?reportId=report-001",
  "expiresAt": "2026-01-20T14:35:00Z"
}

월간 리포트 내용

json

{
  "vin": "KMHSH81C7LU123456",
  "userId": "user123",
  "reportId": "report-001",
  "month": "2026-01",
  "generatedAt": "2026-01-13T14:35:00Z",
  "report": {
    "summary": {
      "totalDistance": 1850,
      "totalTrips": 45,
      "totalFuelConsumed": 157.25,
      "averageEfficiency": 8.5,
      "averageSpeed": 42.3,
      "drivingTime": 2750
    },
    "statistics": {
      "daily": {
        "averageDailyDistance": 59.7,
        "maxDailyDistance": 125,
        "minDailyDistance": 0,
        "drivingDays": 31
      },
      "weekly": {
        "averageWeeklyDistance": 425,
        "maxWeeklyDistance": 580,
        "minWeeklyDistance": 180
      },
      "trip": {
        "averageTripDistance": 41.1,
        "maxTripDistance": 125,
        "minTripDistance": 2,
        "averageTripDuration": 1800
      }
    },
    "fuelEfficiency": {
      "monthlyAverage": 8.5,
      "bestEfficiency": 6.8,
      "worstEfficiency": 12.3,
      "efficiencyTrend": "IMPROVING",
      "fuelCost": 157250,
      "costPerKm": 85
    },
    "drivingBehavior": {
      "score": 85,
      "hardBraking": 12,
      "rapidAcceleration": 8,
      "speedingEvents": 3,
      "nightDriving": 15,
      "behaviorTrend": "IMPROVING"
    },
    "vehicleHealth": {
      "overallHealth": "GOOD",
      "engineStatus": "NORMAL",
      "batteryHealth": "GOOD",
      "tirePressure": "NORMAL",
      "maintenanceDue": false,
      "nextService": "2026-02-10T00:00:00Z"
    },
    "recommendations": [
      {
        "type": "FUEL_EFFICIENCY",
        "priority": "HIGH",
        "message": "연비 개선을 위해 정속 주행을 유지하세요.",
        "potentialSavings": 15
      },
      {
        "type": "DRIVING_BEHAVIOR",
        "priority": "MEDIUM",
        "message": "안전과 효율성을 위해 급제동을 줄이세요.",
        "potentialSavings": 8
      }
    ]
  }
}

보안 및 프라이버시

인증 및 권한 부여

사용자 인증 토큰 필요 (JWT/OAuth2)
차량 접근 권한 확인
리포트 접근 권한 확인

데이터 보안

모든 API 통신은 HTTPS/TLS 암호화
주행 데이터의 안전한 전송
민감한 위치 정보 보호

프라이버시 보호

주행 데이터 수집에 대한 명시적 동의
위치 정보에 대한 별도 동의
데이터 보유 정책 준수
사용자 요청 시 데이터 삭제 권한 보장

접근 제어

VIN 기반 차량 접근 권한 확인
사용자별 리포트 접근 권한 관리
이상 접근 패턴 감지

예외 처리

네트워크 관련

연결 실패: 오프라인 모드 지원, 마지막 리포트 캐싱
응답 지연: 로딩 인디케이터, 타임아웃 처리
서버 다운: 에러 메시지 표시, 재시도 제안

리포트 생성 관련

생성 실패: 생성 실패 알림
타임아웃: 리포트 생성 타임아웃 처리
데이터 부족: 데이터 부족 알림

데이터 관련

데이터 누락: 데이터 누락 알림
데이터 불일치: 데이터 불일치 처리
계산 오류: 계산 오류 알림

권한 관련

인증 실패: 재인증 요청
권한 부족: 권한 부족에 대한 명확한 설명 제공
데이터 접근 권한: 데이터 접근 권한 부족 알림

테스트 설정

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

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

배포 고려사항

앱 스토어 등록

주행 데이터 수집 권한 요청
위치 정보 수집 권한 요청 (선택 사항)
월간 리포트 모니터링 기능에 대한 명확한 설명

법규 준수

개인정보 보호법 준수
주행 데이터 수집에 대한 명시적 동의 필요
위치 정보에 대한 별도 동의 필요
데이터 보유 정책 준수

차량 호환성

다양한 차종 지원
내연기관/전기차/하이브리드 지원
OEM별 데이터 형식 차이 반영 고려
센서 유형별 데이터 처리 차이 고려

월간 주행 리포트 API 개발자 가이드 ​

서비스 개요 ​

서비스 특징 ​

법적 요구사항 ​

주요 시나리오 ​

시나리오 1: 월간 리포트 생성 및 전달 ​

시나리오 2: 주행 통계 분석 ​

시나리오 3: 연비 분석 ​

시나리오 4: 주행 행동 분석 ​

시나리오 5: 차량 건강 리포트 ​

시나리오 6: 리포트 이력 및 비교 ​

주요 기능 ​

📱 앱 구현 기능 ​

1. 리포트 요청 및 관리 ​

2. 통계 및 분석 표시 ​

3. 연비 분석 ​

4. 주행 행동 분석 ​

5. 차량 건강 모니터링 ​

🏢 콜센터 구현 기능 ​

1. 월간 리포트 생성 시스템 ​

2. 주행 통계 분석 ​

3. 연비 분석 ​

4. 주행 행동 분석 ​

5. 차량 건강 분석 ​

6. API 서비스 관리 ​

7. 데이터 보안 및 프라이버시 ​

8. 시스템 운영 및 모니터링 ​

9. 데이터 분석 및 통계 ​

시퀀스 다이어그램 ​

월간 리포트 시스템 흐름 ​

API 엔드포인트 ​

최신 운전 습관 리포트 조회 ​

운전 습관 리포트 목록 조회 ​

운전 습관 리포트 공유 ​

데이터 모델 ​

월간 리포트 요청 응답 ​

월간 리포트 상태 응답 ​

월간 리포트 내용 ​

보안 및 프라이버시 ​

인증 및 권한 부여 ​

데이터 보안 ​

프라이버시 보호 ​

접근 제어 ​

예외 처리 ​

네트워크 관련 ​

리포트 생성 관련 ​

데이터 관련 ​

권한 관련 ​

테스트 설정 ​

배포 고려사항 ​

앱 스토어 등록 ​

법규 준수 ​

차량 호환성 ​

월간 주행 리포트 API 개발자 가이드

서비스 개요

서비스 특징

법적 요구사항

주요 시나리오

시나리오 1: 월간 리포트 생성 및 전달

시나리오 2: 주행 통계 분석

시나리오 3: 연비 분석

시나리오 4: 주행 행동 분석

시나리오 5: 차량 건강 리포트

시나리오 6: 리포트 이력 및 비교

주요 기능

📱 앱 구현 기능

1. 리포트 요청 및 관리

2. 통계 및 분석 표시

3. 연비 분석

4. 주행 행동 분석

5. 차량 건강 모니터링

🏢 콜센터 구현 기능

1. 월간 리포트 생성 시스템

2. 주행 통계 분석

3. 연비 분석

4. 주행 행동 분석

5. 차량 건강 분석

6. API 서비스 관리

7. 데이터 보안 및 프라이버시

8. 시스템 운영 및 모니터링

9. 데이터 분석 및 통계

시퀀스 다이어그램

월간 리포트 시스템 흐름

API 엔드포인트

최신 운전 습관 리포트 조회

운전 습관 리포트 목록 조회

운전 습관 리포트 공유

데이터 모델

월간 리포트 요청 응답

월간 리포트 상태 응답

월간 리포트 내용

보안 및 프라이버시

인증 및 권한 부여

데이터 보안

프라이버시 보호

접근 제어

예외 처리

네트워크 관련

리포트 생성 관련

데이터 관련

권한 관련

테스트 설정

배포 고려사항

앱 스토어 등록

법규 준수

차량 호환성