API使用手册 | 海为学院

使用 Haiwell APIs

Haiwell APIs 允许开发者访问和操作资源。本章将叙述如何正确的调用 API。

开发前须知

序号	注意事项
1	在调用 Haiwell APIs 前，确保已获取 API 访问凭证，并加入到请求 Header 中。
2	在调用服务端 API 前，确保你已了解调用频率限制。
3	查询服务端错误码表，了解排查建议。
4	可以使用 Postman 进行接口调试和示例代码查看。

APIs 协议说明

Protocols： HTTPS
Host： openapi.haweill.com
Accepts： application/json
Responds With： application/json

Host 将根据服务部署而定，这里的值为示例

请求地址

所有的 API 请求都必须通过 HTTPS 发出,请求的基础 URL 格式为：{{Protocols}}://{{Host}}/{{uri}} 具体 API 请求地址。

例如：查询用户详情请求地址为https：//openapi.haiwell.com/api/v1/users/{user_id}

请求参数

每次请求 API 时，均需提供公共请求参数，具体如下：

参数	参数类型	数据类型	是否必需	描述
Authorization	Header	String	是	访问凭证。格式为：`Bearer [ACCESS TOKEN]`

请求头部示例：

Authorization: Bearer [ACCESS TOKEN]

API 调用流程说明

应用申请访问凭证和发起请求的流程如下：

第三方应用服务器向 haiwel API 服务器发起申请访问 token 请求并且携带 Client ID 和 Client Secret
API 服务器验证 Client ID 和 Client Secret 信息是否正确
验证成功后返回访问 access_token 和 refresh_token
使用 refresh_token 续签新的 access_token
第三方应用服务器发起业务请求，并且携带访问 access_token
API 服务器验证是否存在访问令牌，然后验证访问令牌的有效性。
转发请求给 Haiwell 业务服务器
Haiwell 业务服务器将处理后的结果返回给 Haiwell API 服务器
Haiwell API 服务器将响应结果透传给第三方应用服务器

API 访问凭证（token）

访问凭证(access_token)

对 API 发出的每个 HTTP 请求都必须经过身份认证。此操作是为了保证访问服务的客户端是否为系统已登记的用户身份认证。

在调用 API 之前，您需要从企业管理平台中开发者模块创建 Client ID 与 Client Secret，用于申请访问 access_token。

Client 授权方式只适用于服务器之间的身份认证。如果在开放客户端使用（如：移动 APP），就存在安全风险，Client ID 和访问令牌可能会被盗用。

刷新访问凭证(refresh_token)

对 API 发出的每个 HTTP 请求都必须经过身份认证，access_token 有效期较短，refresh_token 刷新生成新 access_token，无需 Client ID 与 Client Secret 防止被盗用

申请访问凭证

请求方法

POST

请求地址

/api/v1/oauth2/token

请求参数

参数	参数类型	数据类型	是否必需	描述
Credentials	Header	String	是	base64Encode(clientID:secret)，以冒号连接 Client ID 和 Client Secret，然后进行 Base64 编码

HTTP 状态码

返回值	描述
200	操作成功，详见响应参数
500	服务端异常，详见异常响应参数

业务错误码

返回值	描述
10000	客户端传参异常，详见异常响应参数
10016	无效 Client ID 和 Client Secret
10018	功能模块 API 无权调用
30029	当前接口业务限流，请稍后重试
50000	服务端异常

响应参数

参数	数据类型	描述
code	Long	成功返回码默认 0
reason	String	服务端定义的标签，用于业务快速定位问题
data	object	数据结构体
- data.access_token	object	访问令牌对象
-- data.access_token.token	String	访问令牌值
-- data.access_token.expire	String	访问令牌过期时间，格式为 ISO 8601 日期时间字符串
- data.refresh_token	object	刷新令牌对象
-- data.refresh_token.token	String	刷新令牌值
-- data.refresh_token.expire	String	刷新令牌过期时间，格式为 ISO 8601 日期时间字符串

异常响应参数

参数	数据类型	描述
error_msg	String	表示一个错误代码字符串，可以用于对错误进行分类，并对错误进行处理
code	String	服务端定义的错误码，用于快速定位问题
reason	String	服务端定义的标签，用于业务快速定位问题

请求消息示例

POST /api/v1/oauth2/token HTTP/1.1
Content-Type: application/json
Credentials: czZCaGRSa3F0MzpnWDFmQmF0M2JW=+---
{
}

响应参数示例

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
    "code": 0,
    "reason": "OK",
    "data": {
        "access_token": {
            "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJUb2tlblR5cGUiOjEsImV4cGlyZSI6IjIwMjYtMDEtMjZUMTg6MzM6MDEuNDcxODg0NTgzKzA4OjAwIiwiZGF0YSI6eyJlaWQiOjg1OCwiZGV2ZWxvcGVyX2lkIjo0fSwiaXNzIjoiU3lzdGVtIiwiaWF0IjoxNzY5NDIxNzgwLCJqdGkiOiI1ZTkxNTkwNC1lOTMwLTRhOTQtOWFhZC1jOWNiMmJhMzliMzUifQ.D44gh19KBrALRfCtE17FtT0FWojk5ei30LMLoEJszcA",
            "expire": "2026-01-26T18:33:01.471884583+08:00"
        },
        "refresh_token": {
            "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJUb2tlblR5cGUiOjIsImV4cGlyZSI6IjIwMjYtMDItMDJUMTg6MDM6MDAuNDcyMDA1MTE4KzA4OjAwIiwiaXNzIjoiU3lzdGVtIiwiaWF0IjoxNzY5NDIxNzgwLCJqdGkiOiI1ZTkxNTkwNC1lOTMwLTRhOTQtOWFhZC1jOWNiMmJhMzliMzUifQ.WrQGzvSnT6OqY-QelHaZN4H77gSrr_2EPqKxka8UoVg",
            "expire": "2026-02-02T18:03:00.472005118+08:00"
        }
    }
}

业务异常响应参数

HTTP/1.1 200 Bad Request
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
  "error_msg": "Invalid authorized",
  "reason": "INVALID_AUTHORIZED",
  "code": "10016",
}

刷新访问凭证

请求方法

POST

请求地址

/api/v1/oauth2/token-refresh

公共请求参数

参数名称	参数类型	数据类型	是否必填	参数描述
Authorization	Header	String	是	通过 Credentials 获取的 access_token

HTTP 状态码

返回值	描述
200	操作成功，详见响应参数
500	服务端异常

业务错误码

返回值	描述
10010	客户端传参异常，详见异常响应参数
10016	无效 token
10018	功能模块 API 无权调用
30029	当前接口业务限流，请稍后重试
50000	服务端异常

响应参数

参数	数据类型	描述
code	Long	成功返回码默认 0
reason	String	服务端定义的标签，用于业务快速定位问题
data	object	数据结构体
- data.access_token	object	访问令牌对象
-- data.access_token.token	String	访问令牌值
-- data.access_token.expire	String	访问令牌过期时间，格式为 ISO 8601 日期时间字符串

异常响应参数

参数	数据类型	描述
error_msg	String	表示一个错误代码字符串，可以用于对错误进行分类，并对错误进行处理
code	String	服务端定义的错误码，用于快速定位问题
reason	String	服务端定义的标签，用于业务快速定位问题

请求消息示例

POST /api/v1/oauth2/token-refresh HTTP/1.1
Content-Type: application/json
Authorization: Bearer [ACCESS TOKEN]
{
    "refresh_token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJUb2tlblR5cGUiOjEsImV4cGlyZSI6IjIwMjYtMDEtMjdUMTI6MDg6NDQuMzI1NTQ4MTkrMDg6MDAiLCJkYXRhIjxxxxxxxxx"
}

响应参数示例

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
    "code": 0,
    "reason": "OK",
    "data": {
        "access_token": {
            "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJUb2tlblR5cGUiOjEsImV4cGlyZSI6IjIwMjYtMDEtMjdUMTI6MDg6NDQuMzI1NTQ4MTkrMDg6MDAiLCJkYXRhIjp7ImVpZCI6ODU4LCJkZXZlbG9wZXJfaWQiOjR9LCJpc3MiOiJTeXN0ZW0iLCJpYXQiOjE3Njk0ODUxMjMsImp0aSI6IjdlMzhlYWQyLThiMDAtNGJiOS05ZjMyLWM0YTMxOTk1YmZiNSJ9.8ihQsLaMpOOs4YBskvKavQxj8fqA6gZ2s0FbAij7H-M",
            "expire": "2026-01-27T12:08:44.32554819+08:00"
        }
    }
}

API 项目（project）

创建项目

请求方法

POST

请求地址

/api/v1/projects

公共请求参数

参数名称	参数类型	数据类型	是否必填	参数描述
Authorization	Header	String	是	通过 Credentials 获取的 token

请求参数

参数	参数类型	数据类型	是否必需	描述
title	Body	String	是	项目标题，长度必须大于 0 小于 50
remark	Body	String	否	项目备注，长度必须小于 128
storage_time	Body	Int32	否	存储时间，默认30天，选填小于等于 30 天

请求示例

{
  "title": "测试项目",
  "remark": "这是一个测试项目",
  "storage_time": 30
}

HTTP 状态码

返回值	描述
200	操作成功，详见响应参数
429	并发限流
500	服务端异常

业务错误码

返回值	描述
10000	客户端传参异常，详见异常响应参数
10001	公共参数错误
10016	client 下线或者 clientId 不正确（身份不正确）
10018	功能模块 API 无权调用
10019	token 已过期
50000	服务端异常

响应参数

参数	数据类型	描述
code	Int	状态码
-data	Object	响应数据
--data.project_id	Int32	新创建的项目 ID

响应示例

{
  "code": 200,
  "data": {
    "project_id": 12345
  }
}

项目列表

请求方法

GET

请求地址

/api/v1/projects

公共请求参数

参数名称	参数类型	数据类型	是否必填	参数描述
Authorization	Header	String	是	通过 Credentials 获取的 token

请求参数

参数	参数类型	数据类型	是否必需	描述
limit	Query	Long	是	获取的最大记录数，默认为 10，最大 100
offset	Query	Long	是	返回页码默认 1，页码从 1 开始 PS：当前采用分页返回，记录数和页数必需一起传
blur	Query	String	否	模糊查询关键字，长度小于 128，支持按名称搜索

