Token｜裝置管理

API Domain

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

Gateway Registration

① Gateway Registration

Summary

① Gateway Registration

Path

POST /v1/registrations

Description

Through this API, you can register the 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 body

Example Value
JSON
{
  "pid": "3103b9e4-e9b2-470a-88f2-302935562270",
  "singleDeviceDsn": "NDTEST1234567",
  "name": "GENERATE_BY_RAILS"
  "userUuid": "0dedaa75-5f0a-4342-8204-1f3fa55a210b"
}

Schema
JSON
{
  "pid": string,
  "singleDeviceDsn": string,
  "name": string, // optional
  "userUuid": string // only required for Business::**
}

Note

At least one of pid or singleDeviceDsn must be provided.


200

Response

Status Code

200

Description

Successful request

Content Type

application/json

Example Value
JSON
{
  "code": 20000,
  "message": "Successful Request"
  "data": {
      "dsn": "ND8FOX0203267",
      "userUuid": "ea908f0c-5d3c-43ce-9a46-486f418e18b4",
      "registrationUuid": "8e9b3ae5-9347-4c94-80a8-9837b45b9951"
  }
}

Schema
JSON
{
  "code": integer,
  "message": sting,
  "data": {
      "dsn": string,
      "userUuid": string,
      "registrationUuid": string
  }
}
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 Parameter
401

Response

Status Code

401

Description

Unauthorized

Content Type

application/json

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

Schema

  • Access token login failed

  • Unfinished shipment

  • The API request user, target user, and device do not belong to the same business

  • Single device was registered by others

  • Single device was registered
403

Response

Status Code

403

Description

Forbidden

Content Type

application/json

Example Value
JSON
{
  "requestId": "e867850b-0c81-43f4-ad58-459a54c65ec5",
  "code": 40301,
  "message": "Forbidden: No sufficient permissions"
}

Schema

  • No sufficient permissions

  • Single device doesn't exist
404

Response

Status Code

404

Description

Not found

Content Type

application/json

Example Value
JSON
{
  "requestId": "2CC8A71F-B6CC-4CCD-9961-52D4CD50144C",
  "code": 40400,
  "message": "Not found"
}

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": "Server error"
}

Schema

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

Device Management

① Get Device List

Summary

① Get Device List

Path

GET /v1/devices/{dsn}/topology

Description

Through this API, you can get the topology and identifier of the device list.

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)


200

Response

Status Code

200

Description

Successful request

Content Type

application/json

Example Value
JSON
{
  "code": 20000,
  "message": "Successful request",
  "data": {
    "singleDeviceDsn": "ND8FOX0000001",
    "name": "Atto-5e4604",
    "model": "Atto",
    "brand": "NextDrive",
    "nodeDevices": [
      {
        "dsn": "VG69D21000001",
        "name": "NextDrive Office TaipowerMeter",
        "model": "TaipowerMeter",
        "brand": "Taiwan Power Company"
      }
    ]
  }
}

Schema
JSON
{
  "code": integer,
  "message": string,
  "data": {
    "singleDeviceDsn": string,
    "name": string,
    "model": string,
    "brand": string,
    "nodeDevices": [
      {
        "dsn": string,
        "name": string,
        "model": string,
        "brand": string
      }
    ]
  }
}

Note

“nodeDevices” are listed in reversed order by their asscociation time to the gateway.
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 dsn format
401

Response

Status Code

401

Description

Unauthorized

Content Type

application/json

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

Schema

Unauthorized
403

Response

Status Code

403

Description

Forbidden

Content Type

application/json

Example Value
JSON
{
  "requestId": "e867850b-0c81-43f4-ad58-459a54c65ec5",
  "code": 40301,
  "message": "Forbidden: No sufficient permissions"
}

Schema

No sufficient permissions
404

Response

Status Code

404

Description

Not found

Content Type

application/json

Example Value
JSON
{
  "requestId": "2CC8A71F-B6CC-4CCD-9961-52D4CD50144C",
  "code": 40400,
  "message": "Not found"
}

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": "Server error"
}

Schema

Internal server error such as database error, redis error, …etc.
② Get Device Detail

Summary

② Get Device Detail

Path

GET /v1/devices/{dsn}

Description

Through this API, you can get the details of the basic information of the device.

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)


200

Response

Status Code

200

Description

Successful request

Content Type

application/json

Example Value
JSON
{
  "code": 20000,
  "message": "Successful Request",
  "data": {
    "dsn": "ND8FOX0203267",
    "pid": "JACIDB0987D", // single device ONLY;
    "hardwareId": "ca721224-1096-47ae-b9a6-b38cd51ae3fa",
    "name": "name",
    "firmwareSku": "Cube-J",
    "firmwareVersion": "v1.3433",
    "latestFirmwareVersion": "v1.4001", // single device ONLY;
    "model": "Cube",
    "brand": "NextDrive",
    "state": {},
    "connectionInfo": { // node-device ONLY;
      "meterId": "TT21339754",
      "formulaMeter": "1",
      "macAddress": "1CAE3E71000008ED",
      "rootIpv6": "2001:db8::1",
      "networkName": "ND-FAN-BB3646",
      "dlmsType": "wisun_fan"
    }
  }
}

