Vehicle Burglar Alarm API Developer Guide

Service Overview

The Vehicle Burglar Alarm Service is a telematics service that activates the vehicle's alarm system when unauthorized intrusion or theft attempts occur, and simultaneously sends immediate alerts to users through the app.

Service Features

• Real-time alarm alerts for vehicle intrusion
• Detailed vehicle status information (intrusion type, location, etc.)
• Remote vehicle control functions (siren, emergency lights)
• 24/7 integrated security system

Legal Requirements

• User consent mandatory for location information collection
• Compliance with personal information protection laws
• Alarm alerts considered emergency situations and given priority processing

Key Scenarios

Scenario 1: Intrusion Detection and Real-time Alerts

API Flow by Entity:

🚗 Vehicle (TCU):

1. Intrusion Detection: Detect unauthorized entry via door/tilt sensors
2. Local Response: Automatically activate siren and emergency lights
3. Event Notification: Transmit intrusion event to core platform

📱 App (User):

1. Critical Alert: Receive high-priority push notification of intrusion
2. Event Stream: Receive real-time status via SSE
3. Status Query: Check current vehicle security state
4. Siren Control: Remotely disable siren in case of false alarm
5. Emergency Call: One-touch police reporting

🏢 Call Center:

1. Event Monitoring: Monitor global security events
2. Audit History: Review detailed alarm history
3. Police Dispatch: Coordinate with law enforcement if theft is confirmed

---

Scenario 2: Security System Configuration and Management

API Flow by Entity:

📱 App (User):

1. Status Check: Verify if system is armed
2. Armed State: Remotely arm/disarm and disarm
3. System Test: Verify sensors and siren functionality
4. Notification Settings: Configure alert preferences

🏢 Call Center:

1. Remote Config: Support users in arming/disarming their vehicles
2. Operational Heatmap: Analyze security patterns and common intrusion points

---

Scenario 3: Emergency Response and Vehicle Control

API Flow by Entity:

🏢 Call Center:

1. Emergency Situation Assessment: Evaluate anti-theft alarm severity
2. Vehicle Immobilization: Remote vehicle engine immobilization
3. Police Support Request: Emergency police support request
4. Vehicle Tracking: Provide real-time location information

📱 App (User App):

1. Emergency Alert Reception: Receive highest priority emergency alerts
2. Urgent Status Query: Immediate status check
3. Siren Control: Control siren based on situation
4. Location Check: Real-time location tracking

🚗 Vehicle (TCU):

1. Immobilization Execution: Receive and execute server immobilization command
2. Location Information Transmission: Continuously transmit real-time location information
3. Status Information Provision: Transmit all sensor and system status
4. Immobilization Release: Release immobilization on recovery

---

Scenario 4: Security Event Management and Analysis

API Flow by Entity:

🏢 Call Center:

1. Real-time Monitoring: Receive all vehicle security events
2. History Query: Analyze events by time range
3. Detailed Analysis: In-depth analysis of specific events
4. Data Management: Clean up event records

📱 App (User App):

1. Personal Event Query: My vehicle alarm records
2. Detailed Information Check: Specific event detailed information
3. Notification Settings Management: Notification settings

🚗 Vehicle (TCU):

1. History Data Provision: Transmit vehicle-specific event records
2. Status Information Provision: Transmit periodic status updates
3. Data Synchronization: Synchronize history data with server

Key Features

📱 Features to Implement in App

1. Real-time Security Monitoring

• Intrusion Alerts: Receive high-priority push notifications for detected threats
• Event Stream: Connect to real-time event updates
• Security Hub: Comprehensive view of armed state and sensors
• Alarm History: Audit past security events

2. Remote Security Control

• Siren Control: Immediate silence for alarm system
• System Arming: Remote arming with sensitivity settings
• System Disarming: Secure disarming via PIN/Biometrics
• Verification Test: Trigger test alarm for system validation

3. Support and Reporting

• Police Hotline: Instant connection to emergency services
• Notification Manager: Custom alert thresholds and channels
• Audit Logs: Searchable archive of all security interactions

---

🏢 Features to Implement in Call Center

