원격 위치 확인 API 개발자 가이드

서비스 개요

원격 위치 확인(내 차 찾기)은 넓은 주차장이나 대형 쇼핑몰 주차장 등의 환경에서 사용자가 차량의 경적(Horn)과 비상등(Hazard Lamp)을 원격으로 작동시켜 차량의 위치를 쉽게 찾을 수 있도록 돕는 텔레매틱스 기능입니다.

서비스 특징

원격 경적 및 비상등 작동을 통한 손쉬운 차량 위치 식별
다양한 모드 제공 (경적만, 비상등만, 동시 작동)
단방향 명령 기반의 빠른 응답성
주차 상태에서만 작동하는 안전 정책
남용 방지를 위한 호출 제한(Rate Limit) 적용

법적 요구사항

차량 경적 소리 관련 규정 준수
공공장소 사용 시간 제한 준수
개인정보 보호법 준수
남용 방지 정책 적용

주요 시나리오

시나리오 1: 원격 위치 확인 요청 및 실행

엔티티별 API 흐름:

📱 앱 (사용자):

위치 요청: 원격 위치 확인 요청
응답 수신: 202 Accepted 응답 수신
푸시 알림: 위치 확인 결과 푸시 알림 수신
지도 표시: 수신된 위치 정보를 지도에 표시

🚗 차량 (TCU):

명령 수신: ECARUS로부터 위치 확인 명령 수신
프라이버시 모드 확인: GPS 공유 설정 상태 확인
GPS 수신: GPS 위성 신호 수신 및 위치 계산
결과 게시: 성공/실패 결과를 ECARUS로 게시

🏢 콜센터:

대리 요청: 고객을 대신하여 위치 확인 요청
상태 확인: 위치 서비스 상태 확인
결과 수신: 위치 확인 결과 수신

시나리오 2: 위치 확인 실패 및 예외 처리

엔티티별 API 흐름:

📱 앱 (사용자):

명령 요청: 위치 확인 명령 요청
실패 알림: 푸시 알림을 통해 실패 원인 수신
상태 확인: 현재 위치 서비스 상태 확인
설정 확인: 프라이버시 설정 확인

🚗 차량 (TCU):

프라이버시 모드 확인: 위치 정보 공유 비활성화 상태 확인
GPS 상태 확인: GPS 모듈 상태 및 신호 세기 확인
실패 처리: 프라이버시 모드 또는 GPS 신호 약함 시 실패 처리
결과 게시: 실패 결과 및 에러 코드 게시

🏢 콜센터:

이력 조회: 실패 이력 조회
동의 확인: 위치 정보 동의 상태 확인
고객 지원: 실패 원인 분석 및 고객 안내

시나리오 3: 위치 정보 동의 관리 및 프라이버시 보호

엔티티별 API 흐름:

📱 앱 (사용자):

동의 요청: 위치 정보 수집 동의
동의 확인: 동의 상태 확인
동의 철회: 위치 정보 동의 철회
설정 관리: 동의 기간 및 목적 관리

🚗 차량 (TCU):

동의 확인: 위치 정보 수집 동의 여부 확인
데이터 수집: 동의된 범위 내에서 위치 데이터 수집
보안 전송: 암호화된 위치 데이터 전송
프라이버시 보호: 개인정보 보호 정책 준수

🏢 콜센터:

동의 관리: 동의 상태 확인
이력 관리: 위치 이력 관리
분석 조회: 위치 분석 조회
프라이버시 보호: 위치 정보 개인정보 보호 처리

시나리오 4: 위치 상태 모니터링 및 이력 관리

엔티티별 API 흐름:

📱 앱 (사용자):

최근 위치 조회: 최신 위치 정보 조회
상태 조회: 위치 서비스 상태 확인
실시간 모니터링: SSE 스트림을 통한 실시간 위치 모니터링
이력 확인: 위치 이력 확인

🚗 차량 (TCU):