HTTP 状态码

返回值	描述
200	操作成功，详见响应参数
429	并发限流
500	服务端异常

业务错误码

返回值	描述
10000	客户端传参异常，详见异常响应参数
10001	公共参数错误
10016	client 下线或者 clientId 不正确（身份不正确）
10018	功能模块 API 无权调用
10019	token 已过期
50000	服务端异常

响应参数

参数	参数类型	描述
code	Long	成功返回码默认 0
reason	String	服务端定义的标签，用于业务快速定位问题
data	Object	返回数据结构体
- data.total	Long	数据总数
- data.list	Object[]	项目列表
-- data.list[0].project_id	Long	项目 ID
-- data.list[0].project_name	String	项目名称
-- data.list[0].storage_time	Long	项目存储时间(天)
-- data.list[0].project_uuid	String	项目唯一标识
-- data.list[0].project_remark	String	项目备注

异常响应参数

参数	数据类型	描述
error_msg	String	表示一个错误代码字符串，可以用于对错误进行分类，并对错误进行处理
code	String	服务端定义的错误码，用于快速定位问题
reason	String	服务端定义的标签，用于业务快速定位问题

请求消息示例

GET /projects?limit=10&offset=1&blur=项目名字 HTTP/1.1
Host: openapi.haweill.com
Content-Type: application/json

响应消息示例

HTTP/1.1 200
Content-Type: application/json;charset=UTF-8

{
    "code": 0,
    "reason": "OK",
    "data": {
        "total": 0,
        "list": [
            {
                "project_id": 1457,
                "project_name": "test1",
                "project_remark": "",
                "storage_time": 30,
                "project_uuid": "11263"
            },
            {
                "project_id": 1456,
                "project_name": "test1",
                "project_remark": "",
                "storage_time": 1,
                "project_uuid": "11262"
            },
        ]
    }
}

更新项目详情

请求方法

PUT

请求地址

/api/v1/projects/{project_id}

公共请求参数

参数名称	参数类型	数据类型	是否必填	参数描述
Authorization	Header	String	是	通过 Credentials 获取的 token

请求参数

参数	参数类型	数据类型	是否必需	描述
project_id	Path	Long	是	项目 ID
storage_time	body	Long	否	数据存储时间，(天)单位；限制：1~30 天
project_name	body	String	否	项目名称
project_remark	body	String	否	项目备注

HTTP 状态码

返回值	描述
200	操作成功，详见响应参数
429	并发限流
500	服务端异常

业务错误码

返回值	描述
10000	客户端传参异常，详见异常响应参数
20002	项目存在变量无法删除
10016	client 下线或者 clientId 不正确（身份不正确）
10018	功能模块 API 无权调用
10019	token 已过期
50000	服务端异常

响应参数

参数	参数类型	描述
code	Long	成功返回码默认 0
reason	String	服务端定义的标签，用于业务快速定位问题
data	Object	返回数据空结构体

异常响应参数

参数	数据类型	描述
error_msg	String	表示一个错误代码字符串，可以用于对错误进行分类，并对错误进行处理
code	String	服务端定义的错误码，用于快速定位问题
reason	String	服务端定义的标签，用于业务快速定位问题

请求消息示例

GET /projects/{project_id} HTTP/1.1
Host: openapi.haweill.com
Content-Type: application/json

响应消息示例

成功响应

http： HTTP/1.1 200
Content-Type: application/json;charset=UTF-8

{
    "code": 0,
    "reason": "OK",
    "data": {}
}

异常响应

http： HTTP/1.1 200
Content-Type: application/json;charset=UTF-8

{
    "code": 20002,
    "reason": "VARIABLES_NOT_CLEARED",
    "error_msg": "project contains variables not cleared"
}

删除项目

请求方法

DELETE

请求地址

/api/v1/projects/{project_id}

公共请求参数

参数名称	参数类型	数据类型	是否必填	参数描述
Authorization	Header	String	是	通过 Credentials 获取的 token

请求参数

参数	参数类型	数据类型	是否必需	描述
project_id	Path	Long	是	项目 ID

HTTP 状态码

返回值	描述
200	操作成功，详见响应参数
429	并发限流
500	服务端异常

业务错误码

返回值	描述
10000	客户端传参异常，详见异常响应参数
10001	公共参数错误
20002	项目存在工程无法删除
20002	项目存在变量无法删除
10016	client 下线或者 clientId 不正确（身份不正确）
10018	功能模块 API 无权调用
10019	token 已过期
50000	服务端异常

响应参数

参数	参数类型	描述
code	Long	成功返回码默认 0
reason	String	服务端定义的标签，用于业务快速定位问题
data	Object	返回数据空结构体

异常响应参数

参数	数据类型	描述
error_msg	String	表示一个错误代码字符串，可以用于对错误进行分类，并对错误进行处理
code	String	服务端定义的错误码，用于快速定位问题
reason	String	服务端定义的标签，用于业务快速定位问题

请求消息示例

GET /projects/{project_id} HTTP/1.1
Host: openapi.haweill.com
Content-Type: application/json

响应消息示例

成功响应
http： HTTP/1.1 200
Content-Type: application/json;charset=UTF-8

{
    "code": 0,
    "reason": "OK",
    "data": {}
}

异常响应
http： HTTP/1.1 200
Content-Type: application/json;charset=UTF-8

{
    "code": 20002,
    "reason": "VARIABLES_NOT_CLEARED",
    "error_msg": "project contains variables not cleared"
}

创建工程

请求方法

POST

请求地址

/api/v1/webscadas

公共请求参数

参数名称	参数类型	数据类型	是否必填	参数描述
Authorization	Header	String	是	通过 Credentials 获取的 token

请求参数

参数	参数类型	数据类型	是否必需	描述
project_id	body	Long	是	项目 uuid
scada_type	body	Long	否	工程类型 0：普通工程 1：数据可视化
scada_name	body	String	是	工程名称，长度大于 0 且小于 100
scada_remake	body	String	是	工程备注，长度大于 0 且小于 150

HTTP 状态码

返回值	描述
200	操作成功，详见响应参数
429	并发限流
500	服务端异常

业务错误码

返回值	描述
10000	客户端传参异常，详见异常响应参数
10001	公共参数错误
10016	client 下线或者 clientId 不正确（身份不正确）
10018	功能模块 API 无权调用
10019	token 已过期
50000	服务端异常

响应参数

参数	参数类型	描述
code	Long	成功返回码默认 0
reason	String	服务端定义的标签，用于业务快速定位问题
data	Object	返回数据结构体
- data.scada_id	Long	新建工程的 ID

异常响应参数

参数	数据类型	描述
error_msg	String	表示一个错误代码字符串，可以用于对错误进行分类，并对错误进行处理
code	String	服务端定义的错误码，用于快速定位问题
reason	String	服务端定义的标签，用于业务快速定位问题

请求消息示例

POST /webscadas HTTP/1.1
Host: openapi.haweill.com
Content-Type: application/json

{
	"project_id":1,
	"scada_type":1,
	"scada_name":"新工程",
	"scada_remake":"工程详情"
}

响应消息示例

HTTP/1.1 200
Content-Type: application/json;charset=UTF-8

{
	"code":0,
	"reason":"OK",
	"data":{
		"scada_id":1
	}
}

查询工程列表

请求方法

GET

请求地址

/api/v1/webscadas

公共请求参数

参数名称	参数类型	数据类型	是否必填	参数描述
Client-ID	Header	String	是	分配的 clientID
Authorization	Header	Strings	是	通过 Credentials 获取的 token

请求参数

参数	参数类型	数据类型	是否必需	描述
limit	Query	Long	是	获取的最大记录数，默认为 10，最大 100
offset	Query	Long	是	返回页码默认 1，页码从 1 开始 PS：当前采用分页返回，记录数和页数必需一起传
project_id	Query	Long	是	所属项目 id

HTTP 状态码

返回值	描述
200	操作成功，详见响应参数
429	并发限流
500	服务端异常

业务错误码

返回值	描述
10000	客户端传参异常，详见异常响应参数
10001	公共参数错误
10016	client 下线或者 clientId 不正确（身份不正确）
10018	功能模块 API 无权调用
10019	token 已过期
50000	服务端异常

响应参数

参数	参数类型	描述
code	Long	成功返回码默认 0
reason	String	服务端定义的标签，用于业务快速定位问题
data	Object	返回数据结构体
- data.total	Long	数据总数
- data.list	Object[]	工程列表
-- data.list[0].scada_id	Long	工程 ID
-- data.list[0].scada_name	String	工程名称

异常响应参数

参数	数据类型	描述
error_msg	String	表示一个错误代码字符串，可以用于对错误进行分类，并对错误进行处理
code	String	服务端定义的错误码，用于快速定位问题
reason	String	服务端定义的标签，用于业务快速定位问题

请求消息示例

GET /webscadas?limit=10&offset=1&project_id=1 HTTP/1.1
Host: openapi.haweill.com
Content-Type: application/json

响应消息示例

HTTP/1.1 200
Content-Type: application/json;charset=UTF-8

{
	"code":0,
	"data":{
			"ttal":2,
			"list":[
				{
					"scada_id":1,
					"scada_name":"演示项目1"
				},
				{
					"scada_id":2,
					"scada_name":"演示项目2"
				},
			]
	}
}

查询工程详情

请求方法

GET

请求地址

/api/v1/webscadas/{scada_id}

公共请求参数

参数名称	参数类型	数据类型	是否必填	参数描述
Authorization	Header	String	是	通过 Credentials 获取的 token

请求参数

参数	参数类型	数据类型	是否必需	描述
scada_id	path	Long	是	工程 ID

HTTP 状态码

返回值	描述
200	操作成功，详见响应参数
429	并发限流
500	服务端异常

业务错误码

返回值	描述
10000	客户端传参异常，详见异常响应参数
10001	公共参数错误
10016	client 下线或者 clientId 不正确（身份不正确）
10018	功能模块 API 无权调用
10019	token 已过期
50000	服务端异常

响应参数