1. Global Security Incident Management

• Security Monitoring: Monitor all vehicle security events
• History Analytics: Search and filter past incidents
• Detailed Audit: Deep-dive into specific security breaches
• Police Coordination: Coordinate with law enforcement

2. Vehicle Protection and Recovery

• Theft Immobilization: Remotely disable engine for stolen vehicles
• Recovery Release: Restore vehicle functionality after recovery
• System Configuration: Assist customers with arming protocols
• Operational Status: Monitor fleet-wide system health

Sequence Diagram

Anti-theft Alarm System Flow

API Endpoints

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

Anti-theft Alarm

Anti-theft Alarm History Query

curl -X GET "https://api.ecarus.run/api/v1/security/vehicles/KMHSH81C7LU123456/burglar-alarm/history?timeRange=LAST_WEEK" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d"

Alarm Status Query

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

Siren Off

curl -X POST "https://api.ecarus.run/api/v1/security/vehicles/KMHSH81C7LU123456/burglar-siren/off" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d" \
     -H "Content-Type: application/json" \
     -d '{"reason": "FALSE_ALARM", "userId": "user123"}'

---

Security System

Security System Status Query

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

Security System Activation

curl -X POST "https://api.ecarus.run/api/v1/security/vehicles/KMHSH81C7LU123456/antitheft/enable" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d" \
     -H "Content-Type: application/json" \
     -d '{"sensitivity": "HIGH", "notifications": true}'

Security System Deactivation

curl -X POST "https://api.ecarus.run/api/v1/security/vehicles/KMHSH81C7LU123456/antitheft/disable" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d" \
     -H "Content-Type: application/json" \
     -d '{"reason": "User request", "pin": "1234"}'

Security Alarm Trigger

curl -X POST "https://api.ecarus.run/api/v1/security/vehicles/KMHSH81C7LU123456/antitheft/trigger" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d" \
     -H "Content-Type: application/json" \
     -d '{"triggerType": "MANUAL", "reason": "Test alarm"}'

---

Security History

Security Event List Query

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

Event Detailed Information Query

curl -X GET "https://api.ecarus.run/api/v1/security/vehicles/KMHSH81C7LU123456/history/event_001" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d"

Delete Event from History

curl -X DELETE "https://api.ecarus.run/api/v1/security/vehicles/KMHSH81C7LU123456/history/event_001" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d"

---

4. Notification Settings

Notification Settings Query

curl -X GET "https://api.ecarus.run/api/v1/security/vehicles/KMHSH81C7LU123456/alerts/settings" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d"

Notification Settings Update

curl -X PUT "https://api.ecarus.run/api/v1/security/vehicles/KMHSH81C7LU123456/alerts/settings" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d" \
     -H "Content-Type: application/json" \
     -d '{
       "notifications": {
         "push": true,
         "sms": false,
         "email": true
       },
       "alertTypes": ["BURGLAR", "TOWING", "IMMOBILIZATION"]
     }'

Remote Control

Remote Vehicle Immobilization

curl -X POST "https://api.ecarus.run/api/v1/security/vehicles/KMHSH81C7LU123456/immobilize" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d" \
     -H "Content-Type: application/json" \
     -d '{
       "reason": "Theft detected",
       "pin": "1234",
       "notifyOwner": true
     }'

Immobilization Release

curl -X POST "https://api.ecarus.run/api/v1/security/vehicles/KMHSH81C7LU123456/release" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d" \
     -H "Content-Type: application/json" \
     -d '{
       "reason": "Vehicle recovered",
       "pin": "1234"
     }'

---

Emergency Services

Police Support Request

curl -X POST "https://api.ecarus.run/api/v1/security/vehicles/KMHSH81C7LU123456/burglar-police/call" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d" \
     -H "Content-Type: application/json" \
     -d '{
       "emergencyType": "BURGLARY",
       "userLocation": {
         "latitude": 37.5665,
         "longitude": 126.9780
       },
       "contactNumber": "+82-10-1234-5678",
       "description": "Vehicle hood was forced open, siren is active"
     }'

