Token｜數據存取

API Domain

https://ioe-api.nextdrive.io/device-management

MQTT Data Format

Topic

log/registers/nextdrive/{{gatewayId}}

Schema

Column

Format

Example

Description

1

gatewayId

string

A005DFEFIE5CE83CE

  • Required

  • Gateway PID（產品序號）

2

meterId

string

KT90000046

  • Required

  • 智慧電表表號

3

deviceUuid

string

9678a700-7c93-4db7-84c8-32747937a40c

  • Required

  • 智慧電表唯一識別碼，由NextDrive 產生

4

customerId

string

00000000000

  • Required

  • 用戶電號

5

routeBMacAddr

string

00:00:00:00:00:00

  • Required

  • Route B 模組 Mac Address

6

itemTimestamp

  • float

  • non-negative

  • 單位：秒

1728015180

  • Required

  • 資料產生的時間戳
    （Unix epoch time）

7

_uploadedTime

  • float

  • non-negative

  • 單位：秒

1728015064

  • Required

  • 資料上傳的時間戳
    （Unix epoch time）

8

ac_power_meter_output_kwh

  • float

  • non-negative

310346.316000

  • Required

  • 台電售電總仟瓦小時

9

ac_power_meter_input_kwh

  • float

  • non-negative

1234.56

  • Optional

  • 台電購電總仟瓦小時

10

ac_power_meter_output_kvarh

  • float

  • non-negative

2345.12

  • Optional

  • 總售電 kVArh

Example 

{
  "gatewayId": "{{gatewayId}}",
  "meterId": "{{meterId}}",
  "deviceUuid": "{{deviceUuid}}",
  "customerId": "{{customerId}}",
  "routeBMacAddr": "{{routeBMacAddr}}",
  "itemTimestamp": 1728015180,
  "_uploadedTime": 1728015064,
  "ac_power_meter_output_kwh": 310346.316,
  "ac_power_meter_input_kwh": 1234.56,
  "ac_power_meter_output_kvarh": 2345.12
}

Resend Data

① Operate device command for resending data

Summary

① Operate device command for resending data

Path

POST /v1/devices/<dsn>/commands

Description

Through this API, you can issue a command to a specific GW to resending data.

Permission

  • Business::Admin, and Business::Operator (if the device is under the same business)

  • Business::Dealer (if the device attached the dealer tag)

  • EndUser (if you are the device owner)

Request Header

Authorization

<accessToken>

Request Params

Example Value
JSON
dsn: "NDTEST1234567"

Schema
JSON
dsn: string(NextDrive defined DSN)

Request Body

Content Type

application/json

Example Value
JSON
{
  "invokeType": "async",
  "identifier": "externalMqttService",
  "params": {
    "command": "resendData",
    "startTime": "2025-02-18T11:30:00+08:00",
    "endTime": "2025-02-18T12:30:00+08:00"
  }
}

Schema
JSON
{
  "invokeType": "async"                              | required,
  "identifier": "externalMqttService"                | required,
  "params": json object,
    {
      "command": "resendData"                        | required,
      "startTime": string (refer to ISO 8601 format) | required,
      "endTime": string (refer to ISO 8601 format,   | required
                 up to 7 days after the startTime)
    }
}

Note

Since “Resend Data” follows a fire-and-forget communication pattern, we don't need to call the Get the details of resending data API to check the command result, even when using invokeType = async. However, it's fine to retrieve the command result through the API if you want to.


200

Response

Status Code

200

Description

Successful request

Content Type

application/json

Example Value
JSON
{
  "code": 20000,
  "message": "successful request",
  "data": {
    "sessionId": "7b2e0ca2-60d0-4a92-9cc0-0befe917d4c9",
    "requestTime": 1671494400000
  }
}

Schema
JSON
{
  "code": integer,
  "message": string,
  "data": {
    "sessionId": string,
    "requestTime": timestamp
  }
}
400

Response

Status Code

400

Description

Invalid parameter

Content Type

application/json

Example Value
JSON
{
  "requestId": "e867850b-0c81-43f4-ad58-459a54c65ec5",
  "code": 40001,
  "message": "Invalid parameter: XXXXXX"
}

Schema

Invalid Parameter Error
403

Response

Status Code

403

Description

Forbidden

Content Type

application/json

Example Value
JSON
{
  "requestId": "e867850b-0c81-43f4-ad58-459a54c65ec5",
  "code": 40300,
  "message": "Forbidden: XXXXXX"
}

Schema

  1. No permission to operate on the device.

  2. The device does not support the specified command.

  3. params do not match the value range of the specified command.

  4. The device is offline.
404

Response

Status Code

404

Description

Not found

Content Type

application/json

Example Value
JSON
{
  "requestId": "e867850b-0c81-43f4-ad58-459a54c65ec5",
  "code": 40400,
  "message": "Not found: dsn doesn't exist"
}

Schema

The device is not found.
500

Response

Status Code

500

Description

System error

Content Type

application/json

Example Value

 
{
  "requestId": "e867850b-0c81-43f4-ad58-459a54c65ec5",
  "code": 50000,
  "message": "Something went wrong"
}

Schema

Internal server error such as database error, redis error, …etc.


② Get the details of resending data

Summary

② Get the details of resending data

Path