参数	参数类型	描述
code	Long	成功返回码默认 0
reason	String	服务端定义的标签，用于业务快速定位问题
data	Object	返回数据结构体
- data.scada_id	Long	工程 ID
- data.scada_name	String	工程名称
- data.scada_detail	String	工程详情
-- data.author	String	工程创建者
-- data.page_type	String	工程展示页面类型 pc ｜ mobile

异常响应参数

参数	数据类型	描述
error_msg	String	表示一个错误代码字符串，可以用于对错误进行分类，并对错误进行处理
code	String	服务端定义的错误码，用于快速定位问题
reason	String	服务端定义的标签，用于业务快速定位问题

请求消息示例

GET /webscadas/10487 HTTP/1.1
Host: openapi.haweill.com
Content-Type: application/json

响应消息示例

HTTP/1.1 200
Content-Type: application/json;charset=UTF-8

{
	"code":0,
	"data":{
		"scada_id":1,
		"scada_name":"演示项目1"
		"scada_detail":"工程20211"
	}
}

删除工程

请求方法

DELETE

请求地址

/api/v1/webscadas/{scada_id}

公共请求参数

参数名称	参数类型	数据类型	是否必填	参数描述
Authorization	Header	String	是	通过 Credentials 获取的 token

请求参数

参数	参数类型	数据类型	是否必需	描述
scada_id	path	Long	是	工程 ID

HTTP 状态码

返回值	描述
200	操作成功，详见响应参数
429	并发限流
500	服务端异常

业务错误码

返回值	描述
10000	客户端传参异常，详见异常响应参数
10001	公共参数错误
10016	client 下线或者 clientId 不正确（身份不正确）
10018	功能模块 API 无权调用
10019	token 已过期
50000	服务端异常

响应参数

参数	参数类型	描述
code	Long	成功返回码默认 0
reason	String	服务端定义的标签，用于业务快速定位问题

异常响应参数

参数	数据类型	描述
error_msg	String	表示一个错误代码字符串，可以用于对错误进行分类，并对错误进行处理
code	String	服务端定义的错误码，用于快速定位问题
reason	String	服务端定义的标签，用于业务快速定位问题

请求消息示例

DELETE /webscadas/1 HTTP/1.1
Host: openapi.haweill.com
Content-Type: application/json

响应消息示例

HTTP/1.1 200
Content-Type: application/json;charset=UTF-8

{
	"code":0,
	"reason":"OK"
}

工程信息修改

请求方法

PUT

请求地址

/api/v1/webscadas/{scada_id}

公共请求参数

参数名称	参数类型	数据类型	是否必填	参数描述
Authorization	Header	String	是	通过 Credentials 获取的 token

请求参数

参数	参数类型	数据类型	是否必需	描述
scada_id	path	Long	是	工程 ID
scada_name	body	String	否	工程名称
scada_detail	body	String	否	工程详情

HTTP 状态码

返回值	描述
200	操作成功，详见响应参数
429	并发限流
500	服务端异常

业务错误码

返回值	描述
10000	客户端传参异常，详见异常响应参数
10001	公共参数错误
10016	client 下线或者 clientId 不正确（身份不正确）
10018	功能模块 API 无权调用
10019	token 已过期
50000	服务端异常

响应参数

参数	参数类型	描述
code	Long	成功返回码默认 0
reason	String	服务端定义的标签，用于业务快速定位问题

异常响应参数

参数	数据类型	描述
error_msg	String	表示一个错误代码字符串，可以用于对错误进行分类，并对错误进行处理
code	String	服务端定义的错误码，用于快速定位问题
reason	String	服务端定义的标签，用于业务快速定位问题

请求消息示例

PUT /webscadas/1 HTTP/1.1
Host: openapi.haweill.com
Content-Type: application/json

{
	"scada_name":"更新工程名称",
	"scada_detail":"更新工程详情"
}

响应消息示例

HTTP/1.1 200
Content-Type: application/json;charset=UTF-8

{
	"code":0,
	"reason":"OK"
}

创建工程访问链接

请求方法

POST

请求地址

/api/v1/webscadas/visit

公共请求参数

参数名称	参数类型	数据类型	是否必填	参数描述
Client-ID	Header	String	是	分配的 clientID
Authorization	Header	String	是	通过 Credentials 获取的 token

请求参数

参数	参数类型	数据类型	是否必需	描述
scada_id	body	Long	是	工程 Id
visit_type	body	Long	是	访问页面类型 1:pc ｜ 2:mobile

HTTP 状态码

返回值	描述
200	操作成功，详见响应参数
429	并发限流
500	服务端异常

业务错误码

返回值	描述
10000	客户端传参异常，详见异常响应参数
10001	公共参数错误
10016	client 下线或者 clientId 不正确（身份不正确）
10018	功能模块 API 无权调用
10019	token 已过期
20004	服务端异常
20013	访问页面类型无权限
50000	服务端异常

响应参数

参数	参数类型	描述
code	String	成功返回码默认 0
reason	String	服务端定义的标签，用于业务快速定位问题
data	Object	返回数据结构体
- data.visit_url	Long	工程访问链接

异常响应参数

参数	数据类型	描述
error_msg	String	表示一个错误代码字符串，可以用于对错误进行分类，并对错误进行处理
code	Long	服务端定义的错误码，用于快速定位问题
reason	String	服务端定义的标签，用于业务快速定位问题

请求消息示例

GET /webscadas/10487 HTTP/1.1
Host: openapi.haweill.com
Content-Type: application/json

响应消息示例

HTTP/1.1 200
Content-Type: application/json;charset=UTF-8

{
	"code":0,
	"data":{
		"visit_url":"772383232323231.iotbus.cn.com"
	}
}

工程设计链接

请求方法

GET

请求地址

/api/v1/webscadas/{scada_id}/editor

公共请求参数

参数名称	参数类型	数据类型	是否必填	参数描述
Authorization	Header	String	是	通过 Credentials 获取的 token

请求参数

参数	参数类型	数据类型	是否必需	描述
scada_id	path	Long	是	工程 ID，必须大于 0

HTTP 状态码

返回值	描述
200	操作成功，详见响应参数
429	并发限流
500	服务端异常

业务错误码

返回值	描述
10000	客户端传参异常，详见异常响应参数
10001	公共参数错误
10016	client 下线或者 clientId 不正确（身份不正确）
10018	功能模块 API 无权调用
10019	token 已过期
50000	服务端异常

响应参数

参数	参数类型	描述
code	Long	成功返回码默认 0
reason	String	服务端定义的标签，用于业务快速定位问题
data	Object	返回数据结构体
- data.url	String	工程编辑器访问链接

异常响应参数

参数	数据类型	描述
error_msg	String	表示一个错误代码字符串，可以用于对错误进行分类，并对错误进行处理
code	Long	服务端定义的错误码，用于快速定位问题
reason	String	服务端定义的标签，用于业务快速定位问题

请求消息示例

GET /webscadas/10487/editor HTTP/1.1
Host: openapi.haweill.com
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

响应消息示例

HTTP/1.1 200
Content-Type: application/json;charset=UTF-8

{
	"code":0,
	"reason":"OK",
	"data":{
		"url":"https://editor.haweill.com/editor?projectId=12345&scadaId=10487&token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
	}
}

虚拟设备列表

⚠️ 注意：设备必须企业平台项目中心-终端关联实体设备 请求方法

GET

请求地址

/api/v1/projects/devices

公共请求参数

参数名称	参数类型	数据类型	是否必填	参数描述
Authorization	Header	String	是	通过 Credentials 获取的 token

请求参数

参数	参数类型	数据类型	是否必需	描述
project_id	Query	Long	是	项目 ID，必须大于 0
limit	Query	Long	是	获取的最大记录数，必须大于 0
offset	Query	Long	是	返回页码，必须大于 0，页码从 1 开始

HTTP 状态码

返回值	描述
200	操作成功，详见响应参数
429	并发限流
500	服务端异常

业务错误码

返回值	描述
10000	客户端传参异常，详见异常响应参数
10001	公共参数错误
10016	client 下线或者 clientId 不正确（身份不正确）
10018	功能模块 API 无权调用
10019	token 已过期
50000	服务端异常

响应参数

参数	参数类型	描述
code	Long	成功返回码默认 0
reason	String	服务端定义的标签，用于业务快速定位问题
data	Object	返回数据结构体
- data.total	Long	数据总数
- data.list	Object[]	设备列表
-- data.list[0].device_id	Long	真实设备ID
-- data.list[0].is_bind	Long	是否绑定 1：绑定 0:未绑定
-- data.list[0].device_code	String	设备编码
-- data.list[0].device_name	String	设备名称
-- data.list[0].device_remark	String	设备备注
-- data.list[0].datasource_id	String	虚拟设备ID
-- data.list[0].datasource_name	String	虚拟设备名称

异常响应参数

参数	数据类型	描述
error_msg	String	表示一个错误代码字符串，可以用于对错误进行分类，并对错误进行处理
code	Long	服务端定义的错误码，用于快速定位问题
reason	String	服务端定义的标签，用于业务快速定位问题

请求消息示例

GET /projects/devices?project_id=12345&limit=10&offset=1 HTTP/1.1
Host: openapi.haweill.com
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

响应消息示例

HTTP/1.1 200
Content-Type: application/json;charset=UTF-8

{
    "code": 0,
    "reason": "OK",
    "data": {
        "total": 3,
        "list": [
            {
                "device_id": 1221212510,
                "is_bind": 1,
                "datasource_id": "11292-3",
                "datasource_name": "红向处至候",
                "device_name": "Enterprise equipment",
                "device_code": "7102259159010100025",
                "device_remark": "test"
            },
            {
                "device_id": 1221212510,
                "is_bind": 1,
                "datasource_id": "11292-4",
                "datasource_name": "内回建干其",
                "device_name": "Enterprise equipment",
                "device_code": "7102259159010100025",
                "device_remark": "test"
            },
        ]
    }
}

添加项目虚拟设备

请求方法

POST

请求地址

/proxy/ecloud/api/web/project/{pid}/device

请求参数

