Server-Only API - ESL Management

Server-Only API Overview

REST APIs for ESL system management, user authentication, store operations, analytics, and administrative functions. These APIs do not involve direct hardware communication.

API Details:
Protocol: HTTP/HTTPS REST
Authentication: JWT Bearer tokens
Format: JSON request/response
Base URL: https://api.esl-system.example.com/v1

🔐 Authentication

Security & Access: User and system authentication

User login/logout
JWT token management
Role-based permissions
Multi-factor authentication

🏢 Store Management

Business Operations: Store and product management

Store hierarchy
Product catalog
Pricing management
Template library

📊 Analytics

Intelligence & Reporting: Data analysis and insights

Performance metrics
Usage analytics
Business reports
Real-time dashboards

⚙️ Administration

System Management: Configuration and maintenance

User management
System configuration
Audit logging
Integration settings

Server-Only API Endpoints

🔐 Authentication APIs

POST /api/v1/auth/login

Authenticate users and return JWT access/refresh tokens

Request Body:

{ "email": "[email protected]", "password": "SecurePassword123!", "remember_me": true, "mfa_code": "123456" }

Response (200 OK):

{ "success": true, "data": { "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "refresh_token": "rt_1a2b3c4d5e6f7g8h9i0j", "expires_in": 3600, "user": { "id": "user_001", "email": "[email protected]", "role": "store_manager", "permissions": ["esl:read", "esl:write", "analytics:view"], "stores": [{"store_id": "STORE_001", "role": "manager"}] } } }

POST /api/v1/auth/refresh

Refresh access token using refresh token

Request Body:

{
  "refresh_token": "rt_1a2b3c4d5e6f7g8h9i0j"
}
                                

Response (200 OK):

{
  "success": true,
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expires_in": 3600
  }
}
                                

POST /api/v1/permissions/validate

Validate user permissions for specific operations

Request Body:

{
  "user_id": "user_001",
  "operation": "esl:bulk_update",
  "resource": {
    "type": "devices",
    "store_id": "STORE_001",
    "device_ids": ["ESL_001", "ESL_002"]
  }
}
                                

Response (200 OK):

{
  "success": true,
  "data": {
    "permission_granted": true,
    "operation_limits": {
      "max_devices_per_operation": 100,
      "remaining_operations_today": 47
    }
  }
}
                                

🏢 Store Management APIs

GET /api/v1/stores

Retrieve store information with ESL deployment details

Query Parameters:

?region=northeast&status=active&include_devices=true&page=1&limit=50

Response (200 OK):

{
  "success": true,
  "data": {
    "stores": [
      {
        "store_id": "STORE_001",
        "store_name": "Downtown Location",
        "status": "active",
        "esl_deployment": {
          "total_devices": 245,
          "active_devices": 242,
          "offline_devices": 3
        },
        "departments": [
          {
            "department_id": "DEPT_ELECTRONICS",
            "name": "Electronics",
            "device_count": 45
          }
        ]
      }
    ],
    "pagination": {
      "current_page": 1,
      "total_pages": 3,
      "total_stores": 12
    }
  }
}
                                

GET /api/v1/products

Product catalog with ESL assignments and pricing

Response (200 OK):

{
  "success": true,
  "data": {
    "products": [
      {
        "sku": "PHONE_SAMSUNG_S24",
        "product_name": "Samsung Galaxy S24",
        "brand": "Samsung",
        "pricing": {
          "base_price": 899.99,
          "store_prices": [
            {
              "store_id": "STORE_001",
              "current_price": 849.99,
              "promotion_active": true
            }
          ]
        },
        "esl_assignments": [
          {
            "store_id": "STORE_001",
            "device_id": "ESL_ELECTRONICS_001",
            "template_id": "electronics_premium"
          }
        ]
      }
    ]
  }
}
                                

PUT /api/v1/products/{sku}/pricing

Update product pricing with automatic ESL synchronization

Request Body:

{
  "sku": "PHONE_SAMSUNG_S24",
  "pricing_updates": [
    {
      "store_id": "STORE_001",
      "new_price": 799.99,
      "effective_date": "2025-05-28T06:00:00.000Z",
      "reason": "competitive_pricing"
    }
  ],
  "esl_update_config": {
    "immediate_update": false,
    "scheduled_update_time": "2025-05-28T06:00:00.000Z",
    "priority": "high"
  }
}
                                

Response (200 OK):

{
  "success": true,
  "data": {
    "pricing_update_id": "price_update_001",
    "status": "scheduled",
    "updates_processed": 2,
    "esl_devices_affected": [
      {
        "device_id": "ESL_ELECTRONICS_001",
        "update_scheduled": "2025-05-28T06:00:00.000Z"
      }
    ]
  }
}
                                

GET /api/v1/templates

Display template library with usage statistics

Response (200 OK):

{
  "success": true,
  "data": {
    "templates": [
      {
        "template_id": "electronics_premium",
        "name": "Electronics Premium Display",
        "category": "electronics",
        "supported_sizes": ["4.2", "7.5"],
        "usage_statistics": {
          "devices_using": 45,
          "stores_using": 8,
          "success_rate": 99.2
        }
      }
    ]
  }
}
                                

📊 Analytics APIs

GET /api/v1/analytics/device-performance

Device performance metrics and KPIs

Response (200 OK):

{
  "success": true,
  "data": {
    "summary": {
      "total_devices": 245,
      "online_devices": 242,
      "average_battery_level": 78.5,
      "update_success_rate": 99.2
    },
    "performance_metrics": [
      {
        "device_id": "ESL_ELECTRONICS_001",
        "uptime_percentage": 99.8,
        "average_refresh_time_ms": 4350,
        "battery_health": "excellent"
      }
    ]
  }
}
                                

GET /api/v1/reports/price-change-impact

Price change effectiveness analysis

Response (200 OK):

{
  "success": true,
  "data": {
    "report_period": {
      "start_date": "2025-05-01",
      "end_date": "2025-05-27"
    },
    "price_changes": {
      "total_changes": 1247,
      "successful_updates": 1231,
      "failed_updates": 16
    },
    "business_impact": {
      "revenue_change_percentage": 5.2,
      "customer_engagement_score": 8.7,
      "conversion_rate_improvement": 2.3
    }
  }
}
                                

WebSocket /ws/live-monitoring

Real-time device status and system health updates

WebSocket Message:

{
  "type": "device_status_update",
  "timestamp": "2025-05-27T14:00:00.000Z",
  "data": {
    "device_id": "ESL_ELECTRONICS_001",
    "status": "online",
    "battery_level": 87,
    "last_update": "2025-05-27T13:58:00.000Z"
  }
}
                                

👤 User Management APIs

GET /api/v1/users

User account management and permissions

Response (200 OK):

{ "success": true, "data": { "users": [ { "id": "user_001", "email": "[email protected]", "role": "store_manager", "status": "active", "stores": ["STORE_001"], "permissions": ["esl:read", "esl:write"], "last_login": "2025-05-27T14:00:00.000Z" } ] } }

POST /api/v1/users

Create new user account with role assignment

Request Body:

{ "email": "[email protected]", "first_name": "Jane", "last_name": "Smith", "role": "assistant_manager", "stores": ["STORE_001"], "permissions": ["esl:read", "esl:write"], "temporary_password": true }

Response (201 Created):

{ "success": true, "data": { "user_id": "user_002", "email": "[email protected]", "temporary_password": "TempPass123!", "status": "pending_activation", "activation_link": "https://app.example.com/activate/abc123" } }

⚙️ System Administration APIs

GET /api/v1/config/system

System-wide configuration settings

Response (200 OK):

{
  "success": true,
  "data": {
    "mqtt_config": {
      "broker_host": "mqtt.store.example.com",
      "broker_port": 8883,
      "max_connections": 10000
    },
    "security_config": {
      "jwt_expiry_minutes": 60,
      "refresh_token_expiry_days": 30,
      "mfa_required": true
    },
    "performance_config": {
      "max_concurrent_updates": 100,
      "bulk_operation_limit": 1000,
      "rate_limit_per_minute": 1000
    }
  }
}
                                

GET /api/v1/audit/logs

System audit logs and user activity tracking

Response (200 OK):

{
  "success": true,
  "data": {
    "logs": [
      {
        "timestamp": "2025-05-27T14:00:00.000Z",
        "user_id": "user_001",
        "action": "price_update",
        "resource": "PHONE_SAMSUNG_S24",
        "details": {
          "old_price": 899.99,
          "new_price": 849.99,
          "store_id": "STORE_001"
        },
        "ip_address": "192.168.1.100",
        "user_agent": "Mozilla/5.0..."
      }
    ],
    "pagination": {
      "current_page": 1,
      "total_pages": 25,
      "total_logs": 1247
    }
  }
}
                                

GET /api/v1/integrations/status

External integration status and health

Response (200 OK):

{
  "success": true,
  "data": {
    "integrations": [
      {
        "name": "POS System",
        "type": "pos_integration",
        "status": "healthy",
        "last_sync": "2025-05-27T13:55:00.000Z",
        "sync_frequency": "real_time",
        "error_count_24h": 0
      },
      {
        "name": "Inventory Management",
        "type": "inventory_integration",
        "status": "warning",
        "last_sync": "2025-05-27T13:45:00.000Z",
        "sync_frequency": "hourly",
        "error_count_24h": 3
      }
    ]
  }
}
                                

📋 Server API Summary

Category	Endpoint	Method	Purpose	Auth Required
Authentication	/api/v1/auth/login	POST	User authentication	No
	/api/v1/auth/refresh	POST	Token refresh	Refresh Token
	/api/v1/permissions/validate	POST	Permission validation	Yes
Store Management	/api/v1/stores	GET	Store information	Yes
	/api/v1/products	GET	Product catalog	Yes
	/api/v1/products/{sku}/pricing	PUT	Price updates	Yes
	/api/v1/templates	GET	Template library	Yes
Analytics	/api/v1/analytics/device-performance	GET	Device metrics	Yes
	/api/v1/reports/price-change-impact	GET	Business analytics	Yes
	/ws/live-monitoring	WebSocket	Real-time updates	Yes
User Management	/api/v1/users	GET/POST	User CRUD operations	Admin
User Management	/api/v1/users/{id}/permissions	PUT	Permission management	Admin
System Admin	/api/v1/config/system	GET/PUT	System configuration	SuperAdmin
	/api/v1/audit/logs	GET	Audit trail	Admin
	/api/v1/integrations/status	GET	Integration health	Yes