Remote Sunroof Control API Developer Guide

Service Overview

Remote Sunroof Control is a telematics service that allows users to remotely open or close the vehicle's sunroof through a mobile application.

Service Features

Remote sunroof open/close control
Various opening modes (full open, tilt ventilation)
Anti-pinch safety functionality
Environment condition-based safety verification
Real-time status monitoring

Legal Requirements

Compliance with vehicle Body Domain control related safety regulations
Mandatory application of Anti-pinch safety functionality
Compliance with personal information protection laws
Compliance with OEM policy-based safety rules

Key Scenarios

Scenario 1: Remote Sunroof Control Request and Execution

API Flow by Entity:

📱 App (User):

Sunroof Control: Request remote sunroof open/close control
Command Reception: Receive 202 Accepted response
Push Notification: Receive sunroof control result push notification
UI Update: Display control results on screen

🚗 Vehicle (TCU):

Command Reception: Receive sunroof control command from ECARUS
Safety Verification: Check safety conditions like engine status, rain detection
Motor Drive: Execute control by driving sunroof motor
Result Publication: Publish success/failure results to ECARUS

🏢 Call Center:

Proxy Control: Control sunroof on behalf of customer
Status Check: Check sunroof status
Result Reception: Receive sunroof control results

Scenario 2: Sunroof Control Failure and Exception Handling

API Flow by Entity:

📱 App (User):

Command Request: Sunroof control command request
Failure Notification: Receive failure reasons via push notification
Status Check: Check current sunroof status
Command Cancellation: Cancel executing command

🚗 Vehicle (TCU):

Safety Verification: Check rain detection or engine status
Failure Processing: Process failure when safety conditions violated
Result Publication: Publish failure results and error codes
Status Report: Report current sunroof status

🏢 Call Center:

History Query: Query failure history
Diagnostics Check: Check system diagnostics
Customer Support: Analyze failure causes and guide customers

Scenario 3: Sunroof Status Monitoring and Settings Management

API Flow by Entity:

📱 App (User):

Status Query: Query sunroof status
Settings Query: Query sunroof settings
Settings Update: Update sunroof settings
Real-time Monitoring: Real-time status monitoring via SSE stream

🚗 Vehicle (TCU):

Status Collection: Real-time collection of sunroof status data
Settings Application: Automatic application of sunroof settings
Status Transmission: Transmit status data to server
Event Publication: Publish status change events

🏢 Call Center:

Status Monitoring: Real-time sunroof status check
Settings Management: Manage customer settings and Update sunroof settings
Diagnostics Management: Manage system diagnostics
History Management: Manage control history

Scenario 4: Sunroof Diagnostics and History Management

API Flow by Entity:

📱 App (User):

Diagnostics Query: Query sunroof system diagnostics
History Query: Query sunroof control history
Settings Check: Check current settings
Status Check: Check latest status

🚗 Vehicle (TCU):

Diagnostics Execution: Diagnose sunroof related component status
Status Report: Report component status to server
History Recording: Detailed recording of control history
Settings Synchronization: Synchronize setting changes

🏢 Call Center:

Diagnostics Management: Automatic system diagnostics management
History Management: Automatic control history management
Settings Support: Support customer setting changes and Update sunroof settings
Problem Solving: Problem solving based on diagnostics results

Key Features

📱 Features to Implement in App

1. Remote Sunroof Control Function

Sunroof Control: Request remote sunroof open/close control
Command Cancellation: Request cancellation of executing command
Status Query: Immediate sunroof status query

2. Settings Management Function

Settings Query: Query sunroof settings
Settings Update: Update sunroof settings
Environment Settings: Manage safety settings like rain detection, temperature protection

3. Real-time Monitoring Function

Real-time Updates: Real-time status monitoring via SSE stream
Event Processing: Real-time processing of sunroof status change events
Status Display: Real-time display of sunroof open/close status

4. Notification and UI Functions

Push Notifications: Receive sunroof control result push notifications
Error Guidance: User-friendly error messages on failure
Status Visualization: Visual representation of sunroof status

🏢 Features to Implement in Call Center

1. Proxy Sunroof Control Function

Proxy Control: Control sunroof on behalf of customer
Command Cancellation: Process command cancellation
Status Check: Check sunroof status

2. History and Diagnostics Management Function