상태 수집: GPS 상태, 신호 세기 실시간 수집
위치 전송: 주기적 위치 데이터 전송
이벤트 게시: 위치 변경 이벤트 게시
상태 보고: 현재 위치 서비스 상태 보고

🏢 콜센터:

상태 모니터링: 실시간 위치 서비스 상태 확인
이력 조회: 위치 이력 조회
분석 관리: 위치 분석 관리
동의 관리: 고객 동의 상태 관리

주요 기능

📱 앱 구현 기능

1. 원격 위치 확인 기능

위치 요청: 원격 위치 확인 요청
최근 위치 조회: 최신 위치 정보 조회
상태 조회: 위치 서비스 상태 확인

2. 위치 정보 동의 관리 기능

동의 요청: 위치 정보 수집 동의
동의 확인: 동의 상태 확인
동의 철회: 위치 정보 동의 철회

3. 실시간 모니터링 기능

실시간 업데이트: SSE 스트림을 통한 실시간 위치 모니터링
이벤트 처리: 위치 변경 이벤트 실시간 처리
지도 표시: 수신된 위치 정보의 지도 시각화

4. 알림 및 UI 기능

푸시 알림: 위치 확인 결과 푸시 알림 수신
지도 표시: 지도상에 위치 정보 시각화
에러 안내: 실패 시 사용자 친화적 에러 메시지 제공

🏢 콜센터 구현 기능

1. 대리 위치 확인 기능

대리 위치 요청: 고객을 대신하여 위치 확인 요청
상태 확인: 위치 서비스 상태 확인

2. 이력 및 분석 관리 기능

이력 조회: 위치 이력 조회
분석 조회: 위치 분석 조회
통계 생성: 주행 통계 및 방문 패턴 분석 생성

3. 동의 관리 기능

동의 확인: 고객 동의 상태 확인
프라이버시 보호: 위치 정보 개인정보 보호 처리
동의 이력: 동의/철회 이력 관리

4. 고객 지원 기능

문제 해결: 위치 확인 실패 원인 분석
설정 지원: 고객 위치 설정 지원
보안 모니터링: 이상 접근 패턴 모니터링

🚗 차량(TCU) 처리 기능

1. 위치 확인 기능

GPS 수신: GPS 위성 신호 수신 및 위치 계산
프라이버시 확인: 위치 정보 공유 설정 상태 확인
결과 게시: 위치 확인 결과 게시

2. 상태 관리 기능

GPS 상태 모니터링: GPS 모듈 상태 및 신호 세기 모니터링
위치 데이터 수집: 주기적 위치 데이터 수집
이벤트 게시: 위치 변경 이벤트 게시

3. 프라이버시 보호 기능

동의 상태 확인: 위치 정보 수집 동의 여부 확인
데이터 보호: 개인정보 보호 정책 준수
보안 전송: 암호화된 위치 데이터 전송

시퀀스 다이어그램

원격 위치 확인 시스템 흐름

원격 위치 확인

API 엔드포인트

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

위치 확인 요청

bash

curl -X POST "https://api.ecarus.run/api/v1/remotecontrol/vehicles/KMHSH81C7LU123456/location" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d" \
     -H "Content-Type: application/json" \
     -d '{"accuracy": "HIGH", "timeout": 10}'

위치 서비스 상태 조회

bash

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

위치 확인 이력 조회

bash

curl -X GET "https://api.ecarus.run/api/v1/remotecontrol/vehicles/KMHSH81C7LU123456/location/history?period=24h&limit=100&includeAddress=true" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d"

위치 정보 수집 동의

bash

curl -X POST "https://api.ecarus.run/api/v1/remotecontrol/vehicles/KMHSH81C7LU123456/location/consent" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d" \
     -H "Content-Type: application/json" \
     -d '{"consent": true, "expiresAt": "2024-12-31T23:59:59Z", "purpose": "보안 및 편의를 위한 차량 위치 추적", "dataRetention": 90}'

위치 정보 동의 철회

bash