Anti-theft Alarm Real-time Event Reception (SSE)

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

curl -N -H "Accept: text/event-stream" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d" \
     "https://api.ecarus.run/api/v1/security/vehicles/KMHSH81C7LU123456/burglar-alarm/events/stream"

Data Models

Anti-theft Alarm History Response

{
  "vin": "KMHSH81C7LU123456",
  "timeRange": "LAST_WEEK",
  "events": [
    {
      "eventId": "BA-20260311-001",
      "eventType": "INTRUSION",
      "trigger": "DOOR_OPEN",
      "timestamp": "2026-03-11T14:30:00Z",
      "location": {
        "latitude": 37.5665,
        "longitude": 126.9780,
        "address": "Seoul, Gangnam-gu, Teheran-ro"
      },
      "severity": "HIGH",
      "status": "CLEARED",
      "details": {
        "door": "FRONT_LEFT",
        "forcedEntry": true,
        "sirenActivated": true
      }
    }
  ],
  "total": 1
}

Anti-theft Alarm Status Response

{
  "vin": "KMHSH81C7LU123456",
  "alarmStatus": "ARMED",
  "armedTime": "2026-03-11T22:30:00Z",
  "sensitivity": "HIGH",
  "sensorStatus": {
    "doors": {
      "frontLeft": "LOCKED",
      "frontRight": "LOCKED",
      "rearLeft": "LOCKED",
      "rearRight": "LOCKED"
    },
    "trunk": "LOCKED",
    "hood": "LOCKED"
  },
  "lastEvent": {
    "eventId": "BA-20260311-001",
    "timestamp": "2026-03-11T22:30:00Z",
    "type": "ARMED"
  }
}

Siren Off Request

{
  "reason": "FALSE_ALARM",
  "userId": "user123"
}

Siren Off Response

{
  "vin": "KMHSH81C7LU123456",
  "commandId": "CMD-20260311-001",
  "status": "EXECUTED",
  "timestamp": "2026-03-11T14:35:00Z",
  "sirenStatus": "OFF"
}

Security System Status Response

{
  "vin": "KMHSH81C7LU123456",
  "status": "ENABLED",
  "enabledTime": "2026-03-11T22:30:00Z",
  "sensitivity": "HIGH",
  "notifications": true,
  "activeFeatures": {
    "doorSensors": true,
    "motionSensor": true,
    "tiltSensor": true,
    "batteryDisconnect": true
  },
  "lastTrigger": {
    "timestamp": "2026-03-10T15:20:00Z",
    "triggerType": "MANUAL"
  }
}

Security System Activation Request

{
  "sensitivity": "HIGH",
  "notifications": true
}

Security System Deactivation Request

{
  "reason": "User request",
  "pin": "1234"
}

Security Alarm Trigger Request

{
  "triggerType": "MANUAL",
  "reason": "Test alarm"
}

Security History List Response

{
  "vin": "KMHSH81C7LU123456",
  "events": [
    {
      "eventId": "SEC-20260311-001",
      "eventType": "INTRUSION",
      "timestamp": "2026-03-11T14:30:00Z",
      "severity": "HIGH",
      "status": "CLEARED",
      "description": "Front door forced entry detected",
      "location": {
        "latitude": 37.5665,
        "longitude": 126.9780,
        "address": "Seoul, Gangnam-gu, Teheran-ro"
      }
    }
  ],
  "total": 1
}

Security Event Detail Response

{
  "eventId": "SEC-20260311-001",
  "vin": "KMHSH81C7LU123456",
  "eventType": "INTRUSION",
  "timestamp": "2026-03-11T14:30:00Z",
  "severity": "HIGH",
  "status": "CLEARED",
  "location": {
    "latitude": 37.5665,
    "longitude": 126.9780,
    "address": "Seoul, Gangnam-gu, Teheran-ro"
  },
  "description": "Front door forced entry detected",
  "details": {
    "trigger": "DOOR_OPEN",
    "door": "FRONT_LEFT",
    "forcedEntry": true,
    "sirenActivated": true
  }
}

Notification Settings Response