History Query: Query sunroof control history
Diagnostics Query: Query sunroof system diagnostics
Statistics Generation: Generate sunroof control usage statistics

3. Settings Management Function

Settings Query: Check customer sunroof settings
Settings Update: Support customer setting changes
Settings Synchronization: Automatic settings synchronization with vehicle

4. Customer Support Function

Problem Solving: Analyze sunroof control failure causes
Settings Support: Support customer sunroof settings
Security Monitoring: Monitor abnormal access patterns

🚗 Functions Processed by Vehicle (TCU)

1. Sunroof Control Function

Command Reception: Receive sunroof control commands
Safety Verification: Check safety conditions like engine status, rain detection
Motor Drive: Execute control by driving sunroof motor
Result Publication: Publish control results

2. Status Management Function

Status Collection: Real-time collection of sunroof status data
Event Publication: Publish status change events
Status Report: Report current sunroof status

3. Safety Function

Rain Detection: Automatic close when rain detected
Anti-pinch: Automatic stop when pinch detected
Temperature Protection: Automatic limitation when overheated

Sequence Diagram

Remote Sunroof Control System Flow

Remote Sunroof Control

API Endpoints

Refer to the Common API Specifications for headers, response codes, and error formats.

Sunroof Control

bash

curl -X POST "https://api.ecarus.run/api/v1/remotecontrol/vehicles/KMHSH81C7LU123456/sunroof/control" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d" \
     -H "Content-Type: application/json" \
     -d '{"action": "OPEN", "position": 100}'

Sunroof Status Query

bash

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

Sunroof Control Cancellation

bash

curl -X POST "https://api.ecarus.run/api/v1/remotecontrol/vehicles/KMHSH81C7LU123456/sunroof/cancel" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d" \
     -H "Content-Type: application/json" \
     -d '{"correlationId": "uuid-12345678", "reason": "User cancellation", "force": false}'

Sunroof Control History Query

bash

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

Sunroof Control Settings Query

bash

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

Sunroof Control Settings Update

bash

curl -X PUT "https://api.ecarus.run/api/v1/remotecontrol/vehicles/KMHSH81C7LU123456/sunroof/config" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d" \
     -H "Content-Type: application/json" \
     -d '{"sunroof": {"remoteControlEnabled": true, "autoCloseEnabled": true, "autoCloseDelay": 300, "tiltEnabled": true}, "safety": {"rainProtectionEnabled": true, "temperatureProtectionEnabled": true, "rainSensitivity": "HIGH"}}'

Sunroof Diagnostics Information Query

bash

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

Sunroof Control Information Real-time Update Reception (SSE)

Note: Recommended to access via browser or use a dedicated SSE client

bash

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

Data Models

Sunroof Control Request

json

{
  "action": "OPEN",
  "position": 100
}

action: OPEN, CLOSE, STOP, TILT_UP, TILT_DOWN
position: 0-100 (0=fully closed, 100=fully open)

Sunroof Control Response

json

{
  "commandId": "cmd-uuid-12345",
  "vin": "KMHSH81C7LU123456",
  "status": "PENDING",
  "message": "Sunroof control command received",
  "estimatedDuration": 15,
  "timestamp": "2026-01-12T14:30:00Z"
}

status: PENDING, PROCESSING, SUCCESS, FAILED, CANCELLED

Sunroof Status Response

json

{
  "vin": "KMHSH81C7LU123456",
  "isOpen": true,
  "position": 85,
  "mode": "FULL",
  "isMoving": false,
  "tiltAngle": 0,
  "obstructionDetected": false,
  "lastAction": "OPEN",
  "timestamp": "2026-01-12T14:30:00Z"
}

mode: CLOSED, PARTIAL, FULL, TILT_UP, TILT_DOWN

Sunroof Cancellation Request

json

{
  "correlationId": "uuid-12345678",
  "reason": "User cancellation",
  "force": false
}

reason: User cancellation, Safety stop, System error, Emergency stop
force: Force cancellation flag (true means immediate stop)

Sunroof Control History Request (Query Parameters)

vin: KMHSH81C7LU123456
period: 24h
limit: 50
offset: 0

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

Sunroof Control History Response

json

