커퓨(심야 운행 제한) API 개발자 가이드

서비스 개요

커퓨(Curfew) 서비스는 미국 미성년자(16-17세) 임시 면허 운전자의 심야 운행 제한 정책을 차량 서비스에 적용하여, 특정 시간대의 차량 이용을 모니터링하고 제어하는 텔레매틱스 기반 기능입니다.

서비스 특징

심야 시간대 차량 운행 자동 감지
시간 기반 차량 이용 제한 정책 적용
보호자/관리자 실시간 알림
차량 엔진 제어 기능 (선택 사항)
청소년 운전자의 안전 강화

법적 요구사항

미국 지역별 커퓨 관련 규정 준수
운전자 사전 동의 필수
개인정보 및 위치정보 보호법 준수
주행 중 강제 엔진 정지 금지

주요 시나리오

시나리오 1: 커퓨 정책 설정

엔티티별 API 흐름:

📱 앱 (사용자):

정책 설정: 요일/시간대별 커퓨 규칙 설정
정책 조회: 현재 설정된 커퓨 정책 확인
예외 설정: 일시적인 커퓨 해제

🚗 차량 (TCU):

엔진 이벤트 전송: 시동 이벤트를 ECARUS로 전송
상태 보고: 커퓨 시간 중 현재 차량 이용 상태 보고

🏢 콜센터:

위반 모니터링: 실시간 위반 모니터링
이력 조회: 위반 이력 조회

주요 기능

앱 기능

정책 설정: 요일/시간대별 커퓨 규칙 설정
정책 조회: 현재 설정된 커퓨 정책 확인
위반 이력: 과거 위반 기록 확인
통계 조회: 위반 패턴 및 통계 분석
예외 설정: 일시적인 커퓨 해제
예외 조회: 설정된 예외 상태 확인
실시간 모니터링: SSE 스트림을 통한 실시간 알림 수신
비상 지원: 일시적 모니터링 강화

콜센터 기능

위반 모니터링: 실시간 위반 모니터링
위반 이력: 위반 이력 조회
통계 분석: 다수 차량의 위반 패턴 분석
차량 제어: 심각한 위반 시 원격 엔진 정지
에스컬레이션 관리: 반복 위반자 관리 및 대응

시퀀스 다이어그램

커퓨 시스템 흐름

플랫폼 연동 고려사항

시간 판별 로직

서버 기반 시간 판별
타임존/DST(일광절약시간제) 처리
차량 현지 시간과 서버 시간 동기화
지역별 시차 고려

차량 제어 방식

소프트 제어: 알림 중심의 제어
하드 제어: 차량 이용 제한 제어 (선택 사항)
주행 중 강제 엔진 정지 금지
다음 시동 제한 또는 속도 제한 적용

운전자 식별

디지털 키 미사용 시 차량 레벨 정책 적용
시간 기반으로만 정책 적용
개별 운전자 식별 불가

API 엔드포인트

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

커퓨 정책

커퓨 정책 조회

bash

curl -X GET "https://api.ecarus.run/api/v1/childcare/vehicles/KMHSH81C7LU123456/curfew/policy" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d"

커퓨 정책 설정

bash

curl -X PUT "https://api.ecarus.run/api/v1/childcare/vehicles/KMHSH81C7LU123456/curfew/policy" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d" \
     -H "Content-Type: application/json" \
     -d '{
           "enabled": true,
           "timezone": "Asia/Seoul",
           "days": ["monday", "wednesday", "friday"],
           "timeWindow": {"start": "21:00", "end": "07:00"},
           "actions": ["notification"]
         }'

커퓨 통계 조회

bash

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

커퓨 모니터링 및 예외 처리

커퓨 위반 이력 조회

bash

curl -X GET "https://api.ecarus.run/api/v1/childcare/vehicles/KMHSH81C7LU123456/curfew/violations?limit=10&offset=0" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d"

커퓨 예외 설정

bash

curl -X POST "https://api.ecarus.run/api/v1/childcare/vehicles/KMHSH81C7LU123456/curfew/exception" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d" \
     -H "Content-Type: application/json" \
     -d '{"reason": "After-school program ended late", "startTime": "2026-03-06T21:00:00Z", "endTime": "2026-03-06T23:00:00Z"}'