GET /v1/devices/<dsn>/commands/sessions/<sessionId>

Description

Through this API, you can check the execution status of the resend data setting of a specific gateway.

Permission

  • Business::Admin, and Business::Operator (if the device is under the same business)

  • Business::Dealer (if the device attached the dealer tag)

  • EndUser (if you are the device owner)

Request Header

Authorization

<accessToken>

Request Params

Example Value
JSON
sessionId: "abbb3398-7157-4609-9ddc-629d7704d292"

Schema
JSON
sessionId: string(UUID format)

Note

Records are retained for only 3 months.
200

Response

Status Code

200

Description

Successful request

Content Type

application/json

Example Value
No Ack, no Result
JSON
{
  "code": 20000,
  "message": "Successful Request",
  "data": {
    // Command info
    "sessionId": "abbb3398-7157-4609-9ddc-629d7704d292",
    "invokeType": "async",
    "identifier": "externalMqttService",

    // Device info
    "dsn": "NDTEST1234567",
    "model": "Atto",
    
    // Command operation request
    "requestTime": 1671494400000,
    "request": {
      "command": "resendData",
      "startTime": "2025-02-18T11:30:00+08:00",
      "endTime": "2025-02-18T12:30:00+08:00"
    },
    
    // Command operation ack
    "ackTime": null,
    "ack": null,
    "ackError": null,
    
    // Command operation result
    "responseTime": null,
    "response": null
  }
}
Ack received, no Result
JSON
{
  "code": 20000,
  "message": "Successful Request",
  "data": {
    // Command info
    "sessionId": "abbb3398-7157-4609-9ddc-629d7704d292",
    "invokeType": "async",
    "identifier": "externalMqttService",

    // Device info
    "dsn": "NDTEST1234567",
    "model": "Atto",
    
    // Command operation request
    "requestTime": 1671494400000,
    "request": {
      "command": "resendData",
      "startTime": "2025-02-18T11:30:00+08:00",
      "endTime": "2025-02-18T12:30:00+08:00"
    },
    
    // Command operation ack
    "ackTime": 1671494400000,
    "ack": {
      "dataCount": 100,
    },
    "ackError": null,  // optional field, use it when failure
    
    // Command operation result
    "responseTime": null,
    "response": null
  }
}
Ack received, Result received
JSON
{
  "code": 20000,
  "message": "Successful Request",
  "data": {
    // Command info
    "sessionId": "abbb3398-7157-4609-9ddc-629d7704d292",
    "invokeType": "async",
    "identifier": "externalMqttService",

    // Device info
    "dsn": "NDTEST1234567",
    "model": "Atto",
    
    // Command operation request
    "requestTime": 1671494400000,
    "request": {
      "command": "resendData",
      "startTime": "2025-02-18T11:30:00+08:00",
      "endTime": "2025-02-18T12:30:00+08:00"
    },
    
    // Command operation ack
    "ackTime": 1671494400000,
    "ack": {
      "dataCount": 100,
    },
    "ackError": null,  // optional field, use it when failure
    
    // Command operation result
    "responseTime": 1671494400000,
    "response": {
      "uploadedDataSet": 50, // it may differ from dataCount because each upload consists of a dataset containing meter data at a specific timestamp.
      "lastUploadedTimestamp": "2024-12-23T11:31:00+08:00",
      "error": "error message" 
    }
  }
}

Schema
JSON
{
  "code": integer,
  "message": string,
  "data": {
    // Command info
    "sessionId": string(UUID format),
    "invokeType": string(<"async"|"sync">),
    "identifier": string(refer to Thing Protocol),

    // Device info
    "dsn": string(NextDrive defined DSN),
    "model": string(NextDrive defined model),
    
    // Command operation request
    "requestTime": timestamp,
    "request": json object | nullable,
    
    // Command operation ack
    "ackTime": timestamp | nullable,
    "ack": json object | nullable,
    "ackError": string | nullable,
    
    // Command operation result
    "responseTime": timestamp | nullable,
    "response": json object | nullable
  }
}
400

Response

Status Code

400

Description

Invalid parameter

Content Type

application/json

Example Value
JSON
{
  "requestId": "e867850b-0c81-43f4-ad58-459a54c65ec5",
  "code": 40000,
  "message": "Invalid parameter: XXXXXX"
}

Schema

Invalid sessionId format
403

Response

Status Code

403

Description

Forbidden

Content Type

application/json

Example Value
JSON
{
  "requestId": "e867850b-0c81-43f4-ad58-459a54c65ec5",
  "code": 40300,
  "message": "Forbidden: XXXXXX"
}

Schema

No permission to operate on the device.
404

Response

Status Code

404

Description

Not found

Content Type

application/json

Example Value
JSON
{
  "requestId": "e867850b-0c81-43f4-ad58-459a54c65ec5",
  "code": 40400,
  "message": "Not found: sessionId doesn't exist"
}

Schema

  1. The device is not found.

  2. The sessionId is not found.
500

Response

Status Code

500

Description

System error

Content Type

application/json

Example Value

 
{
  "requestId": "e867850b-0c81-43f4-ad58-459a54c65ec5",
  "code": 50000,
  "message": "Something went wrong"
}

Schema

Internal server error such as database error, redis error, …etc.