{
  "vin": "KMHSH81C7LU123456",
  "history": [
    {
      "commandId": "cmd-uuid-12345",
      "action": "OPEN",
      "position": 100,
      "timestamp": "2026-01-12T14:30:00Z",
      "status": "SUCCESS",
      "executionTime": 15,
      "userId": "user-123",
      "source": "APP"
    }
  ],
  "total": 1,
  "hasMore": false
}

source: APP, CALL_CENTER, SYSTEM
status: PENDING, PROCESSING, SUCCESS, FAILED, CANCELLED

Sunroof Control Settings Response

json

{
  "vin": "KMHSH81C7LU123456",
  "sunroof": {
    "remoteControlEnabled": true,
    "autoCloseEnabled": true,
    "autoCloseDelay": 300,
    "tiltEnabled": true,
    "maxOpenPosition": 100,
    "speedControl": "NORMAL"
  },
  "safety": {
    "rainProtectionEnabled": true,
    "temperatureProtectionEnabled": true,
    "rainSensitivity": "HIGH",
    "obstacleDetectionEnabled": true,
    "maxOperatingTemperature": 60
  },
  "updatedTime": "2026-01-12T10:00:00Z"
}

rainSensitivity: LOW, MEDIUM, HIGH
speedControl: SLOW, NORMAL, FAST
maxOperatingTemperature: Maximum operating temperature (°C)

Sunroof Diagnostics Information Response

json

{
  "vin": "KMHSH81C7LU123456",
  "systemStatus": "NORMAL",
  "components": [
    {
      "name": "Sunroof Motor",
      "status": "ACTIVE",
      "health": 98,
      "lastMaintenance": "2025-06-15T00:00:00Z",
      "operatingHours": 1250
    },
    {
      "name": "Rain Sensor",
      "status": "ACTIVE",
      "health": 95,
      "lastCalibration": "2025-12-01T00:00:00Z",
      "sensitivityLevel": "HIGH"
    },
    {
      "name": "Obstruction Sensor",
      "status": "ACTIVE",
      "health": 100,
      "lastTest": "2026-01-10T14:30:00Z"
    }
  ],
  "alerts": [],
  "lastCheck": "2026-01-12T14:30:00Z"
}

systemStatus: NORMAL, WARNING, ERROR, OFFLINE
component.status: ACTIVE, INACTIVE, ERROR, MAINTENANCE_REQUIRED

Sunroof Control Status Update (SSE)

json

{
  "type": "SUNROOF_STATUS_UPDATE",
  "vin": "KMHSH81C7LU123456",
  "timestamp": "2026-01-12T14:30:15Z",
  "data": {
    "position": 50,
    "mode": "PARTIAL",
    "isMoving": false,
    "isOpen": true,
    "tiltAngle": 0,
    "changeType": "POSITION_UPDATE"
  }
}

type: SUNROOF_STATUS_UPDATE, SUNROOF_COMMAND_RESULT, SUNROOF_SAFETY_ALERT
changeType: POSITION_UPDATE, MODE_CHANGE, SAFETY_STOP, OBSTRUCTION_DETECTED, RAIN_DETECTED

Security and Privacy

Authentication and Authorization

User authentication token required (JWT/OAuth2)
Vehicle access permission verification
Sunroof control permission verification

Data Security

All API communication encrypted with HTTPS/TLS
Command Signing to prevent command forgery
Priority processing of safety-related data

Privacy Protection

Explicit consent for vehicle status information collection
Specify purpose of environment sensor data collection
Compliance with command execution history retention period policy

Access Control

VIN-based vehicle access permission verification
Multi-factor authentication requirement
Priority processing of safety-related functions
Abnormal access pattern detection

Exception Handling

Connection Failure: Support offline mode, cache last status
Slow Response: Loading indicator, timeout handling
Server Down: Display error message, suggest retry

Vehicle Offline: Notify command transmission failure, queue processing
Safety Conditions Not Met: Reject command and clearly guide reasons
Environment Limitations: Notify function limitations when rain detected

Anti-pinch Trigger: Immediate stop and safety notification
Rain Detection: Automatic close and notification
Obstruction Detection: Immediate stop and user notification

Partial Success: Detailed guidance when only some functions operate
Safety Stop: Clearly display safety reasons
Timeout: Notify Command TTL expiration

Test Setup

Base URL: https://api.ecarus.run/api/v1/remotecontrol
Authentication Token: sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d
Sample VIN: KMHSH81C7LU123456

Use Swagger UI for interactive API testing. Jennifer

