Remote Trunk Control API Developer Guide

Service Overview

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

Service Features

Remote trunk open/close control
Convenience for item delivery and pickup
Support for smart delivery and valet services
Enhanced security policy application
Command and Event-based status differentiation

Legal Requirements

Strong security policy required for vehicle security related features
Compliance with personal information protection laws
Mandatory Command Audit Log recording
Location-based restriction (Geo-fencing) application

Key Scenarios

Scenario 1: Remote Trunk Control Request and Execution

API Flow by Entity:

📱 App (User):

Trunk Open: Request remote trunk open control
Command Reception: Receive 202 Accepted response
Push Notification: Receive trunk control result push notification
UI Update: Display control results on screen

🚗 Vehicle (TCU):

Command Reception: Receive trunk control command from ECARUS
Safety Verification: Check gear status (P-Range), speed (0km/h), obstacle detection
Motor Drive: Open trunk by driving tailgate motor
Result Publication: Publish success/failure results to ECARUS

🏢 Call Center:

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

Scenario 2: Trunk Control Failure and Safety Shutdown Processing

API Flow by Entity:

📱 App (User):

Command Request: Trunk open command request
Failure Notification: Receive failure reasons via push notification
Status Check: Check current trunk status
Command Cancellation: Cancel executing command

🚗 Vehicle (TCU):

Safety Verification: Check during driving or rear obstacle detection
Failure Processing: Process failure when safety conditions violated
Result Publication: Publish failure results and error codes
Safety Shutdown: Automatic shutdown in abnormal state

🏢 Call Center:

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

Scenario 3: Trunk Lock and Status Monitoring

API Flow by Entity:

📱 App (User):

Trunk Lock: Request remote trunk lock control
Status Query: Query trunk status
Specification Check: Query trunk specifications
Settings Management: Manage trunk settings and Update trunk settings

🚗 Vehicle (TCU):

Lock Command Reception: Receive trunk lock command
Lock Motor Drive: Drive trunk lock motor
Status Transmission: Transmit lock status to server
Event Publication: Publish status change events

🏢 Call Center:

Status Monitoring: Real-time trunk status check
Specification Management: Manage trunk specifications
Settings Management: Manage customer settings and Update trunk settings
History Management: Manage control history

Scenario 4: Trunk Diagnostics and Settings Management

API Flow by Entity:

📱 App (User):

Diagnostics Query: Query trunk system diagnostics
Specification Query: Query trunk specifications
Settings Query: Query trunk settings
Settings Update: Update trunk settings

🚗 Vehicle (TCU):

Diagnostics Execution: Diagnose trunk related component status
Specification Report: Report trunk specification information to server
Settings Application: Automatic application of trunk settings
Status Report: Report current trunk status

🏢 Call Center:

Diagnostics Management: Automatic system diagnostics management
Specification Management: Automatic trunk specification management
Settings Support: Support customer trunk setting changes and Update trunk settings
Problem Solving: Problem solving based on diagnostics results

Key Features

📱 Features to Implement in App

1. Remote Trunk Control Function

Trunk Open: Request remote trunk open control
Trunk Lock: Request remote trunk lock control
Command Cancellation: Request cancellation of executing command
Status Query: Immediate trunk status query

2. Settings Management Function

Settings Query: Query trunk settings
Settings Update: Update trunk settings
Specification Query: Query trunk specifications

3. Real-time Monitoring Function

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

4. Notification and UI Functions

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

🏢 Features to Implement in Call Center

1. Proxy Trunk Control Function

Proxy Open: Open trunk on behalf of customer
Proxy Lock: Lock trunk on behalf of customer
Command Cancellation: Process command cancellation
Status Check: Check trunk status

2. History and Diagnostics Management Function

History Query: Query trunk control history
Diagnostics Query: Query trunk system diagnostics
Specification Query: Query trunk specifications
Statistics Generation: Generate trunk control usage statistics

3. Settings Management Function

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

4. Customer Support Function

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

🚗 Functions Processed by Vehicle (TCU)

1. Trunk Control Function

Command Reception: Receive trunk control commands
Safety Verification: Check gear status, speed, obstacle detection
Motor Drive: Execute control by driving tailgate/lock motor
Result Publication: Publish control results

2. Status Management Function

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

3. Safety Function

Obstacle Detection: Detect obstacles with rear ultrasonic sensors
Anti-pinch: Automatic stop when pinch detected
Safety Shutdown: Automatic shutdown in dangerous state

