Low Battery Alert API Developer Guide

Service Overview

The Battery Status Alert service is an event-based service that detects when the vehicle battery status falls below a critical level and delivers notifications from vehicle → telematics server → user application.

Service Features

Automatic detection and alert for battery low voltage
Prevention of engine start failure
Prevention of electric vehicle driving inability
Status-based warning service
Reduces user inconvenience and emergency situations

Legal Requirements

Compliance with personal information protection laws
Mandatory data collection consent
Compliance with notification policies

Key Scenarios

Scenario 1: Battery Low Voltage Detection and Warning Processing

API Flow by Entity:

🚗 Vehicle:

Battery Monitoring: Continuous battery voltage monitoring (detect 11.7V)
Low Voltage Detection: Automatic detection of low voltage state below 11.8V
Event Transmission: Transmit battery low voltage event
Continuous Status Monitoring: Continuous battery status monitoring and reporting
Threshold Verification: Distinguish between normal state (>12.0V) and low voltage state (<11.8V)

🏢 Call Center:

Warning Ticket Creation: Automatic creation of battery low voltage warning ticket
Risk Level Assessment: Risk level assessment based on battery status
Emergency Call Preparation: Prepare emergency call if no response within 5 minutes
Follow-up Action Management: Manage and track necessary follow-up actions
Status Update: Update battery warning status

📱 User App:

Push Notification Reception: Immediate reception of battery low voltage warning push notification
Status Query: Immediate query of current battery status
Emergency Call Reception: Receive emergency call from call center
Real-time Event Reception: Real-time reception of battery status updates via SSE
Risk Status Check: Check and respond to battery risk status

Scenario 2: Battery Status Management and Information Query

API Flow by Entity:

📱 User App:

Battery Status Query: Real-time battery voltage and SOC query
Detailed Information Check: Check detailed battery information and health status
Record Query: Query past battery status records
Analysis Information Query: Query battery performance and status analysis
Prediction Information Query: Predict battery lifespan and replacement timing

🚗 Vehicle:

Status Data Provision: Provide detailed data including battery voltage, SOC, temperature
Record Data Storage: Store battery status change history data
Real-time Status Transmission: Real-time transmission of current battery status
Diagnostic Data Generation: Generate battery diagnostic related data
Status Update: Immediate update when battery status changes

🏢 Call Center:

Status Data Reception: Receive battery status data from vehicle
Analysis Processing: Analyze battery status data and risk assessment
Record Management: Manage battery status record data
Prediction Modeling: Predict battery lifespan and replacement timing
Consultation Support: Provide consultation support based on battery status

Scenario 3: Real-time Battery Event Monitoring

API Flow by Entity:

🏢 Call Center:

Real-time Event Stream: Real-time transmission of battery status updates via SSE
Event Processing: Immediate processing of battery status change events
Risk Detection: Real-time battery risk status detection
Notification Generation: Generate notifications based on status changes
Monitoring Dashboard: Real-time battery status monitoring dashboard

📱 User App:

SSE Event Reception: Receive real-time battery status updates
Status Change Notification: Immediate notification of battery status changes
Real-time Display: Real-time display of current battery voltage and SOC
Risk Warning: Immediate warning when risk status changes
Status Recording: Real-time status change recording

🚗 Vehicle:

Continuous Status Monitoring: Continuous battery status monitoring
Event Generation: Automatic event generation when status changes
Real-time Transmission: Real-time transmission of status change data
Threshold Monitoring: Continuous monitoring of risk thresholds
Status Reporting: Periodic status reporting

Scenario 4: Maintenance Reservation and Follow-up Actions

API Flow by Entity:

📱 User App:

Maintenance Reservation: Reserve battery replacement
Reservation Confirmation: Check reservation status and time
Service Linkage: Automatic linkage with repair center service
Follow-up Action Check: Check necessary follow-up actions
Reservation Management: Manage reservation changes and cancellations

🏢 Call Center:

Service Call: Connect service call to user
Reservation Processing: Process battery replacement reservation
Follow-up Action Management: Manage necessary follow-up actions
Status Update: Update battery warning status
Service Provider Linkage: Linkage with service providers like repair centers

🚗 Vehicle:

Service Preparation: Prepare vehicle status for maintenance service
Status Information Provision: Provide detailed status information needed for service
Diagnostic Data Transmission: Transmit diagnostic data to service center
Status Monitoring: Monitor status before and after service
Completion Report: Report service completion status

Key Features

📱 Features to Implement in App

1. Real-time Battery Status Monitoring