参数	参数类型	数据类型	是否必需	描述
pid	path	String	是	项目 uuid
-deviceList	body	Array	是	设备列表
--deviceList[0].title	String	是	虚拟设备名称
--deviceList[0].actualId	String	是	实际设备的 ID
--deviceList[0].pn	String	是	设备 PN 码
--deviceList[0].des	String	否	虚拟设备备注
--deviceList[0].type	Int	否	设备类型：0 外部设备, 1 内部变量

响应参数

参数	数据类型	描述
result	Array	结果列表

result 内部结构：

参数	数据类型	描述
title	String	添加的设备名称
actualId	String	添加的设备 ID
result	Int	结果：1 成功, 2 失败, 3 名称重复, 4 绑定失败
message	String	结果消息
pn	String	设备 PN 码

请求消息示例

POST /api/web/project/12345/device HTTP/1.1
Content-Type: application/json

{
	"deviceList": [
		{
			"title": "虚拟设备1",
			"actualId": "physic_dev_001",
			"pn": "HW-PLC-001",
			"des": "备注信息",
			"type": 0
		}
	]
}

响应消息示例

HTTP/1.1 200
Content-Type: application/json;charset=UTF-8

{
	"hwcode": 0,
	"hwreason": "OK",
	"hwdata": {
		"result": [
			{
				"title": "虚拟设备1",
				"actualId": "physic_dev_001",
				"result": 1,
				"message": "success",
				"pn": "HW-PLC-001"
			}
		]
	}
}

更新虚拟设备

请求方法

POST

请求地址

/proxy/ecloud/api/web/project/:pid/device/update

请求参数

参数	参数类型	数据类型	是否必需	描述
pid	uri	String	是	项目 ID
id	body	String	是	虚拟设备 ID
title	body	String	是	虚拟设备名称
des	body	String	否	虚拟设备备注
HTTP 状态码

返回值	描述
200	操作成功，详见响应参数
429	并发限流
500	服务端异常

业务错误码

返回值	描述
10000	客户端传参异常，详见异常响应参数
10001	公共参数错误
10016	client 下线或者 clientId 不正确（身份不正确）
10018	功能模块 API 无权调用
10019	token 已过期
50000	服务端异常

请求消息示例

POST /api/web/project/12345/device/update HTTP/1.1
Content-Type: application/json

{
	"id": "vdev_001",
	"title": "新设备名称",
	"des": "更新后的备注"
}

HTTP 状态码

返回值	描述
200	操作成功，详见响应参数
429	并发限流
500	服务端异常

业务错误码

返回值	描述
10000	客户端传参异常，详见异常响应参数
10001	公共参数错误
10016	client 下线或者 clientId 不正确（身份不正确）
10018	功能模块 API 无权调用
10019	token 已过期
50000	服务端异常

响应消息示例

HTTP/1.1 200
Content-Type: application/json;charset=UTF-8

{
	"code": 0,
	"reason": "OK"
}

解绑虚拟设备

请求方法

POST

请求地址

/proxy/ecloud/api/web/projects/devices/unbind

请求参数

参数	参数类型	数据类型	是否必需	描述
id	body	String	是	虚拟设备 ID
clear	body	Boolean	否	是否清除同步的设备变量

响应参数

参数	数据类型	描述
code	Int	状态码 (0: 成功)
reason	String	状态描述
HTTP 状态码

返回值	描述
200	操作成功，详见响应参数
429	并发限流
500	服务端异常

业务错误码

返回值	描述
10000	客户端传参异常，详见异常响应参数
10001	公共参数错误
10016	client 下线或者 clientId 不正确（身份不正确）
10018	功能模块 API 无权调用
10019	token 已过期
50000	服务端异常

请求消息示例

POST /api/web/projects/devices/unbind HTTP/1.1
Content-Type: application/json

{
	"id": "vdev_001",
	"clear": true
}

响应消息示例

HTTP/1.1 200
Content-Type: application/json;charset=UTF-8

{
	"hwcode": 0,
	"hwreason": "OK"
}

删除项目设备

请求方法

POST

请求地址

/proxy/ecloud/api/web/project/{pid}/devices/delete

请求参数

参数	参数类型	数据类型	是否必需	描述
pid	path	String	是	项目 ID
deviceIds	body	Array	是	虚拟设备 ID 列表

HTTP 状态码

返回值	描述
200	操作成功，详见响应参数
429	并发限流
500	服务端异常

业务错误码

返回值	描述
10000	客户端传参异常，详见异常响应参数
10001	公共参数错误
10016	client 下线或者 clientId 不正确（身份不正确）
10018	功能模块 API 无权调用
10019	token 已过期
50000	服务端异常

响应参数

参数	数据类型	描述
hwcode	Int	状态码
hwreason	String	状态描述

请求消息示例

POST /proxy/ecloud/api/web/project/123456/devices/delete HTTP/1.1
Content-Type: application/json

{
	"deviceIds": ["dev_001", "dev_002"]
}

响应消息示例

HTTP/1.1 200
Content-Type: application/json;charset=UTF-8

{
	"hwcode": 0,
	"hwreason": "OK"
}

绑定虚拟设备

请求方法

POST

请求地址

/proxy/ecloud/api/web/projects/devices/bind

请求参数

参数	参数类型	数据类型	是否必需	描述
id	body	String	是	虚拟设备 ID
actualId	body	String	是	实际设备的 ID

响应参数

参数	数据类型	描述
code	Int	状态码 (0: 成功)
reason	String	状态描述
HTTP 状态码

返回值	描述
200	操作成功，详见响应参数
429	并发限流
500	服务端异常

业务错误码

返回值	描述
10000	客户端传参异常，详见异常响应参数
10001	公共参数错误
10016	client 下线或者 clientId 不正确（身份不正确）
10018	功能模块 API 无权调用
10019	token 已过期
50000	服务端异常

请求消息示例

POST /proxy/ecloud/api/web/projects/devices/bind HTTP/1.1
Content-Type: application/json

{
	"id": "vdev_001",
	"actualId": "physic_dev_002"
}

响应消息示例

HTTP/1.1 200
Content-Type: application/json;charset=UTF-8

{
	"code": 0,
	"reason": "OK"
}

搜索变量历史数据

请求方法

POST

请求地址

/proxy/ecloud/api/web/datac/his/value/search

请求参数

参数	参数类型	数据类型	是否必需	描述
projectId	body	String	是	项目 UUid
current	body	Int	是	当前页码
pageSize	body	Int	是	每页数量
timeRange	body	Array	是	时间范围 [开始时间, 结束时间] (Unix 时间戳)
deviceIds	body	Array	否	虚拟设备 ID 列表
variableIds	body	Array	否	虚拟变量 ID 列表
sorter	body	Map	否	排序条件
HTTP 状态码

返回值	描述
200	操作成功，详见响应参数
429	并发限流
500	服务端异常

业务错误码

返回值	描述
10000	客户端传参异常，详见异常响应参数
10001	公共参数错误
10016	client 下线或者 clientId 不正确（身份不正确）
10018	功能模块 API 无权调用
10019	token 已过期
50000	服务端异常

响应参数

参数	数据类型	描述
total	Int	数据总数
datas	Array	历史数据列表

datas 内部结构：

参数	数据类型	描述
id	String	虚拟变量 ID
deviceId	String	虚拟设备 ID
time	Int64	变量存储时间
varName	String	变量名称
value	String	变量值
deviceName	String	虚拟设备名称
identification	String	变量唯一标识
realDeviceName	String	物理设备名称

请求消息示例

POST /proxy/ecloud/api/web/datac/his/value/search HTTP/1.1
Content-Type: application/json

{
	"projectId": "123456",
	"current": 1,
	"pageSize": 20,
	"timeRange": [1700000000, 1700086400],
	"variableIds": ["var_001", "var_002"],
	"sorter": {
		"time": "desc"
	}
}

响应消息示例

HTTP/1.1 200
Content-Type: application/json;charset=UTF-8

{
	"code": 0,
	"reason": "OK",
	"data": {
		"total": 100,
		"datas": [
			{
				"id": "var_001",
				"deviceId": "dev_001",
				"time": 1700000001,
				"varName": "温度传感器",
				"value": "25.5",
				"deviceName": "虚拟设备A",
				"identification": "temp_01",
				"realDeviceName": "实际设备X"
			}
		]
	}
}

搜索设备变量

请求方法

POST

请求地址

/proxy/ecloud/api/web/datapoints/search

请求参数

参数	参数类型	数据类型	是否必需	描述
-projectId	body	String	是	项目 UUID
-searchKey	body	Array	否	搜索关键字列表，每个元素包含 key 和 name
｜--searchKey.key	String	搜索关键字 ;请默认填写真实ID,例如："11292-8"
｜--searchKey.name	String	搜索名称 ;请默认填写"deviceId"
-current	body	Int	是	当前页码
-pageSize	body	Int	是	每页数量
-deviceType	body	String	是	0: 物理设备, 1:虚拟设备）

响应参数

参数	数据类型	描述
hwcode	Int	状态码
hwreason	String	状态描述
hwdata	Object	返回数据对象
- total	Int	数据总数
- varList	Array	变量列表
｜--varList[0].id	String	变量 ID
｜--varList[0].title	String	变量名称
｜--varList[0].identifiers	String	变量唯一标识
｜--varList[0].type	String	变量类型
｜--varList[0].descript	String	变量描述
｜--varList[0].power	String	权限
｜--varList[0].bind	Int	绑定关系 (0: 未绑定，1: 已绑定)
｜--varList[0].max	String	变量最大值
｜--varList[0].min	String	变量最小值
｜--varList[0].deviceId	String	设备 ID
｜--varList[0].deviceTitle	String	设备名称
｜--varList[0].actualTitle	String	实际设备名称
｜--varList[0].storageType	Array	存储类型列表
｜--varList[0].storageInterval	Int	存储间隔（秒）
｜--varList[0].initialValue	String	初始值
｜--varList[0].reserve	Int	保留小数位数

HTTP 状态码

返回值	描述
200	操作成功，详见响应参数
429	并发限流
500	服务端异常

业务错误码

返回值	描述
10000	客户端传参异常，详见异常响应参数
10001	公共参数错误
10016	client 下线或者 clientId 不正确（身份不正确）
10018	功能模块 API 无权调用
10019	token 已过期
50000	服务端异常