Sequence Diagram

Remote Trunk Control System Flow

Remote Trunk Control

API Endpoints

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

Trunk Open

bash

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

Trunk Lock

bash

curl -X POST "https://api.ecarus.run/api/v1/remotecontrol/vehicles/KMHSH81C7LU123456/trunk/lock" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d" \
     -H "Content-Type: application/json" \
     -d '{"action": "LOCK"}'

Trunk Status Query

bash

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

Trunk Control Cancellation

bash

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

Trunk Control History Query

bash

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

Trunk Specification Query

bash

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

Trunk Settings Query

bash

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

Trunk Settings Update

bash

curl -X PUT "https://api.ecarus.run/api/v1/remotecontrol/vehicles/KMHSH81C7LU123456/trunk/config" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d" \
     -H "Content-Type: application/json" \
     -d '{"trunk": {"remoteControlEnabled": true, "antiPinchSensitivity": "HIGH", "openSpeed": "SLOW"}, "safety": {"obstacleDetectionEnabled": true, "minSafeDistance": 75.0, "speedLimitEnabled": true}}'

Trunk Control Diagnostics Query

bash

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

Trunk Control 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/trunk/updates/stream" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d" \
     -H "Accept: text/event-stream"

Data Models

Trunk Control Request

json

{
  "action": "OPEN"
}

action: OPEN, CLOSE, STOP

Trunk Control Response

json

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

status: PENDING, PROCESSING, SUCCESS, FAILED, CANCELLED

Trunk Status Response

json

{
  "vin": "KMHSH81C7LU123456",
  "isOpen": false,
  "isLocked": true,
  "isMoving": false,
  "hasPowerTailgate": true,
  "openingHeight": 0,
  "lastAction": "CLOSE",
  "timestamp": "2026-01-12T14:30:00Z"
}

openingHeight: 0-100% (0=fully closed, 100=fully open)

Trunk 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)

Trunk Control History Request (Query Parameters)

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

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

Trunk Control History Response

json

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

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

Trunk Specification Response

json

{
  "vin": "KMHSH81C7LU123456",
  "trunkType": "POWER_TAILGATE",
  "maxOpeningHeight": 2000,
  "hasAntiPinch": true,
  "hasHandsFree": true,
  "loadCapacity": 500,
  "openingModes": ["MANUAL", "POWER", "HANDS_FREE"],
  "safetyFeatures": ["ANTI_PINCH", "OBSTACLE_DETECTION", "SPEED_LIMIT"]
}

trunkType: MANUAL, POWER_TAILGATE, ELECTRIC
maxOpeningHeight: Maximum opening height (mm)
loadCapacity: Maximum load capacity (kg)

Trunk Settings Response

json

{
  "vin": "KMHSH81C7LU123456",
  "trunk": {
    "remoteControlEnabled": true,
    "antiPinchSensitivity": "HIGH",
    "openSpeed": "SLOW",
    "autoCloseEnabled": true,
    "handsFreeEnabled": true
  },
  "safety": {
    "obstacleDetectionEnabled": true,
    "minSafeDistance": 75.0,
    "speedLimitEnabled": true,
    "maxOperatingSpeed": 5.0
  },
  "updatedTime": "2026-01-12T10:00:00Z"
}

antiPinchSensitivity: LOW, MEDIUM, HIGH
openSpeed: SLOW, NORMAL, FAST
maxOperatingSpeed: Maximum operating speed (km/h)

Trunk Control Diagnostics Response

json