Deployment Considerations

App Store Registration

Request vehicle control permissions
Request biometric authentication permissions
Request environment sensor access permissions

Legal Regulation Compliance

Compliance with personal information protection laws
Check vehicle Body Domain control related regulations
Compliance with Anti-pinch safety functionality related laws

Vehicle Compatibility

Support various vehicle models
Consider OEM-specific sunroof control method differences
Reflect country-specific safety regulation differences
Function limitations based on sunroof presence

Remote Sunroof Control API Developer Guide ​

Service Overview ​

Service Features ​

Legal Requirements ​

Key Scenarios ​

Scenario 1: Remote Sunroof Control Request and Execution ​

Scenario 2: Sunroof Control Failure and Exception Handling ​

Scenario 3: Sunroof Status Monitoring and Settings Management ​

Scenario 4: Sunroof Diagnostics and History Management ​

Key Features ​

📱 Features to Implement in App ​

1. Remote Sunroof Control Function ​

2. Settings Management Function ​

3. Real-time Monitoring Function ​

4. Notification and UI Functions ​

🏢 Features to Implement in Call Center ​

1. Proxy Sunroof Control Function ​

2. History and Diagnostics Management Function ​

3. Settings Management Function ​

4. Customer Support Function ​

🚗 Functions Processed by Vehicle (TCU) ​

1. Sunroof Control Function ​

2. Status Management Function ​

3. Safety Function ​

Sequence Diagram ​

Remote Sunroof Control System Flow ​

API Endpoints ​

Sunroof Control ​

Sunroof Status Query ​

Sunroof Control Cancellation ​

Sunroof Control History Query ​

Sunroof Control Settings Query ​

Sunroof Control Settings Update ​

Sunroof Diagnostics Information Query ​

Sunroof Control Information Real-time Update Reception (SSE) ​

Data Models ​

Sunroof Control Request ​

Sunroof Control Response ​

Sunroof Status Response ​

Sunroof Cancellation Request ​

Sunroof Control History Request (Query Parameters) ​

Sunroof Control History Response ​

Sunroof Control Settings Response ​

Sunroof Diagnostics Information Response ​

Sunroof Control Status Update (SSE) ​

Security and Privacy ​

Authentication and Authorization ​

Data Security ​

Privacy Protection ​

Access Control ​

Exception Handling ​

Network Related ​

Vehicle Status Related ​

Safety Related ​

Command Execution Related ​

Test Setup ​

Deployment Considerations ​

App Store Registration ​

Legal Regulation Compliance ​

Vehicle Compatibility ​

Remote Sunroof Control API Developer Guide

Service Overview

Service Features

Legal Requirements

Key Scenarios

Scenario 1: Remote Sunroof Control Request and Execution

Scenario 2: Sunroof Control Failure and Exception Handling

Scenario 3: Sunroof Status Monitoring and Settings Management

Scenario 4: Sunroof Diagnostics and History Management

Key Features

📱 Features to Implement in App

1. Remote Sunroof Control Function

2. Settings Management Function

3. Real-time Monitoring Function

4. Notification and UI Functions

🏢 Features to Implement in Call Center

1. Proxy Sunroof Control Function

2. History and Diagnostics Management Function

3. Settings Management Function

4. Customer Support Function

🚗 Functions Processed by Vehicle (TCU)

1. Sunroof Control Function

2. Status Management Function

3. Safety Function

Sequence Diagram

Remote Sunroof Control System Flow

API Endpoints

Sunroof Control

Sunroof Status Query

Sunroof Control Cancellation

Sunroof Control History Query

Sunroof Control Settings Query

Sunroof Control Settings Update

Sunroof Diagnostics Information Query

Sunroof Control Information Real-time Update Reception (SSE)

Data Models

Sunroof Control Request

Sunroof Control Response

Sunroof Status Response

Sunroof Cancellation Request

Sunroof Control History Request (Query Parameters)

Sunroof Control History Response

Sunroof Control Settings Response

Sunroof Diagnostics Information Response

Sunroof Control Status Update (SSE)

Security and Privacy

Authentication and Authorization

Data Security

Privacy Protection

Access Control

Exception Handling

Network Related

Vehicle Status Related

Safety Related

Command Execution Related

Test Setup

Deployment Considerations

App Store Registration

Legal Regulation Compliance

Vehicle Compatibility