Status Query: Display real-time battery voltage and remaining level
Detailed Information Check: Display battery status warning level
Real-time Event Reception: Receive real-time status updates via SSE
Temperature Monitoring: Real-time battery temperature monitoring

2. Notification Reception and Management

Push Notification Reception: Immediate reception of battery low voltage warning push notifications
Emergency Call Reception: Receive emergency call from call center
Notification Type Management: Manage low voltage, insufficient level, status recovery notifications
Notification Settings: Set and manage notification levels (warning/risk)
Notification Ignore Function: Temporary notification ignore function

3. Battery Information Query and Analysis

Record Query: Query past battery status history
Analysis Query: Query battery performance and status analysis
Prediction Query: Predict battery lifespan and replacement timing
Trend Analysis: Analyze battery status change trends
Performance Evaluation: Evaluate battery efficiency and lifespan

4. Maintenance Service Linkage

Maintenance Reservation: Reserve battery replacement
Repair Center Linkage: Linkage with repair center reservation when battery fails
Service Status Tracking: Real-time tracking of reserved service progress
Follow-up Action Guidance: Guide and reserve necessary follow-up actions
Service History Management: Manage past maintenance service history

5. Settings and Personalization

Notification Level Settings: Set notifications by warning/risk levels
Notification Period Settings: Set notification occurrence period and time
Vehicle-specific Settings: Individual settings for multi-vehicle battery status notifications
Location-based Settings: Location-based notification settings
Personalization Profile: Set user-specific notification profiles

🏢 Features to Implement in Call Center

1. Battery Status Monitoring System

Real-time Status Reception: Real-time reception of vehicle battery status
Status Analysis: Automatic battery status analysis
Risk Detection: Automatic detection of low voltage and insufficient level risks
Status Recording: Record all battery status changes
Performance Monitoring: Real-time battery performance monitoring

2. Notification Generation and Transmission System

Event-based Notifications: Automatic notification generation based on battery status events
Push Notifications: Real-time transmission of push notifications to user apps
Emergency Call: Automatic connection of emergency call if no response within 5 minutes
Notification Priority Management: Manage notification priority by risk level
Notification Channel Management: Multi-channel notifications (Push, Call)

3. Battery Data Analysis System

Record Management: Manage battery status records
Analysis Processing: Process battery performance and status analysis
Prediction Model: Predict battery lifespan and replacement timing
Trend Analysis: Analyze battery status change trends
Performance Reporting: Analyze battery status alert service performance

4. Service Linkage System

Warning Ticket Creation: Automatic creation of battery low voltage warning tickets
Maintenance Reservation: Process battery replacement reservation
Repair Center Linkage: Automatic linkage with repair centers when battery fails
Service Call: Connect service call to user
Follow-up Action Management: Manage and track necessary follow-up actions

5. Status Recovery Management System

Recovery Detection: Automatic detection of battery status recovery
Notification Release: Automatic release of warning notifications
Recovery Notification: Transmit status recovery notification to user
Recovery Analysis: Analyze battery recovery causes
Normal Status Check: Confirm return to normal status

6. Prediction and Prevention System

Discharge Prediction: Predict battery discharge timing
Lifespan Prediction: Predict battery lifespan and replacement timing
Risk Assessment: Automatic assessment of battery failure risk
Preventive Notifications: Generate preventive notifications
Maintenance Recommendation: Recommend optimal maintenance timing

7. Data Management and Security

Data Collection: Automatic collection of battery status data
Data Storage: Secure storage of battery record data
Data Analysis: Comprehensive analysis of battery data
Privacy Protection: Protect user battery information privacy
Audit Log: Audit log of battery data access and processing

8. System Operations and Monitoring

System Status Monitoring: 24-hour monitoring of battery status alert system
API Performance Monitoring: Monitor API response time and availability
Data Integrity Management: Verify battery data integrity
Exception Handling: Handle network, sensor, and notification exceptions
System Optimization: Optimize battery status alert processing logic

Sequence Diagram

Battery Status Alert System Flow

Battery Status Alert

API Endpoints

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

Battery Status Query

bash

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

Detailed Battery Status Query

bash

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

Battery Record Query

bash

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

Battery Analysis Query

bash

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

Battery Prediction Query

bash

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

Data Models

Battery Status Information

json

{
  "vin": "KNXXXXXXX",
  "batteryStatus": {
    "batteryType": "12V",
    "voltage": 12.1,
    "soc": 75,
    "health": "GOOD",
    "temperature": 25.5,
    "isCharging": false
  },
  "vehicleStatus": {
    "ignition": "OFF",
    "parkingDuration": 72,
    "lastDriveTime": "2026-01-10T18:30:00Z"
  },
  "timestamp": "2026-01-13T14:30:00Z"
}