curl -X DELETE "https://api.ecarus.run/api/v1/remotecontrol/vehicles/KMHSH81C7LU123456/location/consent" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d" \
     -H "Content-Type: application/json" \
     -d '{"reason": "개인정보 보호 우려", "immediate": true}'

위치 정보 동의 상태 확인

bash

curl -X GET "https://api.ecarus.run/api/v1/remotecontrol/vehicles/KMHSH81C7LU123456/location/consent" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d"

위치 분석 데이터 조회

bash

curl -X GET "https://api.ecarus.run/api/v1/remotecontrol/vehicles/KMHSH81C7LU123456/location/analytics?period=30d&type=all" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d"

위치 정보 실시간 업데이트 스트림 (SSE)

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

bash

curl -X GET "https://api.ecarus.run/api/v1/remotecontrol/vehicles/KMHSH81C7LU123456/location/updates/stream" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d" \
     -H "Accept: text/event-stream"

데이터 모델

위치 확인 요청 (Location Request)

json

{
  "accuracy": "HIGH",
  "timeout": 10
}

accuracy: LOW, MEDIUM, HIGH
timeout: 요청 타임아웃 (초 단위, 최대 60)

위치 서비스 상태 응답 (Status Response)

json

{
  "vin": "KMHSH81C7LU123456",
  "isOnline": true,
  "lastUpdate": "2026-01-12T14:30:00Z",
  "locationEnabled": true,
  "gpsSignalStrength": "STRONG",
  "lastLocation": {
    "latitude": 37.5665,
    "longitude": 126.9780,
    "timestamp": "2026-01-12T14:30:00Z"
  },
  "timestamp": "2026-01-12T14:30:00Z"
}

gpsSignalStrength: NONE, WEAK, MODERATE, STRONG

위치 정보 응답 (Location Response)

json

{
  "vin": "KMHSH81C7LU123456",
  "location": {
    "latitude": 37.5665,
    "longitude": 126.9780,
    "accuracy": 5.2,
    "altitude": 15.8,
    "heading": 0.0,
    "address": "서울특별시 중구 세종대로 110",
    "timestamp": "2026-01-12T14:30:00Z"
  },
  "vehicleStatus": {
    "speed": 0,
    "ignitionStatus": "OFF",
    "gearPosition": "P"
  },
  "timestamp": "2026-01-12T14:30:00Z"
}

위치 확인 이력 요청 (History Request)

period: 24h
limit: 100
offset: 0
includeAddress: true
includeSpeed: true

period: 1h, 24h, 7d, 30d

위치 확인 이력 응답

json

{
  "vin": "KMHSH81C7LU123456",
  "history": [
    {
      "latitude": 37.5665,
      "longitude": 126.9780,
      "accuracy": 5.2,
      "altitude": 15.8,
      "address": "서울특별시 중구 세종대로 110",
      "speed": 0,
      "heading": 0.0,
      "ignitionStatus": "OFF",
      "timestamp": "2026-01-12T14:30:00Z"
    }
  ],
  "total": 1,
  "hasMore": false
}

json

{
  "consent": true,
  "expiresAt": "2024-12-31T23:59:59Z",
  "purpose": "보안 및 편의를 위한 차량 위치 추적",
  "dataRetention": 90,
  "scope": ["tracking", "analytics", "emergency"]
}

scope: tracking, analytics, emergency, sharing
dataRetention: 데이터 보관 기간 (일 단위)

위치 정보 동의 응답

json

{
  "vin": "KMHSH81C7LU123456",
  "consent": true,
  "grantedAt": "2026-01-12T14:30:00Z",
  "expiresAt": "2024-12-31T23:59:59Z",
  "purpose": "보안 및 편의를 위한 차량 위치 추적",
  "dataRetention": 90,
  "scope": ["tracking", "analytics", "emergency"],
  "lastAccess": "2026-01-12T14:30:00Z",
  "accessCount": 15
}

위치 분석 데이터 요청

period: 30d
type: all
includeDetails: true

period: 7d, 30d, 90d, 1y
type: all, driving, parking, routes

위치 분석 데이터 응답

json

