Remote Door Control API Developer Guide

Service Overview

Remote Door Control is a telematics service that allows users to remotely lock or unlock vehicle doors through a mobile application.

Service Features

Remote door lock/unlock functionality
Response to lost keys or internal lock situations
Mobile-based vehicle access control provision
Asynchronous Command-based architecture
Real-time status updates and notifications

Legal Requirements

Strong security policy required for vehicle access control functionality
Compliance with personal information protection laws
End-to-End authentication mandatory
Command execution Audit Log recording

Key Scenarios

Scenario 1: Remote Door Control Request and Execution

API Flow by Entity:

📱 App (User):

Door Unlock Request: Request after Correlation ID generation
Command Reception: Receive 202 Accepted response
Push Notification: Receive door control result push notification
UI Update: Update UI if response within 30 seconds, ignore if timeout

🚗 Vehicle (TCU):

Command Reception: Receive door control command from ECARUS
Door Control Execution: Control lock/unlock actuators
Result Publication: Publish success/failure results to ECARUS

🏢 Call Center:

Proxy Request: Proxy request after Correlation ID generation
Command Reception: Receive 202 Accepted response
WebSocket Event: Real-time reception of door control results

Scenario 2: Door Control Failure and Exception Handling

API Flow by Entity:

📱 App (User):

Command Request: Door lock/unlock command request
Failure Notification: Receive failure reasons via push notification
Status Check: Check current door status
Command Cancellation: Cancel executing command

🚗 Vehicle (TCU):

Safety Verification: Verify door control execution conditions
Failure Processing: Generate failure reasons when execution impossible
Result Publication: Publish failure results to ECARUS

🏢 Call Center:

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

Scenario 3: Door Status Monitoring and Settings Management

API Flow by Entity:

📱 App (User):

Status Query: Real-time door status check
Settings Query: Check door settings
Settings Update: Change settings like auto-lock
Real-time Monitoring: Monitor status changes via SSE stream

🚗 Vehicle (TCU):

Status Collection: Real-time collection of door, lock, window status
Status Transmission: Transmit collected status data to ECARUS
Settings Application: Execute functions like auto-lock based on user settings

🏢 Call Center:

Status Monitoring: Real-time vehicle status check
Settings Support: Support user settings and Update environment settings
Diagnostics Management: Perform regular system diagnostics

Key Features

📱 Features to Implement in App

4. Notification and UI Functions

Push Notifications: Receive door control result push notifications
Timer Management: Response processing based on 30-second timeout
Correlation ID: Generate unique ID for request tracking

🏢 Features to Implement in Call Center

1. Proxy Control Function

Proxy Unlock: Unlock door on behalf of customer
Proxy Lock: Lock door on behalf of customer

2. History Management Function

History Query: Query door control history
Failure Analysis: Analyze failure causes and report

3. Diagnostics and Monitoring Function

Diagnostics Query: Query door system diagnostics
Status Check: Check vehicle door status
WebSocket Connection: Real-time event reception

4. Customer Support Function

Settings Support: Support user settings and Update environment settings
Problem Solving: Support problem solving based on system diagnostics
Security Monitoring: Monitor abnormal access patterns

🚗 Functions Processed by Vehicle (TCU)

1. Command Execution Function

Door Control: Control lock/unlock actuators
Safety Verification: Verify execution conditions based on vehicle status
Result Publication: Publish execution results via MQTT

2. Status Management Function

Status Collection: Collect door, lock, window status
Status Transmission: Transmit real-time status data
Settings Application: Apply settings like auto-lock

Sequence Diagram

Remote Door Control System Flow

Remote Door Control

API Endpoints

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

Door Unlock

bash

curl -X POST "https://api.ecarus.run/api/v1/remotecontrol/vehicles/KMHSH81C7LU123456/door/unlock" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d" \
     -H "Content-Type: application/json" \
     -d '{"targetDoors": ["all"], "unlockMode": "NORMAL"}'

Door Lock

bash

curl -X POST "https://api.ecarus.run/api/v1/remotecontrol/vehicles/KMHSH81C7LU123456/door/lock" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d" \
     -H "Content-Type: application/json" \
     -d '{"targetDoors": ["all"], "lockMode": "SECURE"}'

Door Status Query

bash

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

Door Control Cancellation

bash

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

Door Control History Query

bash

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

Door Control Settings Query

bash

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

Door Control Settings Update

bash

curl -X PUT "https://api.ecarus.run/api/v1/remotecontrol/vehicles/KMHSH81C7LU123456/door/config" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d" \
     -H "Content-Type: application/json" \
     -d '{"autoLockEnabled": true, "autoLockDelay": 30, "unlockMode": "DRIVER_ONLY", "childLockEnabled": false}'