커퓨 예외 목록 조회

bash

curl -X GET "https://api.ecarus.run/api/v1/childcare/vehicles/KMHSH81C7LU123456/curfew/exceptions?status=active" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d"

커퓨 실시간 이벤트 수신 (SSE)

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

bash

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

데이터 모델

커퓨 정책 설정

json

{
  "enabled": true,
  "timezone": "Asia/Seoul",
  "days": ["monday", "wednesday", "friday"],
  "timeWindow": {
    "start": "21:00",
    "end": "07:00"
  },
  "actions": ["notification"]
}

커퓨 위반 이벤트

json

{
  "violationId": "vio_001",
  "vin": "KMHSH81C7LU123456",
  "timestamp": "2026-02-10T22:15:00Z",
  "severity": "MEDIUM",
  "location": {
    "latitude": 37.5665,
    "longitude": 126.9780,
    "address": "2 Taepyeong-ro, Jung-gu, Seoul"
  },
  "duration": 45,
  "resolved": false
}

커퓨 정책 응답

json

{
  "enabled": true,
  "timezone": "Asia/Seoul",
  "days": ["monday", "wednesday", "friday"],
  "timeWindow": {
    "start": "21:00",
    "end": "07:00"
  },
  "actions": ["notification"],
  "exceptions": [
    {
      "exceptionId": "exc_001",
      "reason": "After-school program ended late",
      "startTime": "2026-03-06T21:00:00Z",
      "endTime": "2026-03-06T23:00:00Z",
      "status": "active"
    }
  ],
  "statistics": {
    "totalViolations": 5,
    "thisMonth": 2,
    "lastMonth": 3
  },
  "createdAt": "2026-01-10T10:00:00Z",
  "updatedAt": "2026-02-10T22:15:00Z"
}

커퓨 예외 설정

json

{
  "reason": "After-school program ended late",
  "startTime": "2026-03-06T21:00:00Z",
  "endTime": "2026-03-06T23:00:00Z"
}

커퓨 예외 목록

json

{
  "exceptions": [
    {
      "exceptionId": "exc_001",
      "reason": "After-school program ended late",
      "startTime": "2026-03-06T21:00:00Z",
      "endTime": "2026-03-06T23:00:00Z",
      "status": "active",
      "createdAt": "2026-03-06T20:30:00Z"
    },
    {
      "exceptionId": "exc_002",
      "reason": "Family emergency",
      "startTime": "2026-03-05T22:00:00Z",
      "endTime": "2026-03-05T23:30:00Z",
      "status": "expired",
      "createdAt": "2026-03-05T21:45:00Z"
    }
  ],
  "pagination": {
    "total": 2,
    "limit": 10,
    "offset": 0,
    "hasMore": false
  }
}

실시간 위반 이벤트 (SSE)

json

{
  "eventType": "CURFEW_VIOLATION",
  "violationId": "vio_001",
  "vin": "KMHSH81C7LU123456",
  "timestamp": "2026-02-10T22:15:00Z",
  "severity": "MEDIUM",
  "data": {
    "location": {
      "latitude": 37.5665,
      "longitude": 126.9780,
      "address": "2 Taepyeong-ro, Jung-gu, Seoul"
    },
    "duration": 45,
    "message": "Vehicle detected during curfew hours"
  }
}

인증 및 보안

인증 요구사항

사용자 인증 토큰 필요 (JWT/OAuth2)
차량 접근 권한 확인
커퓨 정책 설정 권한
운전자 사전 동의 확인

데이터 보안

모든 API 통신은 HTTPS/TLS 암호화
주행 데이터 전송 시 보안 조치
민감 주행 정보는 서버에만 저장
시간 데이터 암호화 처리

프라이버시 보호

운전자 사전 동의 필수
개인정보 및 위치정보 보호 준수
데이터 수집 목적 명시
데이터 보유 기간 정책 준수

접근 제어

VIN 기반 차량 접근 권한 확인
사용자별 커퓨 정책 접근 관리
위반 이력 접근 제어
예외 설정 권한 관리

예외 처리

시간 관련

시간 동기화 오류: 서버 시간과 차량 시간 동기화 재시도
타임존 오류: 타임존 설정 유효성 검사
DST 변경: 일광절약시간제 자동 처리
시간 판별 실패: UTC 시간으로 폴백

