Skip to content

Instantly share code, notes, and snippets.

@miankhalid

miankhalid/Inverterzone-API-DOCUMENTATION.md

Created March 9, 2026 20:44
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save miankhalid/0183c4389f31dea1f2ae9f48f558b60b to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save miankhalid/0183c4389f31dea1f2ae9f48f558b60b to your computer and use it in GitHub Desktop.
Download ZIP

Revisions

  1. miankhalid created this gist Mar 9, 2026.
    987 changes: 987 additions & 0 deletions Inverterzone-API-DOCUMENTATION.md
    View file
    Original file line number Diff line number Diff line change
    @@ -0,0 +1,987 @@
    # InverterZone API Documentation

    Complete API documentation for InverterZone solar inverter monitoring system.

    ---

    ## Table of Contents

    - [Overview](#overview)
    - [Authentication](#authentication)
    - [API Endpoints](#api-endpoints)
    - [Device Management](#device-management)
    - [Realtime Data](#realtime-data)
    - [Energy Data](#energy-data)
    - [Chart Data](#chart-data)
    - [Notifications](#notifications)
    - [Settings](#settings)
    - [Timer/Scheduling](#timerscheduling)
    - [Access Control](#access-control)
    - [Dashboard](#dashboard)
    - [Common Response Codes](#common-response-codes)
    - [Notes](#notes)

    ---

    ## Overview

    | Property | Value |
    |----------|-------|
    | **Base URL** | `https://inverterzone.com` |
    | **Protocol** | HTTPS |
    | **Content Types** | `application/json`, `application/x-www-form-urlencoded` |

    ---

    ## Authentication

    All authenticated endpoints require a JWT token passed in the request body.

    ### Login

    ```http
    POST /api/login
    Content-Type: application/json
    ```

    **Request:**
    ```json
    {
    "email": "user@example.com",
    "password": "password",
    "deviceId": "unique-device-id",
    "deviceName": "Device Name"
    }
    ```

    **Response:**
    ```json
    {
    "code": "Y",
    "msg": "Login Successful",
    "token": "eyJhbGciOiJIUzI1NiJ9..."
    }
    ```

    **Notes:**
    - Store the `token` securely and include it in all subsequent requests
    - Token expires after a period (check `exp` claim in JWT)
    - Session is also tracked via `JSESSIONID` cookie in web browser

    ---

    ## API Endpoints

    ### Device Management

    #### 1. Get Device List

    ```http
    POST /api/devicesMore
    Content-Type: application/json
    ```

    **Request:**
    ```json
    {
    "token": "JWT_TOKEN",
    "pageNumber": "1"
    }
    ```

    **Response:**
    ```json
    {
    "pageNumber": 2,
    "data": [
    {
    "id": 286,
    "response": null,
    "name": "VEYRON 6KW",
    "mac": "F4CFA2735003",
    "accessDevice": null,
    "version": "9.6",
    "phone": "03468382058",
    "online": "Y",
    "production": 0,
    "load": 511,
    "email": "user@example.com",
    "location": null,
    "installedPv": null,
    "shared": "N"
    }
    ]
    }
    ```

    **Parameters:**

    | Parameter | Type | Required | Description |
    |-----------|------|----------|-------------|
    | `token` | string | Yes | JWT authentication token |
    | `pageNumber` | string | Yes | Page number for pagination |

    ---

    ### Realtime Data

    #### 2. Get Realtime Data

    ```http
    POST /api/getRealtimeData
    Content-Type: application/x-www-form-urlencoded
    ```

    **Request:**
    ```
    deviceId=F4CFA2735003
    ```

    **Response:**
    ```json
    {
    "dataDTO": {
    "deviceId": "F4CFA2735003",
    "signal": "-74",
    "localIp": "192.168.1.100",
    "type": "L",
    "gridV": 224.5,
    "gridHz": 50.0,
    "gridW": 0,
    "acOutV": 230.0,
    "acOutHz": 50.0,
    "acOutVa": 437,
    "acOutW": 417,
    "acOutPercent": 7,
    "busV": 363.0,
    "heatSinkDegC": "52",
    "inverterTemp": "0",
    "battV": 52.3,
    "battPercent": 49,
    "battChargeA": 0.0,
    "battDischargeA": 9.0,
    "solarW": 0,
    "solarV": 0.0,
    "solarA": 0.0,
    "solarW1": 0,
    "solarV1": 0.0,
    "solarA1": 0.0,
    "solarW2": 0,
    "solarV2": 0.0,
    "solarA2": 0.0,
    "solarW3": 0,
    "solarV3": 0.0,
    "solarA3": 0.0,
    "iv_mode": "B",
    "protocol": "PI30",
    "chargingStatus": "30",
    "acOutRatingW": "6000",
    "acOutRatingV": 230,
    "acOutRatungVA": "6000",
    "battRatingV": "48.0",
    "backToGridV": 48.0,
    "backToDisV": 54.0,
    "battBulkV": 56.5,
    "battFloatV": 56.5,
    "acOutRatingHz": 50.0,
    "cutOffVolts": 42.0,
    "battType": "LIB",
    "battMaxAcChrgA": "30",
    "battMaxChrgA": "50",
    "inputVoltType": "APL",
    "outputSource": "SBU",
    "chargeSource": "OSO",
    "inverterType": "Grid tie",
    "time": "0",
    "realTime": "10-03-2026 00:46",
    "serverTime": "10-03-2026 00:47",
    "currentVersion": "9.6",
    "dongleType": "regular",
    "freeHeap": "24048",
    "jsonMemUsage": "1960",
    "heapFrag": "1",
    "chargingType": "",
    "fanSpeed": "0",
    "grid": true,
    "gridFeeding": 0,
    "heavyLoadBattery": false,
    "lowSolar": false,
    "heavyLoad": false,
    "inverterSoftware": "VERFW:00060.01",
    "inverterBuzzer": "1",
    "powerSaving": "0",
    "overloadRestart": "1",
    "temperatureRestart": "1",
    "lcdBacklight": "0",
    "alarmInterrupt": "1",
    "faultRecord": "1",
    "overloadBypass": "0",
    "defaultLcdPage": "1",
    "fault": "NO",
    "solarBatteryWatts": 0,
    "gridBatteryWatts": 0,
    "name": "Veyron 6kw 48.0V 6000W",
    "pvInstalled": 6540,
    "peakSolar": 0,
    "netMetering": "Y",
    "peakLoad": 511,
    "eqStatus": 0,
    "eqTime": 60,
    "eqInterval": 30,
    "eqMaxCharge": 50,
    "eq24Charge": 30.0,
    "eqVolatge": 58.4,
    "eqOutTime": 120,
    "eqActivate": 0,
    "eqElapsetime": 0,
    "dualOutput": 1
    },
    "type": "L"
    }
    ```

    **Parameters:**

    | Parameter | Type | Required | Description |
    |-----------|------|----------|-------------|
    | `deviceId` | string | Yes | Device MAC address (e.g., `F4CFA2735003`) |

    **Key Fields:**

    | Field | Description |
    |-------|-------------|
    | `gridV`, `gridHz`, `gridW` | Grid voltage (V), frequency (Hz), power (W) |
    | `acOutV`, `acOutW`, `acOutPercent` | AC output voltage, power, load percentage |
    | `battV`, `battPercent`, `battChargeA`, `battDischargeA` | Battery voltage, percentage, charge/discharge amps |
    | `solarW`, `solarV`, `solarA` | Solar input power (W), voltage (V), amps (A) |
    | `outputSource` | Current mode: `SBU` (Solar-Battery-Utility), `SUB` (Solar-Utility-Battery) |
    | `chargeSource` | Charging mode: `OSO` (Only Solar Charging) |
    | `fault` | Fault status: `NO` = no fault |

    ---

    ### Energy Data

    #### 3. Get Energy Data

    ```http
    POST /api/getEnergy
    Content-Type: application/x-www-form-urlencoded
    ```

    **Request:**
    ```
    value=T&device=F4CFA2735003
    ```

    **Response:**
    ```json
    {
    "id": null,
    "response": null,
    "todaySolar": 0.0,
    "todayGrid": 0.0,
    "todayNetGrid": 0.0,
    "todayNetSolar": 0.0,
    "todayBattery": 0.3,
    "todaySolarBattery": 0.0,
    "todayGridBattery": 0.0,
    "todayTotal": 0.4,
    "todayLoad": 0.3,
    "rate": 42,
    "time": null,
    "graphData": null,
    "monthChart": null
    }
    ```

    **Parameters:**

    | Parameter | Type | Required | Description |
    |-----------|------|----------|-------------|
    | `value` | string | Yes | Time period: `T` (Today), `TM` (This Month), `LM` (Last Month) |
    | `device` | string | Yes | Device MAC address |

    **Value Options:**

    | Value | Description |
    |-------|-------------|
    | `T` | Today |
    | `TM` | This Month |
    | `LM` | Last Month |

    **Energy Fields (kWh):**

    | Field | Description |
    |-------|-------------|
    | `todaySolar` | Solar energy generated |
    | `todayGrid` | Energy from grid |
    | `todayNetGrid` | Net grid energy (export - import) |
    | `todayBattery` | Battery energy used |
    | `todayLoad` | Total load consumption |
    | `rate` | Electricity rate (currency per kWh) |

    ---

    ### Chart Data

    #### 4. Get Realtime Chart Data

    ```http
    POST /api/realtimeChart
    Content-Type: application/json
    ```

    **Request:**
    ```json
    {
    "token": "JWT_TOKEN",
    "deviceId": "F4CFA2735003"
    }
    ```

    **Response:**
    ```json
    {
    "chart": [...],
    "chart24": [...],
    "chartMonth": null,
    "monthStats": null
    }
    ```

    **Parameters:**

    | Parameter | Type | Required | Description |
    |-----------|------|----------|-------------|
    | `token` | string | Yes | JWT authentication token |
    | `deviceId` | string | Yes | Device MAC address |

    **Response Structure:**

    | Field | Description |
    |-------|-------------|
    | `chart` | Array of recent data points (minute-by-minute) |
    | `chart24` | Array of 24-hour aggregated data points |
    | `chartMonth` | Monthly chart data (null in this endpoint) |
    | `monthStats` | Monthly statistics (null in this endpoint) |

    ---

    #### 5. Get Realtime Chart Data (With Period)

    ```http
    POST /api/realtimeChartData
    Content-Type: application/json
    ```

    **Request:**
    ```json
    {
    "token": "JWT_TOKEN",
    "deviceId": "F4CFA2735003",
    "value": "TM"
    }
    ```

    **Response:**
    ```json
    {
    "chart": null,
    "chart24": null,
    "chartMonth": [
    {
    "deviceId": "F4CFA2735003",
    "gridV": 241.1,
    "gridW": -4226,
    "solarW": 4494,
    "battV": 56.4,
    "battPercent": 0,
    "time": "05-03-2026 11:40",
    "timeDate": 1772692811.682,
    "realTime": "05-03-2026 11:40"
    }
    ],
    "monthStats": [
    {
    "todaySolar": 23.8,
    "todayGrid": 3.3,
    "todayNetGrid": 12.1,
    "todayBattery": 2.4,
    "todayLoad": 8.6,
    "rate": 0,
    "time": "2026-03-09"
    }
    ]
    }
    ```

    **Parameters:**

    | Parameter | Type | Required | Description |
    |-----------|------|----------|-------------|
    | `token` | string | Yes | JWT authentication token |
    | `deviceId` | string | Yes | Device MAC address |
    | `value` | string | Yes | Time period: `TM` (This Month), `LM` (Last Month) |

    ---

    ### Notifications

    #### 6. Get Notifications Count

    ```http
    POST /api/getNotificationsCount
    Content-Type: application/json
    ```

    **Request:**
    ```json
    {
    "token": "JWT_TOKEN",
    "deviceId": "F4CFA2735003"
    }
    ```

    **Response:**
    ```
    0
    ```

    **Parameters:**

    | Parameter | Type | Required | Description |
    |-----------|------|----------|-------------|
    | `token` | string | Yes | JWT authentication token |
    | `deviceId` | string | Yes | Device MAC address |

    ---

    #### 7. Read Notifications (Mark as Read)

    ```http
    POST /api/readNotifications
    Content-Type: application/json
    ```

    **Request:**
    ```json
    {
    "token": "JWT_TOKEN",
    "deviceId": "F4CFA2735003"
    }
    ```

    **Response:**
    ```
    (empty - 200 OK)
    ```

    ---

    #### 8. Get Notifications (Paginated)

    ```http
    POST /api/getNotificationsMore
    Content-Type: application/json
    ```

    **Request:**
    ```json
    {
    "token": "JWT_TOKEN",
    "deviceId": "F4CFA2735003",
    "pageNumber": "1"
    }
    ```

    **Response:**
    ```json
    {
    "pageNumber": 2,
    "data": [
    {
    "id": null,
    "response": null,
    "msg": "Timer set Mode to Solar Battery Sharing (SBU)",
    "status": "Y",
    "type": "T",
    "time": "12:00 AM | 10-03-2026"
    },
    {
    "id": null,
    "response": null,
    "msg": "Battery Under Heavy Load 2120W",
    "status": "Y",
    "type": "B",
    "time": "03:53 PM | 09-03-2026"
    }
    ]
    }
    ```

    **Parameters:**

    | Parameter | Type | Required | Description |
    |-----------|------|----------|-------------|
    | `token` | string | Yes | JWT authentication token |
    | `deviceId` | string | Yes | Device MAC address |
    | `pageNumber` | string | Yes | Page number for pagination |

    **Notification Types:**

    | Type | Description |
    |------|-------------|
    | `T` | Timer event |
    | `B` | Battery event (low/high/heavy load) |

    ---

    ### Settings

    #### 9. Get Settings Data

    ```http
    POST /api/getSettingsData
    Content-Type: application/json
    ```

    **Request:**
    ```json
    {
    "token": "JWT_TOKEN",
    "deviceId": "F4CFA2735003"
    }
    ```

    **Response:**
    ```json
    {
    "outputMode": "SBU",
    "batteryChargeMode": "OSO",
    "floatCharge": 56.5,
    "bulkCharge": 56.5,
    "backDichargeVolt": 54.0,
    "cutOffVolt": 42.0,
    "backToGrid": 48.0,
    "acOutRatingHz": 50.0,
    "acChargeA": "30",
    "solarChargeA": "50",
    "acOutRatingW": "6000",
    "acInputRange": "APL",
    "batteryType": "PYL",
    "batteryRatingV": "48.0",
    "notification": "Y",
    "emailNotification": "N",
    "signal": "-73",
    "firmware": "9.6",
    "inverterType": "Grid tie",
    "netMetering": "Y",
    "pvCapacity": 6540,
    "batAlert": 1900,
    "outputV": 230,
    "packageDate": "Expired",
    "inverterSoftware": "VERFW:00060.01",
    "inverterBuzzer": "1",
    "powerSaving": "0",
    "powerPriority": null,
    "overloadRestart": "1",
    "temperatureRestart": "0",
    "lcdBacklight": "0",
    "alarmInterrupt": "1",
    "faultRecord": "1",
    "overloadBypass": "0",
    "defaultLcdPage": "1",
    "brandName": "inverex",
    "modelName": "VEYRON II",
    "protocol": "PI30",
    "rate": 42,
    "eqStatus": 0,
    "eqTime": 60,
    "eqInterval": 30,
    "eqMaxCharge": null,
    "eq24Charge": null,
    "eqVolatge": 58.4,
    "eqOutTime": null,
    "eqActivate": 0,
    "eqElapsetime": null,
    "dualOutput": 1,
    "location": "Y",
    "dualOutputVolts": null
    }
    ```

    **Parameters:**

    | Parameter | Type | Required | Description |
    |-----------|------|----------|-------------|
    | `token` | string | Yes | JWT authentication token |
    | `deviceId` | string | Yes | Device MAC address |

    **Key Settings:**

    | Field | Description |
    |-------|-------------|
    | `outputMode` | Output mode: `SBU`, `SUB`, etc. |
    | `batteryChargeMode` | Charging mode: `OSO` (Only Solar) |
    | `floatCharge`, `bulkCharge` | Battery charging voltages |
    | `cutOffVolt` | Battery cut-off voltage |
    | `batteryType` | Battery type: `PYL` (LiFePO4), `LIB` (Lithium), etc. |
    | `firmware` | Device firmware version |
    | `pvCapacity` | Installed PV capacity (W) |

    ---

    ### Timer/Scheduling

    #### 10. Get Timer Devices

    ```http
    POST /api/getTimerDevices
    Content-Type: application/json
    ```

    **Request:**
    ```json
    {
    "token": "JWT_TOKEN"
    }
    ```

    **Response:**
    ```json
    [
    {
    "id": 286,
    "response": null,
    "name": "VEYRON 6KW",
    "mac": "F4CFA2735003",
    "accessDevice": null,
    "version": "9.6",
    "phone": null,
    "online": null,
    "production": null,
    "load": null,
    "email": null,
    "location": null,
    "installedPv": null,
    "shared": null
    }
    ]
    ```

    ---

    #### 11. Get Timer Data

    ```http
    POST /api/getTimerData
    Content-Type: application/json
    ```

    **Request:**
    ```json
    {
    "token": "JWT_TOKEN",
    "deviceId": "286"
    }
    ```

    **Response:**
    ```json
    [
    {
    "id": 1524,
    "response": null,
    "name": "Veyron 6kw",
    "setting": "Mode",
    "value": "SBU",
    "time": "17:59:00",
    "working": "Y",
    "schedule": "D",
    "deviceId": null,
    "protocol": null
    },
    {
    "id": 5941,
    "setting": "Mode",
    "value": "SUB",
    "time": "22:05:00",
    "working": "Y",
    "schedule": "D"
    }
    ]
    ```

    **Parameters:**

    | Parameter | Type | Required | Description |
    |-----------|------|----------|-------------|
    | `token` | string | Yes | JWT authentication token |
    | `deviceId` | string | Yes | Device numeric ID (e.g., `286`) |

    **Schedule Values:**

    | Value | Description |
    |-------|-------------|
    | `D` | Daily |

    ---

    #### 12. Get Timer Setting Dropdown

    ```http
    POST /api/getTimerSettingDropdown
    Content-Type: application/json
    ```

    **Request:**
    ```json
    {
    "token": "JWT_TOKEN"
    }
    ```

    **Response:**
    ```json
    [
    {"label": "Mode", "value": "Mode"},
    {"label": "Charging Mode", "value": "Charging"},
    {"label": "Battery Type", "value": "BatteryType"},
    {"label": "Grid Charging", "value": "GridCharging"},
    {"label": "Solar Charging", "value": "SolarCharging"},
    {"label": "Cutt Of Volts", "value": "CuttOfVolts"},
    {"label": "Back to Grid Volts", "value": "BackToGrid"},
    {"label": "Float Volts", "value": "FloatVolts"}
    ]
    ```

    ---

    ### Access Control

    #### 13. Check Access

    ```http
    POST /api/checkAccess
    Content-Type: application/json
    ```

    **Request:**
    ```json
    {
    "token": "JWT_TOKEN",
    "deviceId": "F4CFA2735003"
    }
    ```

    **Response:**
    ```json
    {
    "code": "Y",
    "msg": "Y",
    "devicesCount": null,
    "timerCount": null,
    "accessCount": null
    }
    ```

    ---

    #### 14. Check Owner Access

    ```http
    POST /api/checkOwnerAccess
    Content-Type: application/json
    ```

    **Request:**
    ```json
    {
    "token": "JWT_TOKEN"
    }
    ```

    **Response:**
    ```json
    {
    "code": "N",
    "msg": "N",
    "devicesCount": null,
    "timerCount": null,
    "accessCount": null
    }
    ```

    **Response Codes:**

    | Code | Description |
    |------|-------------|
    | `Y` | User has owner access |
    | `N` | User does not have owner access |

    ---

    #### 15. Get Access Share Devices

    ```http
    POST /api/accessShareDevices
    Content-Type: application/json
    ```

    **Request:**
    ```json
    {
    "token": "JWT_TOKEN"
    }
    ```

    **Response:**
    ```json
    []
    ```

    ---

    #### 16. Get Access Device Dropdown

    ```http
    POST /api/getAccessDeviceDropDown
    Content-Type: application/json
    ```

    **Request:**
    ```json
    {
    "token": "JWT_TOKEN"
    }
    ```

    **Response:**
    ```json
    [
    {"label": "VEYRON 6KW-F4CFA2735003", "value": "286"}
    ]
    ```

    ---

    ### Dashboard

    #### 17. Get Dashboard Info

    ```http
    POST /api/dashboard
    Content-Type: application/json
    ```

    **Request:**
    ```json
    {
    "token": "JWT_TOKEN"
    }
    ```

    **Response:**
    ```json
    {
    "devicesCount": 1,
    "timerCount": 6,
    "accessCount": 0,
    "nearByCount": 14104,
    "favCount": 1,
    "userEmail": "user@example.com",
    "userName": "User Name"
    }
    ```

    **Response Fields:**

    | Field | Description |
    |-------|-------------|
    | `devicesCount` | Number of devices owned by user |
    | `timerCount` | Number of active timers |
    | `accessCount` | Number of shared access grants |
    | `nearByCount` | Number of nearby devices (for discovery) |
    | `favCount` | Number of favorited devices |
    | `userEmail` | User's email address |
    | `userName` | User's display name |

    ---

    ## Common Response Codes

    | HTTP Code | Description | Action |
    |-----------|-------------|--------|
    | 200 | Success | Request completed successfully |
    | 401 | Unauthorized | Invalid or expired token - re-authenticate |
    | 403 | Forbidden | User lacks permission for this resource |
    | 404 | Not Found | Resource or endpoint not found |
    | 500 | Internal Server Error | Server error - retry later |
    | 503 | Service Unavailable | Server temporarily unavailable |

    ---

    ## Notes

    ### Authentication

    1. **Token Storage**: Store JWT tokens securely (Keychain/Keystore for mobile apps)
    2. **Token Expiry**: Check token expiration and refresh before expiry
    3. **Session Cookie**: Web app also uses `JSESSIONID` cookie for session management

    ### Content Types

    | Endpoint | Content-Type |
    |----------|--------------|
    | `/api/getRealtimeData` | `application/x-www-form-urlencoded` |
    | `/api/getEnergy` | `application/x-www-form-urlencoded` |
    | All other endpoints | `application/json` |

    ### Device ID Formats

    Some endpoints accept different device ID formats:

    | Format | Example | Used By |
    |--------|---------|---------|
    | MAC Address | `F4CFA2735003` | `getRealtimeData`, `getEnergy`, `checkAccess` |
    | Numeric ID | `286` | `getTimerData`, dropdown endpoints |

    ### Mode Values

    | Mode | Description |
    |------|-------------|
    | `SBU` | Solar-Battery-Utility (prioritize solar, then battery, then grid) |
    | `SUB` | Solar-Utility-Battery (prioritize solar, then grid, then battery) |
    | `OSO` | Only Solar Charging |

    ### Rate Limiting

    - API may implement rate limiting
    - Handle 429 (Too Many Requests) responses with exponential backoff
    - Avoid polling realtime endpoints more than once per minute

    ### Error Handling

    Always check response status and handle errors gracefully:

    ```javascript
    if (response.code === 'Y') {
    // Success
    } else {
    // Handle error
    console.error(response.msg);
    }
    ```

    ---

    ## Version History

    | Version | Date | Changes |
    |---------|------|---------|
    | 1.0 | 2026-03-10 | Initial documentation from HAR analysis |

    ---

    **Generated from network traffic analysis on 2026-03-10**