{
  "vin": "KMHSH81C7LU123456",
  "period": "30d",
  "analytics": {
    "totalDistance": 1250.5,
    "averageSpeed": 45.2,
    "maxSpeed": 125.8,
    "parkingTime": 480,
    "drivingTime": 320,
    "idleTime": 65,
    "fuelConsumed": 85.2,
    "mostVisitedLocations": [
      {
        "address": "서울특별시 중구 세종대로 110",
        "visitCount": 15,
        "totalDuration": 240,
        "coordinates": {
          "latitude": 37.5665,
          "longitude": 126.9780
        }
      }
    ],
    "routes": [
      {
        "from": "서울특별시 중구",
        "to": "서울특별시 강남구",
        "frequency": 8,
        "averageDuration": 25
      }
    ]
  },
  "timestamp": "2026-01-12T14:30:00Z"
}

위치 업데이트 알림 (SSE)

json

{
  "type": "LOCATION_UPDATE",
  "vin": "KMHSH81C7LU123456",
  "timestamp": "2026-01-12T14:30:00Z",
  "data": {
    "latitude": 37.5665,
    "longitude": 126.9780,
    "accuracy": 5.2,
    "altitude": 15.8,
    "speed": 0,
    "heading": 0.0,
    "ignitionStatus": "OFF",
    "changeType": "LOCATION_UPDATE"
  }
}

type: LOCATION_UPDATE, GEOFENCE_ENTER, GEOFENCE_EXIT, SPEED_ALERT
changeType: LOCATION_UPDATE, IGNITION_ON, IGNITION_OFF, MOVEMENT_START, MOVEMENT_STOP

보안 및 프라이버시

인증 및 권한 부여

사용자 인증 토큰 필요 (JWT/OAuth2)
차량 접근 권한 확인
위치 확인 기능 권한 확인

데이터 보안

모든 API 통신은 HTTPS/TLS 암호화
명령 위조 방지를 위한 Command Signing 적용
MQTT ACL 기반의 VIN별 접근 제어

프라이버시 보호

차량 상태 정보 수집에 대한 명시적 동의
위치 정보 수집 목적 명시
명령 실행 이력 보존 기간 정책 준수

접근 제어

VIN 기반 차량 접근 권한 확인
명령 호출 제한(Rate Limit) 적용
이상 접근 패턴 감지
남용 방지 정책 적용

예외 처리

네트워크 관련

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

차량 상태 관련

차량 오프라인: 명령 전송 실패 알림
주행 중: 기능 제한 알림 및 안내 메시지 표시
배터리 부족: 실행 제한 알림

명령 실행 관련

실패: 실패 원인 명확히 표시
타임아웃: 명령 유효 시간(TTL) 만료 알림
일부 성공: 일부 기능만 작동 시 상세 안내

규제 관련

시간 제한: 공공장소 사용 시간 제한 안내
소음 규제: 경적 사용 시간 제한 안내
현지 법규: 국가별 규정 준수 안내

테스트 설정

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

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

배포 고려사항

앱 스토어 등록

차량 제어 관련 권한 요청
위치 정보 수집에 대한 명확한 설명
공공장소 사용 시 주의사항 안내

법규 준수

개인정보 보호법 준수
차량 경적 소리 관련 규정 확인
공공장소 소음 규제 준수
국가별 차량 제어 관련 법규 확인

차량 호환성

다양한 차종 지원
OEM별 경적/비상등 제어 방식 차이 고려
국가별 규제 차이 반영

원격 위치 확인 API 개발자 가이드 ​

서비스 개요 ​

서비스 특징 ​

법적 요구사항 ​

주요 시나리오 ​

시나리오 1: 원격 위치 확인 요청 및 실행 ​

시나리오 2: 위치 확인 실패 및 예외 처리 ​

시나리오 3: 위치 정보 동의 관리 및 프라이버시 보호 ​

시나리오 4: 위치 상태 모니터링 및 이력 관리 ​

주요 기능 ​

📱 앱 구현 기능 ​