Notification Settings Information

json

{
  "userId": "user123",
  "vin": "KNXXXXXXX",
  "notificationSettings": {
    "alertLevel": "WARNING",
    "enablePush": true,
    "ignoreDuration": 3600,
    "reminderInterval": 1800,
    "soundEnabled": true
  },
  "lastUpdated": "2026-01-13T14:30:00Z"
}

Battery Record Response

json

{
  "history": [
    {
      "timestamp": "2026-01-13T14:30:00Z",
      "voltage": 12.1,
      "soc": 75,
      "health": "GOOD",
      "temperature": 25.5,
      "chargingStatus": "NOT_CHARGING",
      "eventType": "STATUS_UPDATE"
    },
    {
      "timestamp": "2026-01-13T10:15:00Z",
      "voltage": 11.9,
      "soc": 68,
      "health": "FAIR",
      "temperature": 22.3,
      "chargingStatus": "CHARGING",
      "eventType": "LOW_VOLTAGE_WARNING"
    }
  ],
  "total": 45,
  "summary": {
    "totalRecords": 2,
    "avgVoltage": 12.0,
    "avgSoc": 71.5,
    "minVoltage": 11.9,
    "maxVoltage": 12.1,
    "warningCount": 1,
    "criticalCount": 0
  }
}

Battery Analysis Response

json

{
  "period": "30d",
  "trends": {
    "voltageTrend": "STABLE",
    "healthTrend": "IMPROVING",
    "socTrend": "STABLE"
  },
  "statistics": {
    "avgVoltage": 12.05,
    "minVoltage": 11.8,
    "maxVoltage": 12.6,
    "avgTemperature": 24.5,
    "chargeCycles": 15,
    "dischargeCycles": 320,
    "avgDailyDrain": 2.5
  },
  "performance": {
    "efficiency": 92.5,
    "reliability": 98.2,
    "healthScore": 85.5,
    "capacityRetention": 94.2
  },
  "recommendations": [
    "The battery performance is good",
    "Optimizing charging patterns can extend lifespan",
    "Regular battery inspection is recommended"
  ],
  "generatedAt": "2026-01-13T14:30:00Z"
}

Battery Prediction Response

json

{
  "current": {
    "voltage": 12.1,
    "soc": 75,
    "temperature": 25.5,
    "timestamp": "2026-01-13T14:30:00Z"
  },
  "prediction": {
    "timeToEmpty": {
      "estimatedHours": 72.5,
      "estimatedTime": "2026-01-16T14:30:00Z",
      "confidence": 0.85
    },
    "healthScore": {
      "current": 85,
      "predicted": 82,
      "trend": "STABLE"
    },
    "nextService": {
      "date": "2026-07-15",
      "remainingDays": 183,
      "urgency": "LOW"
    },
    "failureRisk": {
      "level": "LOW",
      "probability": 0.05,
      "factors": ["age", "usage_pattern"]
    }
  },
  "scenarios": [
    {
      "type": "NORMAL_USAGE",
      "timeToEmptyHours": 72.5,
      "confidence": 0.85
    },
    {
      "type": "HEAVY_USAGE",
      "timeToEmptyHours": 48.0,
      "confidence": 0.75
    },
    {
      "type": "MINIMAL_USAGE",
      "timeToEmptyHours": 96.0,
      "confidence": 0.90
    }
  ],
  "model": {
    "algorithm": "LINEAR_REGRESSION",
    "accuracy": 0.85,
    "lastUpdated": "2026-01-13T09:00:00Z",
    "trainingDataPoints": 450
  }
}

Battery Detailed Information

json

{
  "vin": "KNXXXXXXX",
  "battery": {
    "batteryType": "12V",
    "voltage": 12.1,
    "soc": 75,
    "health": "GOOD",
    "temperature": 25.5,
    "isCharging": false,
    "chargeRate": 0.0,
    "dischargeRate": 0.2,
    "estimatedLife": 365,
    "lastCharge": "2026-01-12T18:30:00Z",
    "age": "2.5 years",
    "cycleCount": 150
  },
  "diagnostics": {
    "cellBalance": true,
    "internalResistance": 0.015,
    "capacity": 60.0,
    "maxCapacity": 65.0,
    "currentCapacity": 48.75,
    "capacityRetention": 75.0
  },
  "maintenance": {
    "nextServiceDate": "2026-07-15",
    "recommendedReplacement": "2026-12-15",
    "warrantyExpiry": "2027-01-15",
    "lastServiceDate": "2025-07-15"
  },
  "timestamp": "2026-01-13T14:30:00Z"
}