请求消息示例

POST /proxy/ecloud/api/web/datapoints/search HTTP/1.1
Content-Type: application/json

{
	"projectId": "project_001",
	"searchKey": [
		{
			"key": "temp",
			"name": "温度"
		},
		{
			"key": "sensor",
			"name": "传感器"
		}
	],
	"current": 1,
	"pageSize": 20,
	"deviceType": "virtual"
}

响应消息示例

HTTP/1.1 200
Content-Type: application/json;charset=UTF-8

{
	"code": 0,
	"reason": "OK",
	"data": {
		"total": 50,
		"varList": [
			{
				"id": "var_001",
				"title": "温度传感器1",
				"identifiers": "temp_sensor_01",
				"type": "float",
				"descript": "房间温度传感器",
				"power": "rw",
				"bind": 1,
				"max": "100",
				"min": "-50",
				"deviceId": "dev_001",
				"deviceTitle": "虚拟设备A",
				"actualTitle": "物理设备X",
				"storageType": [1, 2],
				"storageInterval": 60,
				"initialValue": "25.0",
				"reserve": 2
			},
			{
				"id": "var_002",
				"title": "湿度传感器1",
				"identifiers": "humidity_sensor_01",
				"type": "float",
				"descript": "房间湿度传感器",
				"power": "r",
				"bind": 0,
				"max": "100",
				"min": "0",
				"deviceId": "dev_002",
				"deviceTitle": "虚拟设备B",
				"actualTitle": "",
				"storageType": [1],
				"storageInterval": 300,
				"initialValue": "50.0",
				"reserve": 1
			}
		]
	}
}

绑定物理设备的变量列表

请求方法

POST

请求地址

/proxy/ecloud/api/web/datapoints/bindvars

请求参数

参数	参数类型	数据类型	是否必需	描述
id	body	String	是	虚拟设备 ID
actualId	body	String	是	物理设备 ID

响应参数

参数	数据类型	描述
hwcode	Int	状态码
hwreason	String	状态描述
hwdata	Object	返回数据对象
-- hwdata[0].identifiers	String	变量唯一标识
-- hwdata[0].type	String	变量类型 USHORT(无符号整形) UINT(无符号长整型) INT(长整型) SHORT(整型) FLOAT(浮点型) DOUBLE(双精度浮点) STRING(字符串) BOOL(布尔)
-- hwdata[0].title	String	变量名称
-- hwdata[0].power	String	读写权限 (r: 只读, w: 只写, rw: 读写)
-- hwdata[0].min	String	最小值
-- hwdata[0].max	String	最大值
-- hwdata[0].bind	Boolean	虚拟变量绑定状态 (true: 已绑定, false: 未绑定)

HTTP 状态码

返回值	描述
200	操作成功，详见响应参数
429	并发限流
500	服务端异常

业务错误码

返回值	描述
10000	客户端传参异常，详见异常响应参数
10001	公共参数错误
10016	client 下线或者 clientId 不正确（身份不正确）
10018	功能模块 API 无权调用
10019	token 已过期
50000	服务端异常

请求消息示例

POST /proxy/ecloud/api/web/datapoints/bindvars HTTP/1.1
Content-Type: application/json

{
	"id": "vdev_001",
	"actualId": "physic_dev_001"
}

响应消息示例

HTTP/1.1 200
Content-Type: application/json;charset=UTF-8

{
	"hwcode": 0,
	"hwreason": "OK",
	"hwdata": {
		"data": [
			{
				"identifiers": "temp_01",
				"type": "float",
				"title": "温度传感器1",
				"power": "rw",
				"min": "-50",
				"max": "100",
				"bind": true
			},
			{
				"identifiers": "humidity_01",
				"type": "float",
				"title": "湿度传感器1",
				"power": "r",
				"min": "0",
				"max": "100",
				"bind": false
			},
			{
				"identifiers": "pressure_01",
				"type": "int",
				"title": "压力传感器1",
				"power": "rw",
				"min": "0",
				"max": "1000",
				"bind": true
			}
		]
	}
}

添加物理设备变量

请求方法

POST

请求地址

/proxy/ecloud/api/web/device/{did}/datapoints

请求参数

参数	参数类型	数据类型	是否必需	描述
-did	path	String	是	虚拟设备 ID（路径参数）
-id	body	String	是	虚拟设备 ID（请求体参数，需与 did 一致）
-varList	body	Array	是	变量列表
--varList[0].id	String	否	变量 ID
--varList[0].title	String	是	变量名称
--varList[0].identifiers	String	否	变量唯一标识
--varList[0].type	String	是	变量类型 USHORT(无符号整形) UINT(无符号长整型) INT(长整型) SHORT(整型) FLOAT(浮点型) DOUBLE(双精度浮点) STRING(字符串) BOOL(布尔)
--varList[0].descript	String	否	变量描述
--varList[0].power	String	是	读写权限 (r: 只读, w: 只写, rw: 读写)
--varList[0].max	String	否	最大值
--varList[0].min	String	否	最小值
--varList[0].storageType	Array	否	存储类型列表 (1: 时间存储, 2: 容量存储)
--varList[0].storageInterval	Int	否	存储间隔（天）
--varList[0].initialValue	String	否	初始值	注意：type =BOOL时，值只能传 1或0，1表示true 0表示false
--varList[0].pointCode	String	否	虚拟变量编码
--varList[0].reserve	Int	否	保留小数位数

⚠️ 说明：该接口使用路径参数 :did 指定设备ID，同时请求体中的 id 字段也需要提供设备ID（通常与路径参数保持一致）。

HTTP 状态码

返回值	描述
200	操作成功，详见响应参数
429	并发限流
500	服务端异常

业务错误码

返回值	描述
10000	客户端传参异常，详见异常响应参数
10001	公共参数错误
10016	client 下线或者 clientId 不正确（身份不正确）
10018	功能模块 API 无权调用
10019	token 已过期
50000	服务端异常

响应参数

参数	数据类型	描述
hwcode	Int	状态码
hwreason	String	状态描述

请求消息示例

POST /proxy/ecloud/api/web/device/vdev_001/datapoints HTTP/1.1
Content-Type: application/json

{
	"id": "vdev_001",
	"varList": [
		{
			"id": "var_001",
			"title": "温度传感器1",
			"identifiers": "temp_sensor_01",
			"type": "float",
			"descript": "房间温度监测",
			"power": "rw",
			"max": "100",
			"min": "-50",
			"storageType": [1, 2],
			"storageInterval": 30,
			"initialValue": "25.0",
			"reserve": 2
		},
		{
			"id": "var_002",
			"title": "湿度传感器1",
			"identifiers": "humidity_sensor_01",
			"type": "float",
			"descript": "房间湿度监测",
			"power": "r",
			"max": "100",
			"min": "0",
			"storageType": [1],
			"storageInterval": 60,
			"initialValue": "50.0",
			"reserve": 1
		}
	]
}

响应消息示例

HTTP/1.1 200
Content-Type: application/json;charset=UTF-8

{
	"hwcode": 0,
	"hwreason": "OK"
}

更新虚拟变量

请求方法

POST

请求地址

/proxy/ecloud/api/web/datapoints/update

请求参数

参数	参数类型	数据类型	是否必需	描述
id	body	String	是	变量 ID
deviceId	body	String	否	设备 ID
title	body	String	是	变量名称
identifiers	body	String	否	变量唯一标识
type	body	String	是	变量类型 (int, float, string, bool 等)
power	body	String	是	读写权限 (r: 只读, w: 只写, rw: 读写)
storageType	body	Array	是	数据存储类型 (1: 不存储, 2: 变化, 3: 间隔, 4: 实时)
storageInterval	body	Int	否	数据存储间隔（秒）
descript	body	String	否	变量描述
initialValue	body	String	否	初始值
max	body	String	否	最大值
min	body	String	否	最小值
reserve	body	Int	否	保留小数位数

HTTP 状态码

返回值	描述
200	操作成功，详见响应参数
429	并发限流
500	服务端异常

业务错误码

返回值	描述
10000	客户端传参异常，详见异常响应参数
10001	公共参数错误
10016	client 下线或者 clientId 不正确（身份不正确）
10018	功能模块 API 无权调用
10019	token 已过期
50000	服务端异常

响应参数

参数	数据类型	描述
hwcode	Int	状态码
hwreason	String	状态描述

请求消息示例

POST /proxy/ecloud/api/web/datapoints/update HTTP/1.1
Content-Type: application/json

{
	"id": "var_001",
	"deviceId": "vdev_001",
	"title": "温度传感器1",
	"identifiers": "temp_sensor_01",
	"type": "float",
	"power": "rw",
	"storageType": [2, 3],
	"storageInterval": 60,
	"descript": "房间温度监测",
	"initialValue": "25.0",
	"max": "100",
	"min": "-50",
	"reserve": 2
}

响应消息示例

HTTP/1.1 200
Content-Type: application/json;charset=UTF-8

{
	"hwcode": 0,
	"hwreason": "OK"
}

删除虚拟变量

请求方法

POST

请求地址

/proxy/ecloud/api/web/datapoints/delete

请求参数

参数	参数类型	数据类型	是否必需	描述
varIds	body	Array	是	变量 ID 列表

HTTP 状态码

返回值	描述
200	操作成功，详见响应参数
429	并发限流
500	服务端异常

业务错误码

返回值	描述
10000	客户端传参异常，详见异常响应参数
10001	公共参数错误
10016	client 下线或者 clientId 不正确（身份不正确）
10018	功能模块 API 无权调用
10019	token 已过期
50000	服务端异常

响应参数

参数	数据类型	描述
hwcode	Int	状态码
hwreason	String	状态描述

请求消息示例

POST /proxy/ecloud/api/web/datapoints/delete HTTP/1.1
Content-Type: application/json

{
	"varIds": ["var_001", "var_002", "var_003"]
}

响应消息示例

HTTP/1.1 200
Content-Type: application/json;charset=UTF-8

{
	"hwcode": 0,
	"hwreason": "OK"
}

删除项目设备

请求方法

POST

请求地址

/proxy/ecloud/api/web/project/{pid}/devices/delete