{
  "vin": "KMHSH81C7LU123456",
  "systemStatus": "NORMAL",
  "components": [
    {
      "name": "Trunk Motor",
      "status": "ACTIVE",
      "health": 98,
      "lastMaintenance": "2025-06-15T00:00:00Z",
      "operatingHours": 850
    },
    {
      "name": "Anti-Pinch Sensor",
      "status": "ACTIVE",
      "health": 95,
      "lastCalibration": "2025-12-01T00:00:00Z",
      "sensitivityLevel": "HIGH"
    },
    {
      "name": "Obstacle 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

Trunk Control Status Update (SSE)

json

{
  "type": "TRUNK_STATUS_UPDATE",
  "vin": "KMHSH81C7LU123456",
  "timestamp": "2026-01-12T14:30:10Z",
  "data": {
    "isOpen": true,
    "isLocked": false,
    "isMoving": false,
    "openingHeight": 100,
    "changeType": "OPENED"
  }
}

type: TRUNK_STATUS_UPDATE, TRUNK_COMMAND_RESULT, TRUNK_SAFETY_ALERT
changeType: OPENED, CLOSED, STOPPED, OBSTRUCTION_DETECTED, SAFETY_STOP

Security and Privacy

Authentication and Authorization

User authentication token required (JWT/OAuth2)
Vehicle access permission verification
Trunk control permission verification
Two-factor authentication (MFA) support

Data Security

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

Privacy Protection

Explicit consent for vehicle control 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
Location-based restriction (Geo-fencing)

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
During Driving: Notify function limitations, display guidance message
Low Battery: Notify electric tailgate operation limitations

Authentication Failure: Request re-authentication, guide security enhancement
No Permission: Clearly display lack of permission reasons
Location Limitation: Notify control limitations outside Geo-fencing

Physical Obstacle: Notify trunk actuator error
Timeout: Notify Command TTL expiration
Partial Success: Detailed guidance when only some functions operate

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
Clear description of location information collection

Legal Regulation Compliance

Compliance with personal information protection laws
Check vehicle security related regulations
Compliance with Command Audit Log related laws

Vehicle Compatibility

Support various vehicle models
Function differences based on electric tailgate presence
Consider OEM-specific trunk control method differences

Remote Trunk Control API Developer Guide ​

Service Overview ​

Service Features ​

Legal Requirements ​

Key Scenarios ​

Scenario 1: Remote Trunk Control Request and Execution ​

Scenario 2: Trunk Control Failure and Safety Shutdown Processing ​

Scenario 3: Trunk Lock and Status Monitoring ​

Scenario 4: Trunk Diagnostics and Settings Management ​

Key Features ​

📱 Features to Implement in App ​

1. Remote Trunk Control Function ​

2. Settings Management Function ​

3. Real-time Monitoring Function ​

4. Notification and UI Functions ​

🏢 Features to Implement in Call Center ​

1. Proxy Trunk Control Function ​

2. History and Diagnostics Management Function ​

3. Settings Management Function ​

4. Customer Support Function ​

🚗 Functions Processed by Vehicle (TCU) ​

1. Trunk Control Function ​

2. Status Management Function ​

3. Safety Function ​

Sequence Diagram ​

Remote Trunk Control System Flow ​

API Endpoints ​

Trunk Open ​

Trunk Lock ​

Trunk Status Query ​

Trunk Control Cancellation ​

Trunk Control History Query ​

Trunk Specification Query ​

Trunk Settings Query ​

Trunk Settings Update ​

Trunk Control Diagnostics Query ​

Trunk Control Real-time Update Stream (SSE) ​

Data Models ​

Trunk Control Request ​

Trunk Control Response ​

Trunk Status Response ​

Trunk Cancellation Request ​

Trunk Control History Request (Query Parameters) ​

Trunk Control History Response ​

Trunk Specification Response ​

Trunk Settings Response ​

Trunk Control Diagnostics Response ​

Trunk Control 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 Trunk Control API Developer Guide

Service Overview

Service Features

Legal Requirements

Key Scenarios

Scenario 1: Remote Trunk Control Request and Execution

Scenario 2: Trunk Control Failure and Safety Shutdown Processing

Scenario 3: Trunk Lock and Status Monitoring

Scenario 4: Trunk Diagnostics and Settings Management

Key Features

📱 Features to Implement in App

1. Remote Trunk Control Function

2. Settings Management Function

3. Real-time Monitoring Function

4. Notification and UI Functions

🏢 Features to Implement in Call Center

1. Proxy Trunk Control Function

2. History and Diagnostics Management Function

3. Settings Management Function

4. Customer Support Function

🚗 Functions Processed by Vehicle (TCU)

1. Trunk Control Function

2. Status Management Function

3. Safety Function

Sequence Diagram

Remote Trunk Control System Flow

API Endpoints

Trunk Open

Trunk Lock

Trunk Status Query

Trunk Control Cancellation

Trunk Control History Query

Trunk Specification Query

Trunk Settings Query

Trunk Settings Update

Trunk Control Diagnostics Query

Trunk Control Real-time Update Stream (SSE)

Data Models

Trunk Control Request

Trunk Control Response

Trunk Status Response

Trunk Cancellation Request

Trunk Control History Request (Query Parameters)

Trunk Control History Response

Trunk Specification Response

Trunk Settings Response

Trunk Control Diagnostics Response

Trunk Control 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