Door Control Diagnostics Query

bash

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

Door Status Real-time Update Stream (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/door/updates/stream" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d" \
     -H "Accept: text/event-stream"

Data Models

Door Unlock Request

json

{
  "targetDoors": ["all"],
  "unlockMode": "NORMAL"
}

targetDoors: all, driver, passenger, rearLeft, rearRight, trunk
unlockMode: NORMAL, EMERGENCY

Door Lock Request

json

{
  "targetDoors": ["all"],
  "lockMode": "SECURE"
}

targetDoors: all, driver, passenger, rearLeft, rearRight, trunk
lockMode: SECURE, NORMAL

Door Control Response

json

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

status: PENDING, IN_PROGRESS, SUCCESS, FAILED, TIMEOUT
estimatedDuration: Estimated execution time (seconds)

Door Status Response

json

{
  "vin": "KMHSH81C7LU123456",
  "doors": {
    "driver": {
      "locked": true,
      "open": false,
      "windowOpen": false,
      "childLock": false
    },
    "passenger": {
      "locked": true,
      "open": false,
      "windowOpen": false
    },
    "rearLeft": {
      "locked": true,
      "open": false,
      "windowOpen": false,
      "childLock": true
    },
    "rearRight": {
      "locked": true,
      "open": false,
      "windowOpen": false,
      "childLock": true
    },
    "trunk": {
      "locked": true,
      "open": false
    },
    "hood": {
      "locked": true,
      "open": false
    }
  },
  "ignitionStatus": "OFF",
  "vehicleSpeed": 0,
  "gearPosition": "P",
  "timestamp": "2026-01-12T14:30:00Z"
}

Door Cancellation Request

json

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

reason: User cancellation, Emergency stop, System error, Timeout
force: Force cancellation flag (default: false)

Door History Request (Query Parameters)

period: 24h
limit: 50
offset: 0
action: UNLOCK

period: 1h, 24h, 7d, 30d
action: UNLOCK, LOCK, CANCEL, STATUS_CHECK

Door History Response

json

{
  "vin": "KMHSH81C7LU123456",
  "history": [
    {
      "commandId": "cmd-uuid-12345",
      "action": "UNLOCK",
      "targetDoors": ["all"],
      "status": "SUCCESS",
      "timestamp": "2026-01-12T14:30:00Z",
      "executionTime": 2.5,
      "userId": "user-123",
      "source": "MOBILE_APP",
      "failureReason": null
    }
  ],
  "total": 1,
  "hasMore": false
}

status: SUCCESS, FAILED, TIMEOUT, CANCELLED
source: MOBILE_APP, CALL_CENTER, WEB, VOICE_ASSISTANT

Door Settings Response

json

{
  "vin": "KMHSH81C7LU123456",
  "autoLockEnabled": true,
  "autoLockDelay": 30,
  "unlockMode": "DRIVER_ONLY",
  "childLockEnabled": false,
  "speedBasedLockEnabled": true,
  "speedLockThreshold": 15,
  "parkingAutoUnlock": true,
  "updatedTime": "2026-01-12T10:00:00Z"
}

unlockMode: ALL, DRIVER_ONLY, SEQUENCE
speedLockThreshold: Speed-based lock threshold (km/h)

Door Diagnostics Response

json

{
  "vin": "KMHSH81C7LU123456",
  "systemStatus": "NORMAL",
  "components": [
    {
      "id": "driver_actuator_01",
      "name": "Driver Door Actuator",
      "status": "ACTIVE",
      "health": 98,
      "lastMaintenance": "2025-06-15T00:00:00Z",
      "errorCodes": []
    },
    {
      "id": "lock_module_01",
      "name": "Door Lock Module",
      "status": "ACTIVE",
      "health": 95,
      "lastMaintenance": "2025-06-15T00:00:00Z",
      "errorCodes": []
    }
  ],
  "alerts": [],
  "lastCheck": "2026-01-12T14:30:00Z"
}

status: ACTIVE, INACTIVE, ERROR, MAINTENANCE_REQUIRED
health: 0-100 score

Door Status Update (SSE)

json

{
  "type": "DOOR_STATUS_UPDATE",
  "vin": "KMHSH81C7LU123456",
  "timestamp": "2026-01-12T14:30:18Z",
  "data": {
    "doorId": "driver",
    "locked": true,
    "open": false,
    "windowOpen": false,
    "changeType": "LOCKED",
    "previousState": {
      "locked": false,
      "open": false
    }
  }
}

type: DOOR_STATUS_UPDATE, COMMAND_STATUS_UPDATE, SYSTEM_ALERT
changeType: LOCKED, UNLOCKED, OPENED, CLOSED, WINDOW_OPENED, WINDOW_CLOSED

Security and Privacy

Authentication and Authorization

User authentication token required (JWT/OAuth2)
Vehicle access permission verification
Door control permission verification (Owner/Shared User/Digital Key)

Data Security

All API communication encrypted with HTTPS/TLS
Command Signing to prevent command forgery
mTLS-based communication security
End-to-End encryption

Privacy Protection

Explicit consent for vehicle access history collection
Specify purpose of location information collection
Compliance with command execution history retention period policy

Access Control

VIN-based vehicle access permission verification
Multi-factor authentication requirement
Command Rate Limit application
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
Door Open State: Clearly guide lock command failure
Engine On: Guide some control function limitations

Authentication Failure: Request re-authentication, guide security enhancement
No Permission: Clearly display lack of permission reasons
Suspicious Access: Account lock and notification

Partial Success: Detailed guidance when only some doors controlled
Failure: Clearly display failure 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.

Deployment Considerations

App Store Registration

Request vehicle control permissions
Request biometric authentication permissions
Clear description of location information collection

Legal Regulation Compliance

Compliance with personal information protection laws
Check vehicle access control related regulations
Compliance with security authentication related laws

Vehicle Compatibility

Support various vehicle models
Consider OEM-specific door control method differences
Digital Key standard compatibility

Remote Door Control API Developer Guide ​

Service Overview ​

Service Features ​

Legal Requirements ​

Key Scenarios ​

Scenario 1: Remote Door Control Request and Execution ​

Scenario 2: Door Control Failure and Exception Handling ​

Scenario 3: Door Status Monitoring and Settings Management ​

Key Features ​

📱 Features to Implement in App ​

1. Remote Door Control Function ​

2. Status Monitoring Function ​

3. Settings Management Function ​

4. Notification and UI Functions ​

🏢 Features to Implement in Call Center ​

1. Proxy Control Function ​

2. History Management Function ​

3. Diagnostics and Monitoring Function ​

4. Customer Support Function ​

🚗 Functions Processed by Vehicle (TCU) ​

1. Command Execution Function ​

2. Status Management Function ​

Sequence Diagram ​

Remote Door Control System Flow ​

API Endpoints ​

Door Unlock ​

Door Lock ​

Door Status Query ​

Door Control Cancellation ​

Door Control History Query ​

Door Control Settings Query ​

Door Control Settings Update ​

Door Control Diagnostics Query ​

Door Status Real-time Update Stream (SSE) ​

Data Models ​

Door Unlock Request ​

Door Lock Request ​

Door Control Response ​

Door Status Response ​

Door Cancellation Request ​

Door History Request (Query Parameters) ​

Door History Response ​

Door Settings Response ​

Door Diagnostics Response ​

Door Status Update (SSE) ​

Security and Privacy ​

Authentication and Authorization ​

Data Security ​

Privacy Protection ​

Access Control ​

Exception Handling ​

Network Related ​

Vehicle Status Related ​

Security Related ​

Command Execution Related ​

Test Setup ​

Deployment Considerations ​

App Store Registration ​

Legal Regulation Compliance ​

Vehicle Compatibility ​

Remote Door Control API Developer Guide

Service Overview

Service Features

Legal Requirements

Key Scenarios

Scenario 1: Remote Door Control Request and Execution

Scenario 2: Door Control Failure and Exception Handling

Scenario 3: Door Status Monitoring and Settings Management

Key Features

📱 Features to Implement in App

1. Remote Door Control Function

2. Status Monitoring Function

3. Settings Management Function

4. Notification and UI Functions

🏢 Features to Implement in Call Center

1. Proxy Control Function

2. History Management Function

3. Diagnostics and Monitoring Function

4. Customer Support Function

🚗 Functions Processed by Vehicle (TCU)

1. Command Execution Function

2. Status Management Function

Sequence Diagram

Remote Door Control System Flow

API Endpoints

Door Unlock

Door Lock

Door Status Query

Door Control Cancellation

Door Control History Query

Door Control Settings Query

Door Control Settings Update

Door Control Diagnostics Query

Door Status Real-time Update Stream (SSE)

Data Models

Door Unlock Request

Door Lock Request

Door Control Response

Door Status Response

Door Cancellation Request

Door History Request (Query Parameters)

Door History Response

Door Settings Response

Door Diagnostics Response

Door Status Update (SSE)

Security and Privacy

Authentication and Authorization

Data Security

Privacy Protection

Access Control

Exception Handling

Network Related

Vehicle Status Related

Security Related

Command Execution Related

Test Setup

Deployment Considerations

App Store Registration

Legal Regulation Compliance

Vehicle Compatibility