请求参数

参数	参数类型	数据类型	是否必需	描述
pid	path	String	是	项目 ID
deviceIds	body	Array	是	虚拟设备 ID 列表

HTTP 状态码

返回值	描述
200	操作成功，详见响应参数
429	并发限流
500	服务端异常

业务错误码

返回值	描述
10000	客户端传参异常，详见异常响应参数
10001	公共参数错误
10016	client 下线或者 clientId 不正确（身份不正确）
10018	功能模块 API 无权调用
10019	token 已过期
50000	服务端异常

响应参数

参数	数据类型	描述
hwcode	Int	状态码
hwreason	String	状态描述

请求消息示例

POST /proxy/ecloud/api/web/project/123456/devices/delete HTTP/1.1
Content-Type: application/json

{
	"deviceIds": ["dev_001", "dev_002"]
}

响应消息示例

HTTP/1.1 200
Content-Type: application/json;charset=UTF-8

{
	"hwcode": 0,
	"hwreason": "OK"
}

API 企业设备（Enterprise Device）

企业设备列表

请求方法

GET

请求地址

/api/v1/enterprise/devices

公共请求参数

参数名称	参数类型	数据类型	是否必填	参数描述
Authorization	Header	String	是	通过 Credentials 获取的 token

请求参数

参数	参数类型	数据类型	是否必需	描述
state	query	Integer	否	设备状态（0: 离线, 1: 在线）
device_code	query	String	否	设备编码
device_name	query	String	否	设备名称
project_name	query	String	否	项目名称
limit	query	Integer	是	每页数量，默认 10，最大 100
offset	query	Integer	是	偏移量

HTTP 状态码

返回值	描述
200	操作成功，详见响应参数
429	并发限流
500	服务端异常

业务错误码

返回值	描述
10000	客户端传参异常，详见异常响应参数
10001	公共参数错误
10016	client 下线或者 clientId 不正确（身份不正确）
10018	功能模块 API 无权调用
10019	token 已过期
50000	服务端异常

响应参数

参数	参数类型	描述
code	Long	成功返回码默认 0
reason	String	服务端定义的标签，用于业务快速定位问题
data	Object	返回数据结构体
- data.total	Long	设备总数
- data.list	Object[]	设备列表
-- data.list[0].device_id	Long	设备 ID
-- data.list[0].online	Integer	在线状态（0: 离线, 1: 在线）
-- data.list[0].device_code	String	设备编码
-- data.list[0].device_name	String	设备名称
-- data.list[0].project_name	String	项目名称
-- data.list[0].model	String	设备型号
-- data.list[0].version	String	固件版本
-- data.list[0].remark	String	备注
-- data.list[0].iccids	Object[]	SIM 卡信息
--- data.list[0].iccids[0].iccid	String	ICCID

异常响应参数

参数	数据类型	描述
error_msg	String	表示一个错误代码字符串，可以用于对错误进行分类，并对错误进行处理
code	Long	服务端定义的错误码，用于快速定位问题
reason	String	服务端定义的标签，用于业务快速定位问题

请求消息示例

GET /enterprise/devices?limit=10&offset=1 HTTP/1.1
Host: openapi.haweill.com
Content-Type: application/json
Authorization: Bearer YOUR_TOKEN

响应消息示例

HTTP/1.1 200
Content-Type: application/json;charset=UTF-8

{
	"code":0,
	"reason":"OK",
	"data":{
		"total":1,
		"list":[
			{
				"device_id":1,
				"online":1,
				"device_code":"HW123456",
				"device_name":"测试设备",
				"project_name":"测试项目",
				"model":"H1",
				"version":"1.0.0",
				"remark":"备注",
				"iccids":[]
			}
		]
	}
}

企业设备详情

请求方法

GET

请求地址

/api/v1/enterprise/devices/{device_code}

公共请求参数

参数名称	参数类型	数据类型	是否必填	参数描述
Authorization	Header	String	是	通过 Credentials 获取的 token

请求参数

参数	参数类型	数据类型	是否必需	描述
device_code	path	String	是	设备编码，长度大于 7 位

HTTP 状态码

返回值	描述
200	操作成功，详见响应参数
429	并发限流
500	服务端异常

业务错误码

返回值	描述
10000	客户端传参异常，详见异常响应参数
10001	公共参数错误
10016	client 下线或者 clientId 不正确（身份不正确）
10018	功能模块 API 无权调用
10019	token 已过期
50000	服务端异常

响应参数

参数	参数类型	描述
code	Long	成功返回码默认 0
reason	String	服务端定义的标签，用于业务快速定位问题
data	Object	返回数据结构体
- data.eid	Integer	企业 ID
- data.device_id	Integer	设备 ID
- data.device_code	String	设备编码
- data.device_name	String	设备名称
- data.remark	String	设备备注
- data.online	Integer	在线状态（0: 离线, 1: 在线）
- data.version	Integer	设备版本
- data.project_image	String	项目图片
- data.project_name	String	项目名称
- data.model	String	设备型号
- data.location	String	设备地理位置
- data.latitude	String	纬度
- data.longitude	String	经度

异常响应参数

参数	数据类型	描述
error_msg	String	表示一个错误代码字符串，可以用于对错误进行分类，并对错误进行处理
code	Long	服务端定义的错误码，用于快速定位问题
reason	String	服务端定义的标签，用于业务快速定位问题

请求消息示例

GET /enterprise/devices/HW123456789 HTTP/1.1
Host: openapi.haweill.com
Content-Type: application/json
Authorization: Bearer YOUR_TOKEN

响应消息示例

HTTP/1.1 200
Content-Type: application/json;charset=UTF-8

{
	"code":0,
	"reason":"OK",
	"data":{
		"device_id":123,
		"device_code":"HW123456789",
		"device_name":"测试设备",
		"remark":"备注信息",
		"online":1,
		"version":1,
		"project_image":"http://example.com/image.png",
		"project_name":"测试项目",
		"model":"H1",
		"location":"厦门市",
		"latitude":"24.4798",
		"longitude":"118.0894"
	}
}

删除设备

请求方法

DELETE

请求地址

/api/v1/enterprise/devices/{device_code}

公共请求参数

参数名称	参数类型	数据类型	是否必填	参数描述
Authorization	Header	String	是	通过 Credentials 获取的 token

请求参数

参数	参数类型	数据类型	是否必需	描述
device_code	path	String	是	设备编码，长度 19 位

HTTP 状态码

返回值	描述
200	操作成功，详见响应参数
429	并发限流
500	服务端异常

业务错误码

返回值	描述
10000	客户端传参异常，详见异常响应参数
10001	公共参数错误
10016	client 下线或者 clientId 不正确（身份不正确）
10018	功能模块 API 无权调用
10019	token 已过期
50000	服务端异常

响应参数

参数	参数类型	描述
code	Long	成功返回码默认 0
reason	String	服务端定义的标签，用于业务快速定位问题

异常响应参数

参数	数据类型	描述
error_msg	String	表示一个错误代码字符串，可以用于对错误进行分类，并对错误进行处理
code	Long	服务端定义的错误码，用于快速定位问题
reason	String	服务端定义的标签，用于业务快速定位问题

请求消息示例

DELETE /enterprise/devices/HW1234567890123456789 HTTP/1.1
Host: openapi.haweill.com
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

响应消息示例

HTTP/1.1 200
Content-Type: application/json;charset=UTF-8

{
	"code":0,
	"reason":"OK"
}

修改设备信息

请求方法

PUT

请求地址

/api/v1/enterprise/devices/{device_code}

公共请求参数

参数名称	参数类型	数据类型	是否必填	参数描述
Authorization	Header	String	是	通过 Credentials 获取的 token

请求参数

参数	参数类型	数据类型	是否必需	描述
device_code	path	String	是	设备编码，长度大于 17 位
device_name	body	String	否	设备名称，最大长度 30 个字符，只能包含字母、数字、下划线和中文
device_remark	body	String	否	设备备注，最大长度 100 个字符，可包含字母、数字、下划线、空格和中文

HTTP 状态码

返回值	描述
200	操作成功，详见响应参数
429	并发限流
500	服务端异常

业务错误码

返回值	描述
10000	客户端传参异常，详见异常响应参数
10001	公共参数错误
10016	client 下线或者 clientId 不正确（身份不正确）
10018	功能模块 API 无权调用
10019	token 已过期
50000	服务端异常

响应参数

参数	参数类型	描述
code	Long	成功返回码默认 0
reason	String	服务端定义的标签，用于业务快速定位问题

异常响应参数

参数	数据类型	描述
error_msg	String	表示一个错误代码字符串，可以用于对错误进行分类，并对错误进行处理
code	Long	服务端定义的错误码，用于快速定位问题
reason	String	服务端定义的标签，用于业务快速定位问题

请求消息示例

PUT /enterprise/devices/HW1234567890123456789 HTTP/1.1
Host: openapi.haweill.com
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

{
	"device_name":"更新后的设备名称",
	"device_remark":"更新后的设备备注"
}

响应消息示例

HTTP/1.1 200
Content-Type: application/json;charset=UTF-8

{
	"code":0,
	"reason":"OK"
}

API 物联网卡（IOT Card）

物联网卡列表（分页）

请求方法

GET

请求地址

/proxy/ecloud/api/v1/iotcards

业务逻辑说明

权限控制：

接口需要通过认证中间件验证用户身份
用户只能查询自己有权限管理的设备对应的物联网卡
企业管理员可以查询企业所有的物联网卡

查询范围：

根据用户的设备管理权限获取可管理的设备编码列表
企业管理员可额外查询企业所有的物联网卡 ICCID
最终返回用户有权限的卡片列表

筛选条件：

支持多种筛选条件组合查询
blur 参数支持同时搜索 ICCID、设备编码、IMEI、套餐名称
cellularDataBetween 支持流量区间查询，格式为 min,max（单位：万 KB）
operator 参数会同时匹配运营商字段和套餐名称中的运营商关键字

状态筛选：

packageState：套餐状态（1=耗尽，2=不足，3=充足）
cellularDataState：流量状态（1=耗尽，2=不足，3=充足）
状态阈值基于系统配置的通知阈值计算

关联数据：