{
  "vin": "KMHSH81C7LU123456",
  "settings": {
    "notifications": {
      "push": true,
      "sms": false,
      "email": true
    },
    "alertTypes": ["BURGLAR", "TOWING", "IMMOBILIZATION"],
    "quietHours": {
      "enabled": true,
      "startTime": "22:00",
      "endTime": "07:00"
    }
  }
}

Notification Settings Update Request

{
  "notifications": {
    "push": true,
    "sms": false,
    "email": true
  },
  "alertTypes": ["BURGLAR", "TOWING", "IMMOBILIZATION"],
  "quietHours": {
    "enabled": false,
    "startTime": "22:00",
    "endTime": "07:00"
  }
}

Remote Vehicle Immobilization Request

{
  "reason": "Theft detected",
  "pin": "1234",
  "notifyOwner": true
}

Remote Vehicle Immobilization Response

{
  "vin": "KMHSH81C7LU123456",
  "commandId": "IMMOB-20260311-001",
  "status": "EXECUTED",
  "timestamp": "2026-03-11T14:40:00Z",
  "immobilizationStatus": "ACTIVE"
}

Immobilization Release Request

{
  "reason": "Vehicle recovered",
  "pin": "1234"
}

Immobilization Release Response

{
  "vin": "KMHSH81C7LU123456",
  "commandId": "RELEASE-20260311-001",
  "status": "EXECUTED",
  "timestamp": "2026-03-11T14:45:00Z",
  "immobilizationStatus": "RELEASED"
}

Police Support Request

{
  "emergencyType": "BURGLARY",
  "userLocation": {
    "latitude": 37.5665,
    "longitude": 126.9780
  },
  "contactNumber": "+82-10-1234-5678",
  "description": "Vehicle hood was forced open, siren is active"
}

Police Support Response

{
  "vin": "KMHSH81C7LU123456",
  "requestId": "POLICE-20260311-001",
  "status": "DISPATCHED",
  "timestamp": "2026-03-11T14:50:00Z",
  "estimatedArrival": "2026-03-11T15:10:00Z",
  "officerId": "OFFICER_123"
}

Anti-theft Alarm Real-time Event (SSE)

{
  "eventId": "EVT_001",
  "type": "INTRUSION_DETECTED",
  "timestamp": "2026-03-11T14:30:00Z",
  "priority": "HIGH",
  "data": {
    "eventId": "BA-20260311-001",
    "vin": "KMHSH81C7LU123456",
    "trigger": "DOOR_OPEN",
    "severity": "HIGH",
    "location": {
      "latitude": 37.5665,
      "longitude": 126.9780,
      "address": "Seoul, Gangnam-gu, Teheran-ro"
    },
    "details": {
      "door": "FRONT_LEFT",
      "forcedEntry": true,
      "sirenActivated": true
    }
  }
}

Security and Privacy

Authentication and Authorization

• User authentication token required (JWT/OAuth2)
• Vehicle access permission verification
• Alarm alert reception consent confirmation

Data Security

• All API communication encrypted with HTTPS/TLS
• Additional security measures for location information transmission
• Sensitive information stored only on server

Privacy Protection

• Specify purpose of location information collection
• Explicit consent for alert reception
• Compliance with data retention period policy
• Guarantee right to data deletion upon user request

Access Control

• VIN-based vehicle access permission verification
• Permission separation for multi-user households
• Separate authentication procedures for external agency access

Exception Handling

Network Related

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

Vehicle Status Related

• Vehicle Offline: Display last status information, notify offline status
• Low Battery: Guide low power mode, notify function limitations
• Sensor Error: Display sensor status error, guide service check

Alert Related

• Push Notification Failure: Attempt SMS alternative notification
• Duplicate Alerts: Filter duplicate notifications
• Alert Delay: Display delay reason, request retransmission

Test Setup

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

Use Swagger UI for interactive API testing. Jennifer

Deployment Considerations

App Store Registration

• Request emergency alert permissions
• Clear description of location information collection
• Provide privacy policy

Legal Regulation Compliance

• Compliance with personal information protection laws by country
• Check alarm system related regulations
• Emergency situation alert priority processing policy