Commands Service API Documentation

Base URL

/api/commands

📘 TypeScript Interfaces

// Command Send Request
export interface CommandSendRequest {
  deviceId: number;
  type: string;
  attributes?: Record<string, any>;
}

// Command Send Response
export interface CommandSendResponse {
  entryId: string;
  status: 'queued';
}

// Command Status Response
export interface CommandStatusResponse {
  entryId: string;
  status: 'pending' | 'sent' | 'delivered' | 'failed';
  error?: string;
  deviceId?: number;
  commandType?: string;
}

// Command Types Response (all)
export interface CommandTypesResponse {
  models: Record<string, string[]>;
  allCommands: string[];
}

// Command Types Response (by device)
export interface CommandTypesDeviceResponse {
  deviceId: number;
  model: string;
  commands: string[];
}

// Command Template
export interface CommandTemplate {
  id: number;
  userId: number;
  deviceId: number | null;
  name: string;
  type: string;
  description: string | null;
  attributes: Record<string, any>;
  createdAt: string;
  updatedAt: string;
}

// Create Template Request
export interface CommandTemplateCreate {
  name: string;
  type: string;
  deviceId?: number;
  attributes?: Record<string, any>;
  description?: string;
}

// Update Template Request
export interface CommandTemplateUpdate {
  name?: string;
  type?: string;
  deviceId?: number;
  attributes?: Record<string, any>;
  description?: string;
}

// Health Check Response
export interface HealthResponse {
  status: 'healthy' | 'degraded';
  database: 'ok' | 'error';
  redis: 'ok' | 'error';
}

---

📡 Endpoints

1. Command Execution

Get Command Types

GET /types

• Auth Required: Yes
• Query Params:
  • deviceId (optional): Filter commands for specific device model
• Response:
  • Without deviceId: CommandTypesResponse - All commands by model
  • With deviceId: CommandTypesDeviceResponse - Commands for device

Send Command

POST /send

• Auth Required: Yes
• Body: CommandSendRequest

{
  "deviceId": 123,
  "type": "engineStop",
  "attributes": { "duration": 60 }
}

• Response: 202 Accepted CommandSendResponse
• Errors:
  • 400 Bad Request: Command type not supported for device model
  • 403 Forbidden: No permission to send commands
  • 404 Not Found: Device not found
  • 503 Service Unavailable: Redis queue unavailable

Get Command Status

GET /status/{entryId}

• Auth Required: Yes
• Response: CommandStatusResponse

{
  "entryId": "1702300000000-0",
  "status": "pending"
}

---

2. Command Templates

List Templates

GET /

• Auth Required: Yes
• Query Params: deviceId (optional)
• Response: CommandTemplate[]

Create Template

POST /

• Auth Required: Yes
• Body: CommandTemplateCreate
• Response: 201 Created CommandTemplate

Update Template

PUT /{id}

• Auth Required: Yes
• Body: CommandTemplateUpdate
• Response: CommandTemplate
• Errors: 404 Not Found if template doesn't exist or not owned

Delete Template

DELETE /{id}

• Auth Required: Yes
• Response: 204 No Content
• Errors: 404 Not Found

---

3. Health Check

Health

GET /health

{
  "status": "healthy",
  "database": "ok",
  "redis": "ok"
}

---

🔐 Authorization

Commands require device access with command permission:

User Type	Permission
Device Owner	Always allowed
Shared User	Requires permission_commands = true

---

📋 Supported Commands

Model	Commands
S21L	s21lFreq, s21lAPN, s21lSOSNumbers
G11-SE	engineStop, doorUnlock, doorLock, trackingInterval, positionSingle
TK319	engineStop, doorUnlock, trackingInterval, positionSingle
GT06N	engineStop, positionSingle