Key｜金鑰申請與裝置關聯

通用性說明

API Domain 與認證

https://api-eg3.nextdrive.io

採取 API Key 認證，請於 Request Header 添加 `Authorization: Bearer <API_KEY>`

API 文件

API ⑦ - 智慧電表金鑰申請與關連（硬體安裝資訊提供）

Summary

智慧電表金鑰申請與關連（硬體安裝資訊提供）

Path

PUT /api/v1/installation/{hemsNo}

Description

SI 呼叫此 API 後，聯齊將代為處理下列事宜：

  1. 電表金鑰申請

  2. 電表關聯

Request Body

Content Type

application/json

Example Value
JSON
{
  "meterId": "<表號>",
  "hanMacAddress": "<Route-B Mac Address>",
  "gatewayPID": "<Gateway PID>",
  "installTime": "Route-B 裝時間"
}

Schema
JSON
{
  "meterId": string,
  "hanMacAddress": string,
  "gatewayPID": string,
  "installTime": ISO date string
}

Request Params

Example Value
JSON
hemsNo: "20250402-0001"

Schema
JSON
hemsNo: string(NextDrive defined DSN)

Note

  • Route-B Mac Address 為 16 碼應寫英文與數字，不包含冒號

  • 表號（meterId）資訊請於現場佈建時確認抄寫，以作為此 API 呼叫之依據。

  • 表號由2碼英文、8碼數字組成，其位置如下圖所示
    [表號範例] GT99000262

image-20250325-041356.png

Response

Status Code

200

Description

Success

Content Type

application/json

Example Value
JSON
{
  "code": 20000,
  "message": "Successful request",
  "data": {
    "tpcNo": "<電號>",
    "meterId": "<表號>",
    "hanMacAddress": "<Route-B Mac Address>",
    "gatewayPID": "<Gateway PID>"
  }
}

Schema
JSON
{
  "code": integer,
  "message": string,
  "data": {
    "tpcNo": string,
    "meterId": string,
    "hanMacAddress": string,
    "gatewayPID": string
  }
}

Response

Status Code

400

Description

Invalid parameter.

Content Type

application/json

Example Value
JSON
{
  "code": 40000,
  "message": "invalid parameter: xxxxxx"
}

Schema
JSON
{
  "code": integer,
  "message": string
}

Note

  1. GatewayPID(A0C50CC4B73A9D8B1) not found.

  2. Gateway (A0C50CC4B73A9D8B1) user is not belong to same business.

Response

Status Code

403

Description

Forbidden.

Content Type

application/json

Example Value
JSON
{
  "code": 40300,
  "message": "forbidden: xxxxxx"
}

Schema
JSON
{
  "code": integer,
  "message": string
}

Note

  1. meter meter_id_0320 is without ak_h, guk_h, multiplier

  2. meter meter_id_0320 already associated

Response

Status Code

404

Description

Resource not found.

Content Type

application/json

Example Value
JSON
{
  "code": 40400,
  "message": "Not found: hemsNo 20250320-0001 not found."
}

Schema
JSON
{
  "code": integer,
  "message": string
}

API ⑧ - 置換硬體－閘道器

Summary

置換硬體－閘道器

Path

PUT /api/v1/installation/gateways

Description

若 Gateway 因硬體故障等因素需進行更換，SI 可透過呼叫此 API 更換硬體安裝資訊

Request Body

Content Type

application/json

Example Value
JSON
{
  "oriGatewayPID": "<Original Gateway PID>",
  "newGatewayPID": "<New Gateway PID>"
}

Schema
JSON
{
  "oriGatewayPID": string,
  "newGatewayPID": string
}

Response

Status Code

200

Description

Success

Content Type

application/json

Example Value
JSON
{
  "code": 20000,
  "message": "Successful request",
  "data": {
    "list": [
      {
        "hemsNo": "<用戶申請代碼>",
        "tpcNo": "<電號>",
        "meterId": "<表號>",
        "hanMacAddress": "<Route-B Mac Address>",
        "gatewayPID": "<Gateway PID>"
      }
    ]
  }
}

Schema
JSON
{
  "code": integer,
  "message": string,
  "data": {
    "list": [
      {
        "hemsNo": string,
        "tpcNo": string,
        "meterId": string,
        "hanMacAddress": string,
        "gatewayPID": string
      }
    ]
  }
}

Note


Response

Status Code

403

Description

Forbidden.

Content Type

application/json

Example Value
JSON
{
  "code": 40300,
  "message": "forbidden: xxxxxx"
}

Schema
JSON
{
  "code": integer,
  "message": string
}

Note

  1. oriGatewayPID(<oriGatewayPID>) is not existed.

  2. oriGatewayPID(<oriGatewayPID>) is not registered

  3. newGatewayPID(<newGatewayPID>) is not existed.

  4. newGatewayPID(<newGatewayPID>) is not registered.

  5. newGatewayPID(<newGatewayPID>) has associated devices

  6. oriGatewayPID(<oriGatewayPID>) is not belong to same business.

  7. newGatewayPID(<newGatewayPID>) is not belong to same business.


API ⑨ - 置換硬體－Route B 通訊模組

Summary

置換硬體－Route B 通訊模組

Path

PUT /api/v1/installation/hanMacAddress

Description

若 Route B 因硬體故障等因素需進行更換，SI 可透過呼叫此 API 更換硬體安裝資訊

Request Body

Content Type

application/json

Example Value
JSON
{
  "oriHanMacAddress": "<Original Route-B Mac Address>",
  "newHanMacAddress": "<New Route-B Mac Address>"
}

Schema
JSON
{
  "oriHanMacAddress": string,
  "newHanMacAddress": string
}

Response

Status Code

200

Description

Success

Content Type

application/json

Example Value
JSON
{
  "code": 20000,
  "message": "Successful request",
  "data": {
        "hemsNo": "<用戶申請代碼>",
        "tpcNo": "<電號>",
        "meterId": "<表號>",
        "hanMacAddress": "<Route-B Mac Address>",
        "gatewayPID": "<Gateway PID>"
  }
}

Schema
JSON
{
  "code": integer,
  "message": string,
  "data": {
        "hemsNo": string,
        "tpcNo": string,
        "meterId": string,
        "hanMacAddress": string,
        "gatewayPID": string
  }
}

Note


Response

Status Code

404

Description

Resource not found.

Content Type

application/json

Example Value
JSON
{
  "code": 40400,
  "message": "Not found: Route B with hanMacAddress <oriHanMacAddress> not found"
}

Schema
JSON
{
  "code": integer,
  "message": string
}

API ⑩ - 置換電表金鑰

台電 API 文件已提供但有缺漏，實作細節討論中

API ⑪ - 註銷 Route B 服務

Summary

註銷 Route B 服務

Path

DELETE /api/v1/installation/hanMacAddress/{hanMacAddress}

Description

SI 呼叫此 API 後，可註銷特定用戶的 Route B 服務

Request Body

Content Type

application/json

Example Value
JSON
N/A

Schema
JSON
N/A

Request Params

Example Value
JSON
hnaMacAddress: "1CAE3E7100000127"

Schema
JSON
hnaMacAddress: "16-bit uppercase letters and numbers, no colon"

Response

Status Code

200

Description

Success

Content Type

application/json

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

Schema
JSON
{
  "code": integer,
  "message": string
}

Note


Response

Status Code

404

Description

Resource not found.

Content Type

application/json

Example Value
JSON
{
  "code": 40400,
  "message": "Not found: Route B with hanMacAddress <hanMacAddress> not found"
}

Schema
JSON
{
  "code": integer,
  "message": string
}