返回结果包含设备信息（设备名称、别名、型号、项目）
departDevice 字段表示设备归属关系（1=企业设备，2=维护设备，3=同时属于两者）

排序功能：

sorter 参数支持 JSON 格式的排序规则
格式示例：{"cardEndTime":"desc"} 表示按卡到期时间降序排列

注意事项

所有涉及流量的参数单位为 KB，前端展示时需要转换为 MB 或 GB
flowUsageRatio 使用万分比表示，需要除以 10000 转换为百分比
时间戳均为 Unix 时间戳（秒级）
cardType 为 1 时会同时查询类型 0 和 1 的卡片
删除的卡片（deleteTime != 0）不会出现在查询结果中

公共请求参数

参数名称	参数类型	数据类型	是否必填	参数描述
Authorization	Header	String	是	通过 Credentials 获取的 token

请求参数

参数	参数类型	数据类型	是否必需	描述
pageSize	Query	Long	是	每页记录数，必须大于等于 0
page	Query	Long	是	页码，必须大于 0，页码从 1 开始
eid	Query	Long	否	企业 ID
machineCode	Query	String	否	设备编码，支持模糊查询
imei	Query	String	否	IMEI 号，支持模糊查询
cardStatus	Query	Long	否	卡状态
startTime	Query	Long	否	卡有效期开始时间（时间戳）
endTime	Query	Long	否	卡有效期结束时间（时间戳）
packageId	Query	Long	否	套餐 ID
packageName	Query	String	否	套餐名称，支持模糊查询
iccid	Query	String	否	ICCID 号，支持模糊查询
surplusFlowMax	Query	Long	否	剩余流量上限（单位：MB）
flowUsageRatio	Query	Long	否	流量使用比例（万分比）
departDevice	Query	Long	否	设备归属关系
cardType	Query	Long	否	卡类型（1: 包含 0 和 1 类型）
leftTime	Query	Long	否	剩余天数
sorter	Query	String	否	排序规则，JSON 字符串格式，如：`{"field":"asc/desc"}`
blur	Query	String	否	模糊查询，支持按 ICCID、设备编码、IMEI、套餐名称搜索
cellularDataBetween	Query	String	否	剩余流量区间，格式：`min,max`（单位：万 KB），如：`0,100`
packageState	Query	Int8	否	套餐状态（1：耗尽，2：不足，3：充足）
cellularDataState	Query	Int8	否	流量状态（1：耗尽，2：不足，3：充足）
platformCard	Query	Int8	否	是否平台卡（0：平台卡，1：非平台卡）
operator	Query	Int8	否	运营商（1：移动，2：联通，3：电信）

HTTP 状态码

返回值	描述
200	操作成功，详见响应参数
429	并发限流
500	服务端异常

业务错误码

返回值	描述
400	客户端传参异常，详见异常响应参数
10001	公共参数错误
10016	client 下线或者 clientId 不正确（身份不正确）
10018	功能模块 API 无权调用
10019	token 已过期
50000	服务端异常

响应参数

参数	参数类型	描述
hwcode	Long	成功返回码默认 0
hwreason	String	服务端定义的标签，用于业务快速定位问题
hwmsg	String	响应消息
hwdata	Object	返回数据结构体
- hwdata.total	Long	数据总数
- hwdata.list	Object[]	物联网卡列表
-- hwdata.list[0].iotCardId	Long	物联网卡 ID
-- hwdata.list[0].thirdPartyIccid	String	第三方 ICCID
-- hwdata.list[0].iccid	String	ICCID 号
-- hwdata.list[0].reportedIccid	String	上报的 ICCID
-- hwdata.list[0].imei	String	IMEI 号
-- hwdata.list[0].imsi	String	IMSI 号
-- hwdata.list[0].msisdn	String	MSISDN 号
-- hwdata.list[0].machineCode	String	设备编码
-- hwdata.list[0].deviceAddress	String	设备地址
-- hwdata.list[0].usableFlow	Long	可用流量（单位：KB）
-- hwdata.list[0].beenUsedFlow	Long	已用流量（单位：KB）
-- hwdata.list[0].flowUsageRatio	Long	流量使用比例（万分比）
-- hwdata.list[0].surplusFlow	Long	剩余流量（单位：KB）
-- hwdata.list[0].cardStatus	Long	卡状态
-- hwdata.list[0].cardType	Long	卡类型
-- hwdata.list[0].packageId	Long	套餐 ID
-- hwdata.list[0].packageName	String	套餐名称
-- hwdata.list[0].operator	Long	运营商（1：移动，2：联通，3：电信）
-- hwdata.list[0].leftPeriod	Long	剩余周期
-- hwdata.list[0].periodStartTime	Long	周期开始时间（时间戳）
-- hwdata.list[0].periodEndTime	Long	周期结束时间（时间戳）
-- hwdata.list[0].cardEndTime	Long	卡到期时间（时间戳）
-- hwdata.list[0].leftTime	Long	剩余天数
-- hwdata.list[0].cardFeeTime	Long	卡费用时间（时间戳）
-- hwdata.list[0].dataUpdateTime	Long	数据更新时间（时间戳）
-- hwdata.list[0].flowUpdateTime	Long	流量更新时间（时间戳）
-- hwdata.list[0].createTime	Long	创建时间（时间戳）
-- hwdata.list[0].deleteTime	Long	删除时间（时间戳），0 表示未删除
-- hwdata.list[0].reportTime	Long	上报时间（时间戳）
-- hwdata.list[0].supplierType	Long	供应商类型
-- hwdata.list[0].id	Long	记录 ID
-- hwdata.list[0].note	String	备注信息
-- hwdata.list[0].deviceAliases	String	设备别名
-- hwdata.list[0].cardModel	String	设备型号
-- hwdata.list[0].cardProject	String	所属项目
-- hwdata.list[0].deviceName	String	设备名称
-- hwdata.list[0].departDevice	Int8	设备归属（1：企业设备，2：维护设备，3：都有）
-- hwdata.list[0].isUse	Long	是否在使用
-- hwdata.list[0].thumbnail	String	缩略图
-- hwdata.list[0].enterpriseOwned	Int8	是否企业所有（0：否，1：是）

异常响应参数

参数	数据类型	描述
error_msg	String	表示一个错误代码字符串，可以用于对错误进行分类，并对错误进行处理
code	String	服务端定义的错误码，用于快速定位问题
reason	String	服务端定义的标签，用于业务快速定位问题

请求消息示例

GET /api/v1/iotcards?pageSize=10&page=1&blur=测试 HTTP/1.1
Host: openapi.haiwell.com
Client-ID: your-client-id
Authorization: Bearer your-access-token
Content-Type: application/json

响应消息示例

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
    "hwcode": 0,
    "hwreason": "SUCCEEDED",
    "hwmsg": "ok",
    "hwdata": {
        "list": [
            {
                "iotCardId": 347877,
                "thirdPartyIccid": "8986032346201749534",
                "iccid": "8986032346201749534",
                "reportedIccid": "",
                "imei": "",
                "imsi": "",
                "msisdn": "1064987502331",
                "machineCode": "",
                "deviceAddress": "",
                "usableFlow": 36000000,
                "beenUsedFlow": 0,
                "flowUsageRatio": 0,
                "surplusFlow": 0,
                "cardStatus": 20,
                "cardType": 0,
                "packageId": 4490,
                "packageName": "电信3600M/年定向",
                "operator": 0,
                "leftPeriod": 0,
                "periodStartTime": 1714492800,
                "periodEndTime": 1745942400,
                "cardEndTime": 1745942400,
                "leftTime": -274,
                "cardFeeTime": 0,
                "dataUpdateTime": 1769719074,
                "flowUpdateTime": 1769719074,
                "createTime": 1765485470,
                "deleteTime": 0,
                "reportTime": 0,
                "supplierType": 1,
                "id": 347877,
                "note": "",
                "deviceAliases": "",
                "cardModel": "EBIOT",
                "cardProject": "",
                "deviceName": "",
                "departDevice": 0,
                "isUse": 0,
                "thumbnail": "",
                "enterpriseOwned": 1
            },
            {
                "iotCardId": 98392,
                "thirdPartyIccid": "898608121923D0444958",
                "iccid": "898608121923D0444958",
                "reportedIccid": "",
                "imei": "",
                "imsi": "",
                "msisdn": "1441620844958",
                "machineCode": "7042349175880188113",
                "deviceAddress": "",
                "usableFlow": 36000000,
                "beenUsedFlow": 860000,
                "flowUsageRatio": 239,
                "surplusFlow": 35140000,
                "cardStatus": 9,
                "cardType": 0,
                "packageId": 163,
                "packageName": "移动3600M/年",
                "operator": 0,
                "leftPeriod": 1,
                "periodStartTime": 1756656000,
                "periodEndTime": 1788105600,
                "cardEndTime": 1788105600,
                "leftTime": 214,
                "cardFeeTime": 0,
                "dataUpdateTime": 1769735264,
                "flowUpdateTime": 1769735264,
                "createTime": 1745313987,
                "deleteTime": 0,
                "reportTime": 0,
                "supplierType": 1,
                "id": 98392,
                "note": "",
                "deviceAliases": "123",
                "cardModel": "A10 Pro",
                "cardProject": "工程1234",
                "deviceName": "西安市未央区",
                "departDevice": 3,
                "isUse": 0,
                "thumbnail": "",
                "enterpriseOwned": 0
            },
            {
                "iotCardId": 98100,
                "thirdPartyIccid": "898608121923D0444466",
                "iccid": "898608121923D0444466",
                "reportedIccid": "",
                "imei": "",
                "imsi": "",
                "msisdn": "1441620844466",
                "machineCode": "7111639105880188017",
                "deviceAddress": "",
                "usableFlow": 36000000,
                "beenUsedFlow": 23660000,
                "flowUsageRatio": 6573,
                "surplusFlow": 12340000,
                "cardStatus": 20,
                "cardType": 0,
                "packageId": 4605,
                "packageName": "移动3600M/年定向",
                "operator": 0,
                "leftPeriod": 0,
                "periodStartTime": 1719763200,
                "periodEndTime": 1751212800,
                "cardEndTime": 1751212800,
                "leftTime": -213,
                "cardFeeTime": 0,
                "dataUpdateTime": 1769735080,
                "flowUpdateTime": 1769735080,
                "createTime": 1745313804,
                "deleteTime": 0,
                "reportTime": 0,
                "supplierType": 1,
                "id": 98100,
                "note": "",
                "deviceAliases": "Enterprise equipment",
                "cardModel": "A7-GW",
                "cardProject": "未命名工程",
                "deviceName": "",
                "departDevice": 2,
                "isUse": 0,
                "thumbnail": "",
                "enterpriseOwned": 0
            },
            {
                "iotCardId": 98086,
                "thirdPartyIccid": "898608121923D0444452",
                "iccid": "898608121923D0444452",
                "reportedIccid": "",
                "imei": "",
                "imsi": "",
                "msisdn": "1441620844452",
                "machineCode": "7042349175880188113",
                "deviceAddress": "",
                "usableFlow": 36000000,
                "beenUsedFlow": 13220000,
                "flowUsageRatio": 3674,
                "surplusFlow": 22780000,
                "cardStatus": 9,
                "cardType": 0,
                "packageId": 4605,
                "packageName": "移动3600M/年定向",
                "operator": 0,
                "leftPeriod": 1,
                "periodStartTime": 1748707200,
                "periodEndTime": 1780156800,
                "cardEndTime": 1780156800,
                "leftTime": 122,
                "cardFeeTime": 0,
                "dataUpdateTime": 1769735080,
                "flowUpdateTime": 1769735080,
                "createTime": 1745313804,
                "deleteTime": 0,
                "reportTime": 0,
                "supplierType": 1,
                "id": 98086,
                "note": "",
                "deviceAliases": "123",
                "cardModel": "A10 Pro",
                "cardProject": "工程1234",
                "deviceName": "西安市未央区",
                "departDevice": 3,
                "isUse": 0,
                "thumbnail": "",
                "enterpriseOwned": 0
            }
        ],
        "total": 4
    }
}