1. 원격 위치 확인 기능 ​

2. 위치 정보 동의 관리 기능 ​

3. 실시간 모니터링 기능 ​

4. 알림 및 UI 기능 ​

🏢 콜센터 구현 기능 ​

1. 대리 위치 확인 기능 ​

2. 이력 및 분석 관리 기능 ​

3. 동의 관리 기능 ​

4. 고객 지원 기능 ​

🚗 차량(TCU) 처리 기능 ​

1. 위치 확인 기능 ​

2. 상태 관리 기능 ​

3. 프라이버시 보호 기능 ​

시퀀스 다이어그램 ​

원격 위치 확인 시스템 흐름 ​

API 엔드포인트 ​

위치 확인 요청 ​

위치 서비스 상태 조회 ​

최신 위치 정보 조회 ​

위치 확인 이력 조회 ​

위치 정보 수집 동의 ​

위치 정보 동의 철회 ​

위치 정보 동의 상태 확인 ​

위치 분석 데이터 조회 ​

위치 정보 실시간 업데이트 스트림 (SSE) ​

데이터 모델 ​

위치 확인 요청 (Location Request) ​

위치 서비스 상태 응답 (Status Response) ​

위치 정보 응답 (Location Response) ​

위치 확인 이력 요청 (History Request) ​

위치 확인 이력 응답 ​

위치 정보 동의 요청 (Consent Request) ​

위치 정보 동의 응답 ​

위치 분석 데이터 요청 ​

위치 분석 데이터 응답 ​

위치 업데이트 알림 (SSE) ​

보안 및 프라이버시 ​

인증 및 권한 부여 ​

데이터 보안 ​

프라이버시 보호 ​

접근 제어 ​

예외 처리 ​

네트워크 관련 ​

차량 상태 관련 ​

명령 실행 관련 ​

규제 관련 ​

테스트 설정 ​

배포 고려사항 ​

앱 스토어 등록 ​

법규 준수 ​

차량 호환성 ​

원격 위치 확인 API 개발자 가이드

서비스 개요

서비스 특징

법적 요구사항

주요 시나리오

시나리오 1: 원격 위치 확인 요청 및 실행

시나리오 2: 위치 확인 실패 및 예외 처리

시나리오 3: 위치 정보 동의 관리 및 프라이버시 보호

시나리오 4: 위치 상태 모니터링 및 이력 관리

주요 기능

📱 앱 구현 기능

1. 원격 위치 확인 기능

2. 위치 정보 동의 관리 기능

3. 실시간 모니터링 기능

4. 알림 및 UI 기능

🏢 콜센터 구현 기능

1. 대리 위치 확인 기능

2. 이력 및 분석 관리 기능

3. 동의 관리 기능

4. 고객 지원 기능

🚗 차량(TCU) 처리 기능

1. 위치 확인 기능

2. 상태 관리 기능

3. 프라이버시 보호 기능

시퀀스 다이어그램

원격 위치 확인 시스템 흐름

API 엔드포인트

위치 확인 요청

위치 서비스 상태 조회

최신 위치 정보 조회

위치 확인 이력 조회

위치 정보 수집 동의

위치 정보 동의 철회

위치 정보 동의 상태 확인

위치 분석 데이터 조회

위치 정보 실시간 업데이트 스트림 (SSE)

데이터 모델

위치 확인 요청 (Location Request)

위치 서비스 상태 응답 (Status Response)

위치 정보 응답 (Location Response)

위치 확인 이력 요청 (History Request)

위치 확인 이력 응답

위치 정보 동의 요청 (Consent Request)

위치 정보 동의 응답

위치 분석 데이터 요청

위치 분석 데이터 응답

위치 업데이트 알림 (SSE)

보안 및 프라이버시

인증 및 권한 부여

데이터 보안

프라이버시 보호

접근 제어

예외 처리

네트워크 관련

차량 상태 관련

명령 실행 관련

규제 관련

테스트 설정

배포 고려사항

앱 스토어 등록

법규 준수

차량 호환성