차량 제어 관련

엔진 제어 실패: 차량 제어 명령 재시도
제어 명령 타임아웃: 제어 타임아웃 처리
차량 통신 오류: 차량 통신 재시도
안전 위반: 위험한 제어 명령 금지

정책 관련

정책 설정 오류: 정책 설정 유효성 검사
정책 충돌: 다중 정책 충돌 해결
정책 적용 실패: 정책 재시도 메커니즘
예외 설정 오류: 예외 설정 유효성 검사

네트워크 관련

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

테스트 설정

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

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

배포 고려사항

앱 스토어 등록

주행 모니터링 권한 요청
차량 제어 권한 요청 (해당하는 경우)
커퓨 기능에 대한 명확한 설명
운전자 동의 필요성 설명

법규 준수

미국 지역별 커퓨 관련 규정 준수
운전자 사전 동의 필수
개인정보 및 위치정보 보호 준수
주행 중 강제 엔진 정지 금지

시간 정확성

서버 시간 동기화 최적화
타임존 처리 정확성
DST 변경 자동 처리
시간 판별 신뢰성

차량 제어 안전

안전한 차량 제어 명령 설계
비상 상황 처리
제어 명령 유효성 검사
안전 프로토콜 준수

커퓨(심야 운행 제한) API 개발자 가이드 ​

서비스 개요 ​

서비스 특징 ​

법적 요구사항 ​

주요 시나리오 ​

시나리오 1: 커퓨 정책 설정 ​

주요 기능 ​

앱 기능 ​

콜센터 기능 ​

시퀀스 다이어그램 ​

커퓨 시스템 흐름 ​

플랫폼 연동 고려사항 ​

시간 판별 로직 ​

차량 제어 방식 ​

운전자 식별 ​

권한 관리 ​

API 엔드포인트 ​

커퓨 정책 ​

커퓨 정책 조회 ​

커퓨 정책 설정 ​

커퓨 통계 조회 ​

커퓨 모니터링 및 예외 처리 ​

커퓨 위반 이력 조회 ​

커퓨 예외 설정 ​

커퓨 예외 목록 조회 ​

커퓨 실시간 이벤트 수신 (SSE) ​

데이터 모델 ​

커퓨 정책 설정 ​

커퓨 위반 이벤트 ​

커퓨 정책 응답 ​

커퓨 예외 설정 ​

커퓨 예외 목록 ​

실시간 위반 이벤트 (SSE) ​

인증 및 보안 ​

인증 요구사항 ​

데이터 보안 ​

프라이버시 보호 ​

접근 제어 ​

예외 처리 ​

시간 관련 ​

차량 제어 관련 ​

정책 관련 ​

네트워크 관련 ​

테스트 설정 ​

배포 고려사항 ​

앱 스토어 등록 ​

법규 준수 ​

시간 정확성 ​

차량 제어 안전 ​

커퓨(심야 운행 제한) API 개발자 가이드

서비스 개요

서비스 특징

법적 요구사항

주요 시나리오

시나리오 1: 커퓨 정책 설정

주요 기능

앱 기능

콜센터 기능

시퀀스 다이어그램

커퓨 시스템 흐름

플랫폼 연동 고려사항

시간 판별 로직

차량 제어 방식

운전자 식별

권한 관리

API 엔드포인트

커퓨 정책

커퓨 정책 조회

커퓨 정책 설정

커퓨 통계 조회

커퓨 모니터링 및 예외 처리

커퓨 위반 이력 조회

커퓨 예외 설정

커퓨 예외 목록 조회

커퓨 실시간 이벤트 수신 (SSE)

데이터 모델

커퓨 정책 설정

커퓨 위반 이벤트

커퓨 정책 응답

커퓨 예외 설정

커퓨 예외 목록

실시간 위반 이벤트 (SSE)

인증 및 보안

인증 요구사항

데이터 보안

프라이버시 보호

접근 제어

예외 처리

시간 관련

차량 제어 관련

정책 관련

네트워크 관련

테스트 설정

배포 고려사항

앱 스토어 등록

법규 준수

시간 정확성

차량 제어 안전