Security and Privacy

Authentication and Authorization

User authentication token required (JWT/OAuth2)
Vehicle access permission verification
Notification reception permission verification

Data Security

All API communication encrypted with HTTPS/TLS
Security measures when transmitting battery status information
Sensitive information stored only on server

Privacy Protection

Explicit consent for battery status information collection
Specify data collection purpose
Compliance with data retention period policy
Guarantee right to data deletion upon user request

Access Control

VIN-based vehicle access permission verification
Manage user-specific notification setting permissions
Detect abnormal access patterns

Exception Handling

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

Sensor Error: Sensor error notification, display default values
Data Inaccuracy: Low data reliability notification
Battery Failure: Battery failure notification, maintenance guidance

Duplicate Notifications: Prevent duplicate notifications with debounce processing
Notification Failure: Retry when notification transmission fails
User Ignore: Reflect user ignore settings

Test Setup

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

Use Swagger UI for interactive API testing.

Deployment Considerations

App Store Registration

Request battery status monitoring permissions
Request push notification permissions
Clear description of location information collection

Legal Regulation Compliance

Compliance with personal information protection laws
Mandatory data collection consent
Compliance with notification policies

Vehicle Compatibility

Support various vehicle models
Support internal combustion engine/electric/hybrid vehicles
Reflect functionality differences by battery type

Low Battery Alert API Developer Guide ​

Service Overview ​

Service Features ​

Legal Requirements ​

Key Scenarios ​

Scenario 1: Battery Low Voltage Detection and Warning Processing ​

Scenario 2: Battery Status Management and Information Query ​

Scenario 3: Real-time Battery Event Monitoring ​

Scenario 4: Maintenance Reservation and Follow-up Actions ​

Key Features ​

📱 Features to Implement in App ​

1. Real-time Battery Status Monitoring ​

2. Notification Reception and Management ​

3. Battery Information Query and Analysis ​

4. Maintenance Service Linkage ​

5. Settings and Personalization ​

🏢 Features to Implement in Call Center ​

1. Battery Status Monitoring System ​

2. Notification Generation and Transmission System ​

3. Battery Data Analysis System ​

4. Service Linkage System ​

5. Status Recovery Management System ​

6. Prediction and Prevention System ​

7. Data Management and Security ​

8. System Operations and Monitoring ​

Sequence Diagram ​

Battery Status Alert System Flow ​

API Endpoints ​

Battery Status Query ​

Detailed Battery Status Query ​

Battery Record Query ​

Battery Analysis Query ​

Battery Prediction Query ​

Data Models ​

Battery Status Information ​

Notification Settings Information ​

Battery Record Response ​

Battery Analysis Response ​

Battery Prediction Response ​

Battery Detailed Information ​

Security and Privacy ​

Authentication and Authorization ​

Data Security ​

Privacy Protection ​

Access Control ​

Exception Handling ​

Network Related ​

Sensor Related ​

Notification Related ​

Test Setup ​

Deployment Considerations ​

App Store Registration ​

Legal Regulation Compliance ​

Vehicle Compatibility ​

Low Battery Alert API Developer Guide

Service Overview

Service Features

Legal Requirements

Key Scenarios

Scenario 1: Battery Low Voltage Detection and Warning Processing

Scenario 2: Battery Status Management and Information Query

Scenario 3: Real-time Battery Event Monitoring

Scenario 4: Maintenance Reservation and Follow-up Actions

Key Features

📱 Features to Implement in App

1. Real-time Battery Status Monitoring

2. Notification Reception and Management

3. Battery Information Query and Analysis

4. Maintenance Service Linkage

5. Settings and Personalization

🏢 Features to Implement in Call Center

1. Battery Status Monitoring System

2. Notification Generation and Transmission System

3. Battery Data Analysis System

4. Service Linkage System

5. Status Recovery Management System

6. Prediction and Prevention System

7. Data Management and Security

8. System Operations and Monitoring

Sequence Diagram

Battery Status Alert System Flow

API Endpoints

Battery Status Query

Detailed Battery Status Query

Battery Record Query

Battery Analysis Query

Battery Prediction Query

Data Models

Battery Status Information

Notification Settings Information

Battery Record Response

Battery Analysis Response

Battery Prediction Response

Battery Detailed Information

Security and Privacy

Authentication and Authorization

Data Security

Privacy Protection

Access Control

Exception Handling

Network Related

Sensor Related

Notification Related

Test Setup

Deployment Considerations

App Store Registration

Legal Regulation Compliance

Vehicle Compatibility