Schema
JSON
{
  "code": integer,
  "message": string,
  "data": {
    "dsn": string,
    "pid": string, // single device ONLY;
    "hardwareId": string,
    "name": string,
    "firmwareSku": string,
    "firmwareVersion": string,
    "latestFirmwareVersion": string, // single device ONLY;
    "model": string,
    "brand": string,
    "state": {},
    "connectionInfo": { // node-device ONLY;
      "meterId": string,
      "formulaMeter": string,
      "macAddress": string,
      "rootIpv6": string,
      "networkName": string,
      "dlmsType": string
    }
  }
}
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 dsn format
401

Response

Status Code

401

Description

Unauthorized

Content Type

application/json

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

Schema

Unauthorized
403

Response

Status Code

403

Description

Forbidden

Content Type

application/json

Example Value
JSON
{
  "requestId": "e867850b-0c81-43f4-ad58-459a54c65ec5",
  "code": 40301,
  "message": "Forbidden: No sufficient permissions"
}

Schema

No sufficient permissions
404

Response

Status Code

404

Description

Not found

Content Type

application/json

Example Value
JSON
{
  "requestId": "2CC8A71F-B6CC-4CCD-9961-52D4CD50144C",
  "code": 40400,
  "message": "Not found"
}

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": "Server error"
}

Schema

Internal server error such as database error, redis error, …etc.
③ Get Device Status

Summary

③ Get Device Status

Domain

https://ioe-api.nextdrive.io

Path

GET /css/v1/connection-status?dsn={dsn1,dsn2,…,dsn10}

Description

Through this API, you can get the device's connection status information.

Permission

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

  • Business::Dealer (if the device is under the same business)

  • EndUser (if you are the device owner)

Request Header

Authorization

<accessToken>

Request Params

Example Value
JSON
dsn=ND8FOX0203908,ND8FOX0275908

Schema
JSON
dsn=dsn1,dsn2,…,dsn10


200

Response

Status Code

200

Description

Successful request

Content Type

application/json

Example Value
JSON
{
  "code": 20000,
  "message": "Successful Request",
  "data": {
    "devices": [
      {
        "dsn": "3aef97c4-ab52-4d21-a66f-1c3c2bab7177",
        "onlineStatus": "ONLINE"
      }
    ]
  }
}

Schema
JSON
{
  "code": integer,
  "message": string,
  "data": {
    "devices": [
      {
        "dsn": string,
        "onlineStatus": string
      }
    ]
  }
}
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: only support 10 devices in the one request"
}

Schema

only support 10 devices in the one request
401

Response

Status Code

401

Description

Unauthorized

Content Type

application/json

Example Value
JSON
{
  "requestId": "e867850b-0c81-43f4-ad58-459a54c65ec5",
  "code": 40100,
  "message": "Unauthorized"
}
500

Response

Status Code

500

Description

System error

Content Type

application/json

Example Value

 
{
  "requestId": "e867850b-0c81-43f4-ad58-459a54c65ec5",
  "code": 50000,
  "message": "Server error"
}

Schema

Internal server error such as database error, redis error, …etc.
④ Upload Gateway Log

Summary

④ Upload Gateway Log

Path

POST /v1/devices/<singleDeviceDsn>/commands/upload-log

Description

Through this API, you can send a command to a specific gateway to upload the log.

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>

Parameter

Example Value
JSON
dsn: "NDTEST1234567"

Schema
JSON
dsn: string(NextDrive defined DSN)

Note

  • 可能掉值原因如下

    • 電表 offline

    • 電表金鑰驗證失敗

    • 組網失敗

    • GW OTA 執行

    • LTE 連線問題（電信商問題等）

  • 基於下列背景，GW Log 上傳的 Sequence 設計如下圖所示：

    • 電表數據不上傳至 ND 的 MQTT Server 或 Cloud，若發生問題，僅貴司能即時掌握相關資訊。

    • GW Log 可儲存的紀錄有限 ※，較適合在問題發現當下即由系統下達 GW Log 上傳指令，避免 GW Log 因書信/通訊往來，導致作業時間延遲，使得 GW Log 被洗掉無法釐清問題。

      • 可保存容量約 14 MB

      • 1 GW 2 電表狀況下，約可保留 4 天 Log

    • GW Log 剖析 Know How 較難由貴司執行，因此不適合直接上傳至貴司 MQTT Server。

Untitled Diagram-1735054078348.drawio.png


200

Response

Status Code

200

Description

Successful request

Content Type

application/json

Example Value
JSON
{
  "code": 20000,
  "message": "successful request",
  "data": {}
}

Schema
JSON
{
  "code": int,
  "message": string,
  "data": object
}
400

Response

Status Code

400

Description

Invalid parameter

Content Type

application/json

Example Value
JSON
{
  "code": 40000,
  "message": "Invalid parameter: XXXXXX"
}

Schema

  1. not allowed command

  2. invalid body schema
401

Response

Status Code

401

Description

permission denied

Content Type

application/json

Example Value
JSON
{
  "code": 40102,
  "message": "permission denied"
}

Schema


500

Response

Status Code

500

Description

System error

Content Type

application/json

Example Value
JSON
{
  "code": 50000,
  "message": "Server error: XXXXXX"
}

Schema