获取物联网卡信息

请求方法

GET

请求地址

/proxy/ecloud/api/v1/iotcard/info

业务逻辑说明

查询方式：
- 支持通过 machineCode 或 iccid 查询物联网卡信息
- 至少需要提供 machineCode 或 iccid 其中一个参数
- iccid 参数支持匹配标准 ICCID 或第三方 ICCID
使用状态检测：
- 对于绑定了设备的卡片（machineCode 不为空），系统会尝试通过设备域名查询卡片的实际使用状态
- 调用设备的 /api/machine/getActiveCard 接口获取激活卡片信息
- 如果设备当前激活的卡类型与查询卡片类型一致，则 isUse 标记为 1
查询结果：
- 返回符合条件的所有卡片列表
- 以 Map 结构按 iotCardId 组织数据后转换为数组返回

注意事项

所有涉及流量的参数单位为 KB，前端展示时需要转换为 MB 或 GB
flowUsageRatio 使用万分比表示，需要除以 10000 转换为百分比
时间戳均为 Unix 时间戳（秒级）
设备使用状态检测存在 2 秒超时限制，超时不影响基本信息返回
machineCode 和 iccid 至少需要提供一个，否则不会执行查询 公共请求参数

参数名称	参数类型	数据类型	是否必填	参数描述
Authorization	Header	String	是	通过 Credentials 获取的 token

请求参数

参数	参数类型	数据类型	是否必需	描述
machineCode	Query	String	否	设备编码
iccid	Query	String	否	ICCID 号（支持查询第三方 ICCID）

HTTP 状态码

返回值	描述
200	操作成功，详见响应参数
429	并发限流
500	服务端异常

业务错误码

返回值	描述
406	客户端传参异常，详见异常响应参数
10001	公共参数错误
10016	client 下线或者 clientId 不正确（身份不正确）
10018	功能模块 API 无权调用
10019	token 已过期
50000	服务端异常

响应参数

参数	参数类型	描述
hwcode	Long	成功返回码默认 0
hwreason	String	服务端定义的标签，用于业务快速定位问题
hwmsg	String	响应消息
hwdata	Object	返回数据结构体
- hwdata.data	Object[]	物联网卡列表
-- hwdata.data[0].iotCardId	Long	物联网卡 ID
-- hwdata.data[0].thirdPartyIccid	String	第三方 ICCID
-- hwdata.data[0].iccid	String	ICCID 号
-- hwdata.data[0].reportedIccid	String	上报的 ICCID
-- hwdata.data[0].imei	String	IMEI 号
-- hwdata.data[0].imsi	String	IMSI 号
-- hwdata.data[0].msisdn	String	MSISDN 号
-- hwdata.data[0].machineCode	String	设备编码
-- hwdata.data[0].deviceAddress	String	设备地址
-- hwdata.data[0].usableFlow	Long	可用流量（单位：KB）
-- hwdata.data[0].beenUsedFlow	Long	已用流量（单位：KB）
-- hwdata.data[0].flowUsageRatio	Long	流量使用比例（万分比）
-- hwdata.data[0].surplusFlow	Long	剩余流量（单位：KB）
-- hwdata.data[0].cardStatus	Long	卡状态
-- hwdata.data[0].cardType	Long	卡类型
-- hwdata.data[0].packageId	Long	套餐 ID
-- hwdata.data[0].packageName	String	套餐名称
-- hwdata.data[0].operator	Long	运营商（1：移动，2：联通，3：电信）
-- hwdata.data[0].leftPeriod	Long	剩余周期
-- hwdata.data[0].periodStartTime	Long	周期开始时间（时间戳）
-- hwdata.data[0].periodEndTime	Long	周期结束时间（时间戳）
-- hwdata.data[0].cardEndTime	Long	卡到期时间（时间戳）
-- hwdata.data[0].leftTime	Long	剩余天数
-- hwdata.data[0].cardFeeTime	Long	卡费用时间（时间戳）
-- hwdata.data[0].dataUpdateTime	Long	数据更新时间（时间戳）
-- hwdata.data[0].flowUpdateTime	Long	流量更新时间（时间戳）
-- hwdata.data[0].createTime	Long	创建时间（时间戳）
-- hwdata.data[0].deleteTime	Long	删除时间（时间戳），0 表示未删除
-- hwdata.data[0].reportTime	Long	上报时间（时间戳）
-- hwdata.data[0].supplierType	Long	供应商类型
-- hwdata.data[0].id	Long	关联记录 ID
-- hwdata.data[0].note	String	备注信息
-- hwdata.data[0].isUse	Long	是否在使用（1：使用中，0：未使用）

异常响应参数

参数	数据类型	描述
error_msg	String	表示一个错误代码字符串，可以用于对错误进行分类，并对错误进行处理
code	String	服务端定义的错误码，用于快速定位问题
reason	String	服务端定义的标签，用于业务快速定位问题

请求消息示例

GET /api/v1/iotcard/info?machineCode=DEVICE001 HTTP/1.1
Host: openapi.haiwell.com
Authorization: Bearer your-access-token
Content-Type: application/json

响应消息示例

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
    "hwcode": 0,
    "hwreason": "SUCCEEDED",
    "hwmsg": "ok",
    "hwdata": {
        "data": [
            {
                "iotCardId": 357948,
                "thirdPartyIccid": "892225205099446371",
                "iccid": "89861125205099446373",
                "reportedIccid": "89861125205099446373",
                "imei": "862766075575285",
                "imsi": "460113959519201",
                "msisdn": "1410963590131",
                "machineCode": "7062459064771988000",
                "deviceAddress": "",
                "usableFlow": 122880000,
                "beenUsedFlow": 59890,
                "flowUsageRatio": 4,
                "surplusFlow": 122820110,
                "cardStatus": 9,
                "cardType": 1,
                "packageId": 863,
                "packageName": "电信通用12G年包2021",
                "operator": 3,
                "leftPeriod": 0,
                "periodStartTime": 1760025600,
                "periodEndTime": 1791043200,
                "cardEndTime": 1791043200,
                "leftTime": 293,
                "cardFeeTime": 0,
                "dataUpdateTime": 1768361786,
                "flowUpdateTime": 1765868903,
                "createTime": 1768361786,
                "deleteTime": 0,
                "reportTime": 1768361786,
                "supplierType": 2,
                "id": 0,
                "note": "",
                "isUse": 0
            }
        ]
    }
}

使用 Haiwell APIs​

开发前须知​

APIs 协议说明​

请求地址​

请求参数​

请求头部示例：​

API 调用流程说明​

API 访问凭证 （token）​

申请访问凭证​

刷新访问凭证​

API 项目（project）​

创建项目​

项目列表​

更新项目详情​

删除项目​

创建工程​

查询工程列表​

查询工程详情​

删除工程​

工程信息修改​

创建工程访问链接​

工程设计链接​

虚拟设备列表​

添加项目虚拟设备​

更新虚拟设备​

解绑虚拟设备​

删除项目设备​

绑定虚拟设备​

搜索变量历史数据​

搜索设备变量​

绑定物理设备的变量列表​

添加物理设备变量​

更新虚拟变量​

删除虚拟变量​

删除项目设备​

API 企业设备 （Enterprise Device）​

企业设备列表​

企业设备详情​

删除设备​

修改设备信息​

API 物联网卡（IOT Card）​

物联网卡列表（分页）​

获取物联网卡信息​

使用 Haiwell APIs

开发前须知

APIs 协议说明

请求地址

请求参数

请求头部示例：

API 调用流程说明

API 访问凭证（token）

申请访问凭证

刷新访问凭证

API 项目（project）

创建项目

项目列表

更新项目详情

删除项目

创建工程

查询工程列表

查询工程详情

删除工程

工程信息修改

创建工程访问链接

工程设计链接

虚拟设备列表

添加项目虚拟设备

更新虚拟设备

解绑虚拟设备

删除项目设备

绑定虚拟设备

搜索变量历史数据

搜索设备变量

绑定物理设备的变量列表

添加物理设备变量

更新虚拟变量

删除虚拟变量

删除项目设备

API 企业设备（Enterprise Device）

企业设备列表

企业设备详情

删除设备

修改设备信息

API 物联网卡（IOT Card）

物联网卡列表（分页）

获取物联网卡信息