版本：v3.4.0 (最新)

Factory Edge Service API - v1.5

1.修订记录

版本	更改时间	备注
v1.0	2025/03/26	初始版本
v1.1	2025/12/17	增加"查询设备详情"接口「获取烧录状态可以使用该接口」
v1.2	2025/12/22	修改"查询设备详情"接口参数必填项校验和参数说明「支持使用 matter 的 qrcode 作为查询条件获取设备信息」增加接口异常状态码信息增加错误码列表
v1.3	2026/01/26	废弃"查询设备信息"和"更新设备信息"接口增加"更新设备档案信息"接口
v1.4	2026/09/10	增加“上传设备生产数据”接口
v1.5	2026/10/16	更新“查询设备详情”、“更新设备档案信息”和“上传设备生产数据”接口说明新增“查询设备综合信息”、“找回 Matter 二维码”、“上传设备测试文件”、“连接心跳”、“查询登录选项”、“查询工站登录方式”、“U-Safe 预登录”、“工站登录”、“工站退出登录”、“按订单查询批次”、“分配工站批次”、“查询工站批次信息”、“获取动态烧录数据”、“获取批次元数据”、“获取完整烧录数据（兼容接口）”、“提交中间烧录请求数据”、“上报烧录结果”、“SE APDU 步进烧录”、“获取烧录脚本地址”、“下载文件”、“上传设备事件日志”、“生成 Matter Verifier”、“生成 Matter 配网载荷”和“生成 Matter Unique ID”接口补充已废弃接口“查询设备信息”和“更新设备信息”的兼容说明补充公共调用约定及错误码说明

2. 概述

Factory Edge Service API 用于登录工站、管理生产批次、执行设备烧录、上传生产数据、查询设备信息及更新设备档案。该类接口采用 HTTP 协议传输数据，所有请求和响应均使用 UTF-8 编码。

本文将介绍接口规范、公共请求头，并提供各接口的请求参数、响应参数和调用示例。

3. 公共请求头

该类接口包含以下 Key （统一小写）：

Key	是否必填	说明
content-type	是	内容类型，除非特殊说明，否则固定使用 `application/json;charset=utf-8`
x-snbps-factory-id	否	工厂 ID
x-snbps-timestamp	否	请求时间。例如 2021-09-17T16:47:05.132+0800
x-snbps-lang	否	语言编号，默认使用英文：en-US，支持中文简体：zh-CN
x-snbps-request-id	否	请求 traceID

3.1 接口调用约定与鉴权

3.1.1 服务地址与请求格式

服务前缀为 {BASE_URL}/api/iot-factory-edge-service，其中 {BASE_URL} 为实际 Edge 地址（含协议、IP/域名和端口），不重复包含服务前缀。下文接口路径均相对于该前缀。

JSON 请求使用 UTF-8 编码；GET 参数通过 URL Query 传递，multipart 文件上传由客户端自动生成 boundary。

3.1.2 工站会话与接口校验

PS 工站调用 /login 后，从返回的 respData.token 获取会话令牌，并在后续请求的 x-snbps-session 请求头中传入。工站会话令牌与烧录 traceId / uuid 是不同标识；x-snbps-request-id 仅用于请求追踪，不能代替业务 traceId。

会话有效期由部署配置决定，调用受保护接口时会刷新有效期。

以下接口由 UkeyPermissionFilter 强制校验：

/assignBatch
/queryPPCBatchInfo
/v1/queryBatchByOrderNumber
/getPPData
/getProgrammingData
/uploadRequestData
/programmingResult
/executeApdu
/v1/eventLog/upload
/v1/matter/onboarding-payloads/recover
/v1/device/information/query
/v1/testFile/upload
/v1/deviceData/upload

校验信息缺失或失效时，返回 HTTP 200，业务码为 8050。

3.1.3 平台鉴权与工厂上下文

平台鉴权由部署配置独立控制。当前仓库的 application.yml 未将以下接口路径排除在平台鉴权范围之外：

/v1/device/detail
/v1/updateDevicesProfile
/v1/deviceData/upload
/executeApdu
/v1/eventLog/upload
/v1/queryBatchByOrderNumber
三个 /generate* 接口路径

当目标环境启用平台鉴权时，调用这些接口还需提供 x-snbps-auth-token。正式联调前应核对目标环境的鉴权配置，不能仅凭有效的工站会话令牌判断接口是否满足全部鉴权要求。

x-snbps-factory-id 用于传递公共工厂信息，当前工厂上下文主要通过平台登录信息或有效工站会话解析，不能仅通过该请求头切换工厂。

3.2 统一响应与错误处理

Factory Edge Service API 通常采用统一的 JSON 响应格式，各字段说明如下：

字段	类型	是否必填 / 条件	说明
success	boolean	响应	`true` 表示业务成功
respCode	string	响应	`8000` 表示成功；其他业务错误码见附录
respMsg	string	响应	状态说明，受语言设置影响
respData	object / array / null	响应	各接口的业务数据；无返回数据或业务失败时通常为 `null`
respTime	integer (int64)	响应	秒级 Unix 时间戳，非字符串

3.2.1 响应示例

{
  "success": true,
  "respCode": "8000",
  "respMsg": "NoError",
  "respData": null,
  "respTime": 1792108800
}

3.2.2 错误处理

业务异常（ClientApiException）和工站会话失效均通过 HTTP 200 返回，调用方不能仅根据 HTTP 状态码判断业务是否成功，还需检查 success 和 respCode。

参数绑定错误、Bean Validation 校验失败、平台鉴权失败及网关错误不保证返回 HTTP 200，应根据实际 HTTP 状态码和响应内容进行处理。

3.2.3 特殊响应

/download 接口成功时直接返回文件流，不使用统一 JSON 响应格式。

4. 接口索引（29 项）

本节列出 Factory Edge Service API 当前提供的 29 个接口，包括请求方法、相对路径、接口功能及调用身份要求。接口鉴权规则详见“接口调用约定与鉴权”章节。

编号	请求 Method	相对路径	接口名称	调用身份
5.1	POST	/v1/device/detail	查询设备详情	平台鉴权按部署配置
5.2	POST	/v1/updateDevicesProfile	更新设备档案信息	平台鉴权按部署配置
5.3	POST	/v1/deviceData/upload	上传设备生产数据	工站会话；平台鉴权见公共约定
5.4	POST	/v1/device/information/query	查询设备综合信息	工站会话；平台鉴权见公共约定
5.5	POST	/v1/matter/onboarding-payloads/recover	找回 Matter 二维码	工站会话；平台鉴权见公共约定
5.6	POST	/v1/testFile/upload	上传设备测试文件	工站会话；平台鉴权见公共约定
5.7	GET	/heartBeat	连接心跳	登录前 / 初始化
5.8	GET	/queryLoginOptions	查询登录选项	登录前 / 初始化
5.9	POST	/queryLoginType	查询工站登录方式	登录前 / 初始化
5.10	GET	/preLogin	U-Safe 预登录	登录前 / 初始化
5.11	POST	/login	工站登录	登录前 / 初始化
5.12	POST	/logout	工站退出登录	按需提供工站上下文
5.13	GET	/v1/queryBatchByOrderNumber	按订单查询批次	工站会话；平台鉴权见公共约定
5.14	POST	/assignBatch	分配工站批次	工站会话；平台鉴权见公共约定
5.15	GET	/queryPPCBatchInfo	查询工站批次信息	工站会话；平台鉴权见公共约定
5.16	GET	/getProgrammingData	获取动态烧录数据	工站会话；平台鉴权见公共约定
5.17	GET	/getMetadata	获取批次元数据	按需提供工站上下文
5.18	GET	/getPPData	获取完整烧录数据（兼容接口）	工站会话；平台鉴权见公共约定
5.19	POST	/uploadRequestData	提交中间烧录请求数据	工站会话；平台鉴权见公共约定
5.20	POST	/programmingResult	上报烧录结果	工站会话；平台鉴权见公共约定
5.21	POST	/executeApdu	执行 SE APDU 步进烧录	工站会话；平台鉴权见公共约定
5.22	POST	/getScriptFile	获取烧录脚本地址	按需提供工站上下文
5.23	GET	/download	下载文件	按需提供工站上下文
5.24	POST	/v1/eventLog/upload	上传设备事件日志	工站会话；平台鉴权见公共约定
5.25	POST	/generateVerifier	生成 Matter Verifier	平台鉴权按部署配置
5.26	POST	/generateOnboardingData	生成 Matter 配网载荷	平台鉴权按部署配置
5.27	POST	/generateUniqueId	生成 Matter Unique ID	平台鉴权按部署配置
5.28	POST	/queryDeviceData	查询设备信息（已废弃）	按需提供工站上下文
5.29	POST	/updateDeviceInfo	更新设备信息（已废弃）	按需提供工站上下文

4.1 接口范围说明

本接口索引覆盖 ProgrammingStationController 和 ExternalSystemController 当前注册的 29 条对外接口路由，不包含后台管理 Controller、调试用 TestController 及已整类注释的 UsbKeyController。

/v1/testData/upload 虽仍存在于过滤器或鉴权排除配置中，但当前控制器未注册该接口。设备生产数据统一通过 /v1/deviceData/upload 上传。

5. 接口列表

5.1 查询设备详情

根据 AND 逻辑组合的定位条件和过滤条件查询设备档案，并根据 queryKeys 返回指定分组或字段。本地未查询到匹配记录时，依次查询历史数据和云端数据。若查询结果包含不同产品或不同 deviceId 的多条记录，返回错误码 8102；若存在同一产品、同一设备的多条记录，则按生产时间选择最新记录返回。

5.1.1 请求 Method

POST

5.1.2 请求 URL

{BASE_URL}/api/iot-factory-edge-service/v1/device/detail

5.1.3 请求 Body

该接口的 Body 包含以下参数：

提示

deviceLocator 中的 chipUid、bleMac、serialNumber、matterQrcode、matterManualCode 至少需要提供一项非空值，其余参数作为辅助查询条件，所有查询条件均采用 AND 逻辑组合。调用时应提供足够精确的参数，以确保定位目标设备。queryKeys 仅用于指定返回的数据分组或字段，不参与设备查询条件的匹配。

名称	类型	是否必填	说明
deviceLocator	object	是	用来检索设备的基础信息，选择 `deviceLocator` 作为查询条件时， `chipUid`，`bleMac`，`serialNumber`，`matterQrcode`，`matterManualCode` 至少必填一项
├──chipUid	string	否	烧录设备芯片中的 `mcuId`
├──bleMac	string	否	芯片蓝牙 mac 地址
├──serialNumber	string	否	烧录设备流水号
├──matterQrcode	string	否	matter 配网二维码
├──matterManualCode	string	否	matter 手工配网码
filters	object	否	提高定位设备的辅助过滤条件，用于提高设备查询精确度
├──productionTimeStart	string	否	设备烧录生产开始时间，日期格式：2025-12-16T12:02:58+08:00
├──productionTimeEnd	string	否	设备烧录生产完成时间，日期格式：2025-12-17T12:02:58+08:00
├──batchId	string	否	设备生产时的批次号
matter	object	否	matter 相关设备参数，携带该参数用于提高设备查询精确度
├──pid	string	否	matter 设备所属 PID，增加此参数条件有助于提高查询设备的精确度
├──vid	string	否	matter 设备所属 VID，增加此参数条件有助于提高查询设备的精确度
customParams	object	否	自定义条件过滤参数，详情请参考 customParams 参数说明
queryKeys	string[]	建议提供	以字符串数组形式传入，支持指定分组名（如 `matterData`）或字段名（如 `chipData.chipUid`）。本地设备档案匹配成功后，若未提供 `queryKeys` 或传入空数组，则返回空对象 `{}`，不会默认返回所有字段。支持的 key 请参考可查询键列表 (queryKeys V2)

customParams 参数说明

本接口支持通过该参数传入自定义查询条件，以实现更灵活的数据过滤。当需要根据业务中自定义上传的字段查询数据时，可将对应字段名与期望值构造成键值对，放入此对象中。

customParams 参数结构

类型：JSON 对象（键值对集合）。
键（key）：要匹配的扩展字段名（例如 "customData"）。
值（value）：该字段期望匹配的值（例如 "customDataValue"）。

示例

{"customData1": "customDataValue1", "customData2": "customDataValue2"}

表示查询设备上报数据 customData1 为 “customDataValue1” 且 customData2 为 “customDataValue2” 的记录。

名称	类型	是否必须	说明
key	string	是	用于查询设备档案信息中的基础 key 值。可使用的 key 由系统生成，或在烧录过程中自定义上传的 key 集合
value	string	是	每个 key 对应查询参数的值。

5.1.4 返回参数

提示

下表展示的是查询所有 queryKeys 时返回的数据。在实际使用中，按需查询可适当提升接口性能。

名称	类型	说明
respCode	string	`8000` 表示成功，其他均表示异常，具体异常信息可见于 `respMsg`
respMsg	string	响应信息，例如 `NoError` 或 `DataNotFound`
respData	object	查询结果数据
├──matterData	object	Matter 数据相关
├──iterations	string	迭代次数
├──commissioningFlows	string	配网流程
├──discoverableMode	string	设备可发现模式
├──vid	string	厂商 ID
├──pid	string	产品 ID
├──discriminator	string	区分码
├──enableRotatingDeviceId	string	启用旋转设备标识符
├──manualCode	string	手工配对码
├──passcode	string	配对码
├──qrcode	string	matter 配网二维码
├──salt	string	盐值
├──saltLength	string	盐值长度
├──uniqueid	string	设备范围内唯一标识符
├──verifier	string	密码验证器
├──serialNumber	string	matter 烧录设备流水号
├──dacCertMd5	string	DAC 证书 MD5
├──cdFileMd5	string	CD 文件 MD5
├──cdFileName	string	CD 文件名称
├──paiCertMd5	string	PAI 证书 MD5
├──factoryData	object	Factory Data 配置相关
├──vendorName	string	厂商名称
├──hardwareVersion	string	硬件版本
├──hardwareVersionString	string	硬件版本字符串
├──partNumber	string	部件号
├──productUrl	string	产品网址
├──productLabel	string	产品标签
├──productName	string	产品名称
├──startAddress	string	起始地址
├──programmingData	object	设备烧录结果相关
├──programmingStatus	string	设备烧录状态：成功: `success` 失败: `failure` 进行中: `pending`
├──programmingLog	string	烧录日志
├──programmingTime	string	烧录时间
├──chipData	object	芯片数据相关
├──chipUid	string	烧录设备芯片中的 mcuId
├──bleMac	string	芯片蓝牙 mac 地址
├──firmwareData	object[]	固件相关
├──fwName	string	固件名称
├──fwMd5	string	固件 MD5
├──customData	object	客户方在生产时上报的自定义数据

5.1.5 请求示例

{
  "deviceLocator": {
    "chipUid": "f9e203b4cf3ce632363736425055f321",
    "bleMac": "f9:e2:03:b4:cf:3c:e6:32",
    "serialNumber": "8360224622727172372"
  },
  "filters": {
    "productionTimeStart": "2025-12-16T12:02:58+08:00",
    "batchId": "7603594830282752"
  },
  "matter": {
    "pid": "8001",
    "vid": "FFF2"
  },
  "customParams": {
    "customData1": "nPK3DqGQQwdE3fYxaofURw==",
    "customData2": "1"
  },
  "queryKeys": [
    "matterData.vid",
    "matterData.pid",
    "matterData.manualCode",
    "matterData.passcode",
    "matterData.qrcode",
    "matterData.salt",
    "matterData.uniqueid",
    "matterData.verifier",
    "matterData.serialNumber",
    "matterData.dacCertMd5",
    "matterData.paiCertMd5",
    "factoryData.vendorName",
    "factoryData.hardwareVersion",
    "factoryData.hardwareVersionString",
    "factoryData.partNumber",
    "factoryData.productUrl",
    "factoryData.productLabel",
    "factoryData.productName",
    "programmingData.programmingStatus",
    "chipData.chipUid",
    "chipData.bleMac",
    "firmwareData.fwName",
    "firmwareData.fwMd5"
  ]
}

5.1.6 响应示例

注意：本响应示例展示全部结果信息。在实际使用中，请根据 queryKeys 查询参数获取指定的结果数据。

{
  "success": true,
  "respCode": "8000",
  "respMsg": "NoError",
  "respData": {
    "matterData": {
      "vid": "FFF2",
      "pid": "8001",
      "manualCode": "20761614023",
      "passcode": "22977984",
      "qrcode": "MT:634J0-C714UM2X1HI00",
      "salt": "jBRIAMrVMVpvwAbCQ1Hmz9/sIATvea2p2KsFAaEw7a8=",
      "uniqueid": "nPK3DqGQQwdE3fYxaofURw==",
      "verifier": "TYoyImPfYZSaonfzSxlTnhzSJMuLMXnUZ1lgeQUIEIUESKVboFoQjzLVmwsAl9TUzYjwcbnpflP9WpTIzMNzpxedPeNIqwYk60nYXymhyziGOG/VZjwSHiRb+5xkS2Pn7w==",
      "dacCertMd5": "61FC127CD890B6BE828001753161CDE1",
      "paiCertMd5": "61FC127CD890B6BE828001753161CD41"
    },
    "factoryData": {
      "vendorName": "vn",
      "hardwareVersion": "1",
      "hardwareVersionString": "121",
      "partNumber": "1234",
      "productUrl": "456",
      "productLabel": "789",
      "productName": "pn"
    },
    "programmingData": {
      "programmingStatus": "success"
    },
    "firmwareData": [
      {
        "fwName": "81204_Ctrl_Multi_qpg6200_X_09B9_20250206_V1.8.5.hex",
        "fwMd5": "61FC127CD890B6BE828001753161CD42"
      },
      {
        "fwName": "81204_Ctrl_Multi_qpg6200_X_09B9_20251215_V2.0.1.hex",
        "fwMd5": "61FC127CD890B6BE828001753111CD12"
      }
    ],
    "chipData": {
      "chipUid": "0b90cff640d5daf4",
      "bleMac": "00:00:00:04:C9:84"
    }
  },
  "respTime": 1765768529
}

5.1.7 当前实现说明

支持的数据分组： matterData、factoryData、programmingData、chipData、firmwareData、customData、seData。
字段返回规则： seData 仅支持整组返回，指定 seData.xxx 时也不会按子字段过滤。queryKeys 中包含未知分组时，不会返回额外数据；查询字段为空或对应数据未存储时，可能返回空值。
烧录数据： programmingData.programmingStatus 支持 success、failure 和 pending 三种状态。当前本地数据构造逻辑未向 programmingLog 赋予实际日志内容，不应依赖该字段获取烧录日志。
接口鉴权：本接口不属于 UkeyPermissionFilter 强制校验工站会话的接口，平台鉴权要求见“接口调用约定与鉴权”章节。

5.2 更新设备档案信息

工厂在修改设备烧录数据后，可以通过此接口实现设备信息的同步，将修改信息同步至 OBIS 统一管理。

5.2.1 请求 Method

POST

5.2.2 请求 URL

{BASE_URL}/api/iot-factory-edge-service/v1/updateDevicesProfile

5.2.3 请求 Body

该接口的 Body 包含以下参数：

名称	类型	是否必填	说明
deviceLocator	object	是	用来检索设备的基础信息，选择 `deviceLocator` 作为查询条件时， `chipUid`，`bleMac`，`serialNumber`，`matterQrcode`，`matterManualCode` 至少必填一项。
├──chipUid	string	否	烧录设备芯片中的 `mcuId`
├──bleMac	string	否	芯片蓝牙 mac 地址
├──serialNumber	string	否	烧录设备流水号
├──matterQrcode	string	否	matter 配网二维码
├──matterManualCode	string	否	matter 手工配网码
filters	object	否	提高定位设备的辅助过滤条件，用于提高设备查询精确度
├──productionTimeStart	string	否	设备烧录生产开始时间，日期格式：2025-12-16T12:02:58+08:00
├──productionTimeEnd	string	否	设备烧录生产完成时间，日期格式：2025-12-17T12:02:58+08:00
├──batchId	string	否	设备生产时的批次号
matter	object	否	matter 相关设备参数，携带该参数用于提高设备查询精确度
├──pid	string	否	matter 设备所属 PID，增加此参数条件有助于提高查询设备的精确度
├──vid	string	否	matter 设备所属 VID，增加此参数条件有助于提高查询设备的精确度
customParams	object	否	自定义条件过滤参数，详情请参考 customParams 参数说明
updateParams	object[]	否	更新项以数组形式传入，每项包含 `type`、`key` 和 `value` 字段，类型均为 `string`。传入空数组时不执行字段更新。支持的 `key` 及操作范围请参考 updateParams 参数说明

updateParams 参数说明

本接口支持通过该参数传入系统支持的 key，以实现对指定设备字段记录的修改。当需要更新设备字段记录时，可将字段名，目标值及操作类型（type）组合成数组后一并传入。

updateParams 参数结构

类型：JSON 数组。
当 type 为 add 时，新增一条 key 对应的字段记录；如果该 key 已存在，则更新其对应的字段值。
部分设备数据支持删除，当 type 为 delete 时，删除 key 对应的字段记录。
该参数支持的 key 详情请参考可更新键列表 (updateDevicesProfile)。

示例

[
    {
        "type": "add",
        "key": "qrcode",
        "value": "MT:XXX-S0XXXX"
    },
    {
        "type": "delete",
        "key": "factoryData.productURL"
    },
    {
        "type": "add",
        "key": "factoryData.qqbb",
        "value": "abcd"
    },
    {
        "type": "add",
        "key": "firmwareData.bootloader-xxx-1.1.s37",
        "value": "00000001"
    }
]

以上示例表示：

新增 qrcode 字段，并将其值设置为 MT:XXX-S0XXXX；如果对应设备中已存在该字段，则覆盖原有值。
删除对应设备 factoryData 中的 productURL 字段。
在对应设备的 factoryData 中新增 qqbb 字段，并将其值设置为 abcd。
对应设备的固件列表中新增固件 bootloader-xxx-1.1.s37，并将其 startAddress 设置为 00000001。如果设备中已存在同名固件，则将其起始地址更新为该值。

5.2.4 返回参数

名称	类型	说明
respCode	string	`8000` 表示成功，其他均表示异常，具体异常信息可见于 `respMsg`
success	bool	`true` 表示成功
respMsg	string	响应信息，例如 `NoError` 或 `DataNotFound`

5.2.5 请求示例

{
  "deviceLocator": {
    "chipUid": "f9e203b4cf3ce632363736425055f321"
  },
  "filters": {
    "productionTimeStart": "2025-12-16T12:02:58+08:00",
    "batchId": "7603594830282752"
  },
  "matter": {
    "pid": "8001",
    "vid": "FFF2"
  },
  "customParams": {
    "customData1": "nPK3DqGQQwdE3fYxaofURw=="
  },
  "updateParams": [
    {
      "type": "add",
      "key": "qrcode",
      "value": "MT:XXX-S0XXXX"
    },
    {
      "type": "delete",
      "key": "factoryData.productURL",
      "value": ""
    },
    {
      "type": "add",
      "key": "factoryData.qqbb",
      "value": "abcd"
    },
    {
      "type": "add",
      "key": "firmwareData.bootloader-xxx.s37",
      "value": "00000000"
    }
  ]
}

5.2.6 响应示例

{
  "success": true,
  "respCode": "8000",
  "respMsg": "NoError",
  "respTime": 1765768529
}

5.2.7 操作规则与边界

更新参数 updateParams 中各字段的要求如下：

字段	类型	是否必填 / 条件	说明
updateParams[].type	string	按操作传入	`add` 表示新增或覆盖；`delete` 仅适用于支持删除操作的集合字段
updateParams[].key	string	是	支持附录三中列出的系统键或集合前缀
updateParams[].value	string	add 时传入	仅接收字符串，日期和整数文本需符合目标字段的格式要求

设备定位与更新范围

deviceLocator、filters、matter 和 customParams 的设备定位规则与“查询设备详情”接口一致。更新操作仅针对本地设备档案，不查询历史数据或云端数据。

字段取值规则

环境值仅支持 test 和 prod。
programmingStatus 支持 Complete、Failed 和 Unreported，其他值当前按未完成状态处理。

字段更新与删除规则

支持删除的字段： factoryData.*、firmwareData.*、otherFile.*、attachment.* 和 programmingScript。
不支持删除的字段：标量键及 extend.* 当前直接按 value 赋值，不支持通过 delete 操作删除。
未知字段：当前会跳过未知 key，不保证返回参数错误。

其他处理规则

updateParams 为空数组时，不执行字段更新，但仍会尝试读取目标设备档案及元数据。
更新完成后，记录将标记为等待同步状态。收到 HTTP 响应不代表数据已完成云端同步。

5.3 上传设备生产数据

工厂可通过此接口上传设备生产过程中的烧录、测试及组装数据，并根据 traceId 维护对应的生产记录。烧录结束时复用 programmingResult 接口的处理逻辑，测试及组装数据通过后续异步流程同步。

5.3.1 请求 Method

POST

5.3.2 请求 URL

{BASE_URL}/api/iot-factory-edge-service/v1/deviceData/upload

5.3.3 请求头

本接口的 Content-Type 为 application/json。除公共请求头外，还需提供以下请求头：

字段	是否必填	说明
x-snbps-session	是	工站会话令牌，使用 `/login` 接口返回的 `token`

平台鉴权要求见“接口调用约定与鉴权”章节。

5.3.4 请求 Body

该接口的 Body 包含以下参数：

名称	类型	是否必填 / 条件	说明
traceId	string	按场景传入	生产记录跟踪 ID，兼容别名 `uuid`。烧录场景使用 `/getProgrammingData` 返回的 `uuid`；未提供时可创建新记录。传入的值须对应已有生产记录或文件任务，否则返回 `8006`
scenarioType	string	测试 / 自定义场景必填	生产场景名称，如 `RF-Test`。组装批次固定为 `assembly`，已有烧录会话固定为 `programming`；其他场景缺失时返回 `8069`
deviceId	string	测试 / 组装对接必填	设备 MCU ID，未提供时使用 `deviceRecord.deviceId`
batchId	string	组装对接必填	生产批次 ID，仅纯数字字符串按 ID 处理。组装场景根据批次类型识别，不能仅通过 `scenarioType=assembly` 判断
deviceProfileId	string	否	已有设备档案 ID，应与 `deviceId` 对应；未提供时根据设备 ID 匹配已有档案
stationId	string	否	工站编码，未提供时使用当前会话对应的工站，不限于数字
factoryId	string	否	工厂 ID，新建记录时仅纯数字字符串生效，否则使用当前会话对应的工厂
deviceSn	string	否	设备序列号
result	boolean	烧录场景建议提供	烧录结果，`true` 表示成功，`false` 表示失败；烧录结束时未提供则按失败处理
failureReason	string	否	失败原因，写入生产记录
timestamp	string	否	当前接口未使用该字段设置生产记录时间，记录创建时间由服务端生成
status	string	否	自定义状态。烧录和组装场景可能由系统执行结果生成并覆盖；其他非空值写入 `customStatus`
deviceRecord	object	按场景对接约定传入	设备生产数据，兼容别名 `deviceProfile`，具体字段见 deviceRecord 参数说明

5.3.5 deviceRecord 参数说明

deviceRecord 用于上传设备在当前生产环节产生的数据。

名称	类型	是否必填 / 条件	说明
deviceId	string	条件必填	设备 MCU ID，当请求 Body 顶层的 `deviceId` 为空时使用该字段
firmwareVersion	string	烧录场景按需提供	固件版本
seid	string	SE 烧录时按需提供	SEID，字段名使用小写
cplc	string	SE 烧录时按需提供	CPLC 数据
matterData	map	Matter 烧录时按需提供	实际烧录的 Matter 数据
factoryData	map	否	实际烧录的 Factory Data，字段名不能为空，值必须为字符串
customData	map	否	自定义数据，最多 50 个字段；字段名不能为空且不超过 64 个字符，值必须为字符串，否则返回 `8002`。本次上传将整体替换原有 `customData`
testData	map	测试 / 组装对接必填	测试数据，兼容旧字段名 `diagnosticData`。值可以是文本或文件引用列表；同名字段均为列表时追加，否则覆盖

5.3.6 场景处理规则

不同生产场景下的参数要求及处理规则如下：

场景	traceId 与批次	数据与状态
烧录	使用已创建的烧录会话 `traceId`，通常来自 `/getProgrammingData` 接口	根据实际烧录内容提供 `deviceRecord`，并明确传入 `result`。烧录结束时复用 `/programmingResult` 的处理逻辑，仅设置 `scenarioType=programming` 不会创建完整的烧录流程
测试 / 自定义	首次上传可不提供 `traceId`，后续上传使用响应返回的 `traceId`；`scenarioType` 必填	按对接要求提供 `deviceId` 和 `deviceRecord.testData`。若存在对应设备档案，则关联该档案；否则可仅创建生产记录，`deviceProfileId` 返回 `null`
组装	`batchId` 指定组装批次；`traceId` 可来自 `/getProgrammingData` 接口或文件任务，首次未提供时也可创建新记录	提供 `deviceId` 和 `deviceRecord.testData`，场景固定为 `assembly`。`testData.result` 参与结果状态和产量计算，同一设备在同一批次中的成功组装记录按当前实现去重

参数长度与格式限制

数据库字段长度限制如下：

字段	最大长度
traceId	64 字符
deviceId	128 字符
deviceSn	64 字符
failureReason	1024 字符
status / scenarioType	64 字符

上述长度限制并不代表接口会自动校验所有请求字段。ID 值应在 Java Long 类型的取值范围内。字段超长、数字格式不合法或不符合数据库约束时，可能导致数据保存失败。纯数字字符串也必须符合相应的长度和取值范围要求。

其他处理规则

烧录数据：按对接约定，deviceRecord.firmwareVersion、deviceRecord.seid、deviceRecord.cplc 和 deviceRecord.matterData 至少提供一项，但当前接口未对此要求执行强制校验。
测试与组装数据：使用 deviceRecord.testData 上传测试数据。请求 Body 顶层的 customData 不会被识别为 deviceRecord.customData。

5.3.7 请求示例

烧录场景

使用 /getProgrammingData 返回的 uuid 作为 traceId，并提交烧录结果及设备数据。

{
  "traceId": "<uuid returned by getProgrammingData>",
  "deviceId": "DEVICE-001",
  "result": true,
  "deviceRecord": {
    "firmwareVersion": "1.2.3",
    "matterData": {
      "qrcode": "<actual commissioning payload>"
    },
    "customData": {
      "mac": "AA:BB:CC:DD:EE:FF"
    }
  }
}

测试场景

首次测试上报可不提供 traceId，通过 scenarioType 指定测试场景，并在 testData 中提交测试数据。

{
  "scenarioType": "RF-Test",
  "deviceId": "DEVICE-001",
  "status": "success",
  "deviceRecord": {
    "testData": {
      "voltage": "3.3",
      "result": "success"
    },
    "customData": {
      "fixture": "A01"
    }
  }
}

组装场景

通过 batchId 指定组装批次，首次上报可不提供 traceId。

{
  "batchId": "<actual assembly batch ID>",
  "deviceId": "DEVICE-001",
  "deviceRecord": {
    "testData": {
      "eol": "pass",
      "result": "success"
    }
  }
}

5.3.8 文件与生产数据关联

需要关联测试文件时，先调用 POST /v1/testFile/upload 上传文件，并保存返回的 traceId。随后使用相同的 traceId 调用本接口，通过 testData 中的 fileName 引用对应文件。

如果已有生产记录的 traceId，也可以在文件上传时直接传入。fileTraceId 为内部关联字段，无需在本接口请求顶层额外提供。

请求示例：

{
  "traceId": "<traceId returned by testFile/upload>",
  "scenarioType": "RF-Test",
  "deviceId": "DEVICE-001",
  "deviceRecord": {
    "testData": {
      "report": [
        {
          "fileName": "report.txt"
        }
      ]
    }
  }
}

5.3.9 返回参数

本接口采用统一 JSON 响应格式，公共响应字段见“统一响应与错误处理”章节。respData 包含以下字段：

字段	类型	说明
traceId	string	服务端最终使用的跟踪 ID，后续上传时原样回传
deviceProfileId	integer (int64) / null	已关联的设备档案 ID，未关联时为 `null`
programmingRecordId	integer (int64)	设备生产记录 ID

5.3.10 响应示例

{
  "success": true,
  "respCode": "8000",
  "respMsg": "NoError",
  "respData": {
    "traceId": "example-trace-id",
    "deviceProfileId": 200,
    "programmingRecordId": 11
  },
  "respTime": 1792108800
}

5.3.11 主要错误码

错误码	说明
8002	自定义字段不符合要求
8006	`traceId` 未关联已有生产记录或文件任务
8007	数据保存失败
8032	批次不存在
8037	设备建档失败
8050	工站会话失效
8069	测试或自定义场景缺少 `scenarioType`

5.3.12 HTTP 调用示例与续传

以下示例使用 curl 首次上传测试数据。BASE_URL 仅包含协议、主机和端口，例如 http://edge-host:8005；SESSION 为工站调用 /login 获取的会话令牌。如目标环境启用平台鉴权，还需提供 x-snbps-auth-token 请求头。

curl -X POST "$BASE_URL/api/iot-factory-edge-service/v1/deviceData/upload" \
  -H "Content-Type: application/json;charset=utf-8" \
  -H "x-snbps-session: $SESSION" \
  -d '{
    "scenarioType": "RF-Test",
    "deviceId": "DEVICE-001",
    "status": "success",
    "deviceRecord": {
      "testData": {"voltage": "3.3", "result": "success"},
      "customData": {"fixture": "A01"}
    }
  }' 

续传规则与注意事项

跟踪 ID：首次上传成功后，保存响应中的 respData.traceId。后续上传同一生产记录时，在请求顶层传入该值，并继续提供 scenarioType。不同的独立测试不应复用已有 traceId。
标识使用： x-snbps-request-id 仅用于请求追踪，不能代替业务 traceId。传入不存在且未关联文件任务的 traceId 时，返回 8006。
测试数据：同一 traceId 下，testData 的同名列表字段会追加数据，重复请求可能产生重复的附件引用。
自定义数据： customData 每次上传均整体替换原有数据，续传时应提交需要保留的全部自定义字段。
重复请求：网络超时后，不能直接假定上一次请求未执行，也不能将重复上传视为完全幂等操作。

5.4 查询设备综合信息

本接口用于查询本地设备档案中的通用信息、Matter 数据及指定的自定义数据。与 /v1/device/detail 不同，本接口不支持通过 queryKeys 指定返回字段。

5.4.1 请求 Method

POST

5.4.2 请求 URL

{BASE_URL}/api/iot-factory-edge-service/v1/device/information/query

5.4.3 请求头

除公共请求头外，本接口还需提供以下请求头：

字段	是否必填	说明
x-snbps-session	是	工站会话令牌，使用 `/login` 接口返回的 `token`

5.4.4 请求 Body

该接口的 Body 包含以下参数，至少提供一个非空设备标识。

字段	类型	是否必填 / 条件	说明
deviceId	string	至少提供一项	按设备档案中的 `deviceId` 精确匹配，最长 128 字符
chipId	string	至少提供一项	按设备档案中的 `chipUid` 精确匹配，最长 128 字符
uniqueId	string	至少提供一项	按 Matter 数据中的 `uniqueId`、`uniqueid`及对应的 `snake_case` 字段匹配，最长 128 字符

5.4.5 接口说明

查询条件：多个非空设备标识按 AND 关系组合，所有条件均满足时才匹配。
查询范围：仅查询本地设备档案，不查询历史数据库或云端。未找到匹配记录时返回 8101。
查询结果：存在多条匹配记录时，返回查询结果中的第一条，不保证设备标识的唯一性，也不保证仅返回烧录成功的设备。
烧录状态：当前 provisionStatus 固定返回 Success，不能单独作为判断设备实际烧录状态的依据。

5.4.6 请求示例

{
  "deviceId": "DEVICE-001"
}

5.4.7 返回参数

接口采用统一 JSON 响应格式，respData 包含以下数据对象：

字段	类型	说明
generalData	object	设备身份、烧录相关信息及产品版本信息
matterData	object / null	Matter 证书及配网数据，非 Matter 设备可能返回 `null`
customData	object	设备序列号、业务标识、MAC 地址及测试、标定数据

未记录的字段可能为空。

5.4.8 返回示例

{
  "success": true,
  "respCode": "8000",
  "respMsg": "NoError",
  "respData": {
    "generalData": {
      "deviceId": "DEVICE-001",
      "provisionStatus": "Success",
      "provisionTime": "2026-10-16T02:00:00Z",
      "sourceProgramingBatchId": "10",
      "provisionFactoryId": "20",
      "provisionStationId": "30",
      "productId": "40",
      "productName": "sample product",
      "productVersionId": "50",
      "productVersionName": "1.0"
    },
    "matterData": null,
    "customData": {
      "serialNumber": "SN-001",
      "customId": "CUSTOM-001",
      "macAddress": "AA:BB:CC:DD:EE:FF",
      "factoryTestData": null,
      "calibrationParams": null
    }
  },
  "respTime": 1792108800
}

5.4.9 响应字段说明

generalData：通用信息

提示

sourceProgramingBatchId 为实际响应字段名，保留原有的 Programing 拼写。

字段	类型	说明
deviceId	string	设备 ID
provisionStatus	string	烧录状态，当前固定返回 `Success`
provisionTime	string	烧录时间，采用 UTC ISO 8601 格式
sourceProgramingBatchId	string	来源烧录批次 ID
provisionFactoryId	string	烧录工厂 ID
provisionStationId	string	烧录工站 ID，对应设备档案中的工站主键
productId	string	产品 ID
productName	string	产品名称
productVersionId	string	产品版本 ID
productVersionName	string	产品版本名称

matterData：Matter 数据

字段	类型	说明
dacCert	string	DAC 证书，沿用存储的 Base64 DER 或 PEM 格式
paiCert	string	PAI 证书，沿用存储的 Base64 DER 或 PEM 格式
certDeclaration	string	Certification Declaration（CD），Base64 编码
discriminator	integer	Matter Discriminator，十进制数值
spake2pIterationCount	integer	SPAKE2+ 迭代次数
passcode	string	Matter 配网密码
manualPairingCode	string	Matter 手动配对码
setupPayload	string	Matter 配网载荷
spake2pVerifier	string	SPAKE2+ Verifier，沿用存储值
spake2pSalt	string	SPAKE2+ Salt，沿用存储值

customData：自定义数据

提示

factoryTestData 和 calibrationParams 返回前会递归清理已定义的凭据字段，不返回设备私钥。

字段	类型	说明
serialNumber	string	设备序列号
customId	string	业务标识
macAddress	string	MAC 地址
factoryTestData	JSON	工厂测试数据
calibrationParams	JSON	设备标定参数

5.4.10 主要错误码

错误码	说明
8002	查询参数全部为空
8007	存储数据解析失败
8050	鉴权失败
8101	未找到匹配设备

其他错误码见附录。

5.5 找回 Matter 二维码

本接口用于在组装阶段，根据组装批次关联的投入烧录批次，以及 Matter VID、PID、Discriminator 和 BLE 广播中的 Rotating Device Identifier（RDI），查找已成功烧录的本地设备档案，恢复对应的 Matter 配网数据。

5.5.1 请求 Method

POST

5.5.2 请求 URL

{BASE_URL}/api/iot-factory-edge-service/v1/matter/onboarding-payloads/recover

5.5.3 请求头

除公共请求头外，本接口还需提供以下请求头：

参数	是否必填	说明
x-snbps-session	是	工站会话令牌，使用 `/login` 接口返回的 `token`

5.5.4 请求 Body

该接口的 Body 包含以下参数：

字段	类型	是否必填	说明
batchId	string	是	组装批次 ID，须已关联投入烧录批次，且处于 `RUNNING` 状态、未过期
matterProductId	string	是	Matter PID，十六进制字符串，不带 `0x` 前缀；字段名不能使用 `productId` 或 `pid`
matterVendorId	string	是	Matter VID，十六进制字符串，不带 `0x` 前缀；字段名不能使用 `vendorId` 或 `vid`
discriminator	string	是	十六进制字符串，解析后的数值范围为 `0x000–0xFFF`，例如 `0F00`，不能使用十进制字符串
rotatingDeviceIdentifier	string	是	BLE 广播中的 RDI，18 字节（36 位十六进制字符），不带 `0x` 前缀，须使用实际广播数据

5.5.5 接口说明

查询范围：仅查询组装批次关联的投入烧录批次中已成功烧录的本地设备档案，不通过云端反查 RDI。
设备匹配：根据 VID、PID、Discriminator 和 RDI 匹配设备。RDI 不匹配或未找到对应设备时，均返回 8101。
数据格式： VID 和 PID 按数据库中的文本值匹配，调用时应保持与批次数据一致的格式。

5.5.6 请求示例

{
  "batchId": "<assembly batch ID>",
  "matterProductId": "8001",
  "matterVendorId": "FFF2",
  "discriminator": "0F00",
  "rotatingDeviceIdentifier": "<actual 36-character hexadecimal BLE advertising RDI>"
}

5.5.7 返回参数

接口采用统一 JSON 响应格式。当前实现的 respData 返回以下四个字段，并非仅返回 setupPayload：

字段	类型	说明
setupPayload	string	Matter 二维码配网载荷
deviceId	string	设备 ID
deviceProfileId	integer	设备档案 ID
manualCode	string	Matter 手动配网码，字段名为 `manualCode`，不能使用 `manualPairingCode`

5.5.8 返回示例

{
  "success": true,
  "respCode": "8000",
  "respMsg": "NoError",
  "respData": {
    "setupPayload": "<actual QR code payload>",
    "deviceId": "DEVICE-001",
    "deviceProfileId": 200,
    "manualCode": "<actual manual pairing code>"
  },
  "respTime": 1792108800
}

5.5.9 主要错误码

错误码	说明
8002	Discriminator 参数无效
8009	批次已过期
8010	批次未处于运行状态
8032	组装批次或关联关系不存在
8050	鉴权失败
8101	未找到匹配设备

其他错误码见附录。

5.6 上传设备测试文件

本接口用于上传设备测试文件。接口接收文件后，先将文件保存至本地并创建异步上传任务。接口收到 HTTP 响应仅表示文件已被接收并完成本地处理，不代表文件已成功上传至云存储。

5.6.1 请求 Method

POST

5.6.2 请求 URL

{BASE_URL}/api/iot-factory-edge-service/v1/testFile/upload

5.6.3 请求头

本接口的 Content-Type 为 multipart/form-data。除公共请求头外，还需提供以下请求头：

参数	是否必填	说明
x-snbps-session	是	工站会话令牌，使用 `/login` 接口返回的 `token`

5.6.4 请求 Body

该接口使用 multipart/form-data 上传文件，包含以下参数：

字段	类型	是否必填	说明
traceId	string（form field）	否	已有脚本跟踪 ID 可传入；未提供时自动生成。接口返回的 `traceId` 应原样传递给生产数据上传接口
files	file[]（multipart parts）	是	上传的文件列表，至少包含一个非空文件。同一请求上传多个文件时，重复使用 `files` 字段。文件名不得包含路径，不得为 `.` 或 `..`，同一请求中的文件名不得重复

5.6.5 接口说明

文件处理：接口接收文件后，先保存至本地，再创建异步上传任务。
任务跟踪：可传入已有的 traceId，未提供时由接口自动生成。返回的 traceId 应原样用于后续生产数据上传接口。
上传状态： HTTP 请求成功不代表文件已上传至云存储。后台异步上传过程中发生的错误，不一定会体现在首次 HTTP 响应中。
文件大小限制：文件大小受部署环境的 multipart 配置限制。application.yml 默认单文件最大 2 GB、单次请求最大 4 GB；dev 配置分别为 200 MB 和 250 MB。实际限制可能被环境变量或外部配置覆盖。

5.6.6 请求示例

curl -X POST "$BASE_URL/api/iot-factory-edge-service/v1/testFile/upload" \
  -H "x-snbps-session: $SESSION" \
  -F "files=@./report.txt" \
  -F "files=@./photo.png"

5.6.7 返回参数

接口采用统一 JSON 响应格式，respData 包含以下字段：

字段	类型	说明
traceId	string	文件任务跟踪 ID
fileCount	integer	本次接收的文件数量
status	integer	文件异步上传任务状态：`1` 待同步；`2` 上传中；`3` 成功；`4` 等待重试；`5` 失败；`6` 本地已清理

5.6.8 返回示例

{
  "success": true,
  "respCode": "8000",
  "respMsg": "NoError",
  "respData": {
    "traceId": "example-file-trace-id",
    "fileCount": 2,
    "status": 1
  },
  "respTime": 1792108800
}

5.6.9 主要错误码

错误码	说明
8057	上传参数错误
8058	文件清单或文件名不符合要求
8059	文件本地存储失败
8060	文件上传任务保存失败
8061	后台云存储上传失败
8051	存储空间不足或并发处理压力

后台异步上传过程中产生的错误不一定出现在首次 HTTP 响应中。其他错误码见附录。

5.7 连接心跳

本接口用于烧录客户端检测 Edge 服务的连通性。

5.7.1 请求 Method

GET

5.7.2 请求 URL

{BASE_URL}/api/iot-factory-edge-service/heartBeat

5.7.3 请求参数

本接口为初始化接口，不要求提前获取工站会话令牌，无需提供请求参数。

5.7.4 接口说明

客户端可根据需要定期调用本接口。心跳请求成功仅表示 Edge HTTP 服务可访问，不代表其他业务服务均正常运行。

5.7.5 请求示例

GET {BASE_URL}/api/iot-factory-edge-service/heartBeat

5.7.6 返回参数

接口采用统一 JSON 响应格式，成功时 respData 为 null。

5.7.7 返回示例

{
  "success": true,
  "respCode": "8000",
  "respMsg": "NoError",
  "respData": null,
  "respTime": 1792108800
}

5.8 查询登录选项

本接口用于兼容旧版客户端，查询工站绑定批次是否要求使用 U-Safe 和生产密码。

5.8.1 请求 Method

GET

5.8.2 请求 URL

{BASE_URL}/api/iot-factory-edge-service/queryLoginOptions

5.8.3 请求参数

本接口为初始化接口，不要求提前获取工站会话令牌。该接口通过 Query 参数传递以下字段：

字段	类型	是否必填 / 条件	说明
usafeSN	string	与 stationId 至少提供一项	旧版 U-Safe 编号
stationId	string	与 usafeSN 至少提供一项	工站编码，提供时优先使用

5.8.4 接口说明

查询条件：工站及其绑定批次必须存在。
兼容性：本接口用于兼容旧版客户端。新登录流程可先调用 /queryLoginType 查询工站登录方式。

5.8.5 请求示例

GET {BASE_URL}/api/iot-factory-edge-service/queryLoginOptions?stationId=STATION-001

5.8.6 返回参数

接口采用统一 JSON 响应格式，respData 包含以下字段：

字段	类型	说明
requireUsafe	boolean	是否要求 U-Safe，当前固定返回 `true`
requirePassword	boolean	是否要求生产密码，由绑定批次的生产密码开关决定

5.8.7 返回示例

{
  "success": true,
  "respCode": "8000",
  "respMsg": "NoError",
  "respData": {
    "requireUsafe": true,
    "requirePassword": false
  },
  "respTime": 1792108800
}

5.8.8 主要错误码

错误码	说明
8007	未找到工站或绑定批次

其他错误码见附录。

5.9 查询工站登录方式

本接口用于查询指定工站的登录方式，并兼容客户端信息上报。

5.9.1 请求 Method

POST

5.9.2 请求 URL

{BASE_URL}/api/iot-factory-edge-service/queryLoginType

5.9.3 请求 Body

本接口为初始化接口，不要求提前获取工站会话令牌。该接口的 Body 包含以下参数：

字段	类型	是否必填 / 条件	说明
factoryId	integer（int64）	云工厂必填	云模式下校验指定工厂存在且为云工厂
stationId	string	是	工站编码
clientPcMessage	string	否	客户端信息的 JSON 对象字符串，自 3.3.2 起标记为废弃，新客户端应通过 `/login` 上报

5.9.4 接口说明

云工厂登录仅支持密码认证或 Identity U-Safe 认证。

5.9.5 请求示例

{
  "factoryId": 20,
  "stationId": "STATION-001"
}

5.9.6 返回参数

接口采用统一 JSON 响应格式，respData 包含以下字段：

字段	类型	说明
loginType	integer	登录方式：`1` 无密码；`2` 密码；`3` Identity U-Safe

5.9.7 返回示例

{
  "success": true,
  "respCode": "8000",
  "respMsg": "NoError",
  "respData": {
    "loginType": 2
  },
  "respTime": 1792108800
}

5.9.8 主要错误码

错误码	说明
8016	工站不存在
8036	云工厂 ID 错误

其他错误码见附录。

5.10 U-Safe 预登录

本接口用于执行 U-Safe 双向认证的第一步，获取服务端证书、挑战数据及签名。

5.10.1 请求 Method

GET

5.10.2 请求 URL

{BASE_URL}/api/iot-factory-edge-service/preLogin

5.10.3 请求参数

本接口为初始化接口，不要求提前获取工站会话令牌。该接口通过 Query 参数传递以下字段：

字段	类型	是否必填 / 条件	说明
usafeSN	string	是	Identity U-Safe 编号
nonce	string	是	客户端生成的随机挑战
type	integer	否	兼容参数，当前方法未使用其值
factoryId	integer（int64）	云模式按工厂传入	用于云模式下的工厂范围匹配

5.10.4 接口说明

适用范围：本接口用于 U-Safe 双向认证，不适用于直接密码登录。
签名处理：响应中的 sign 为服务端签名，不能直接作为客户端登录签名。客户端应验证服务端身份，并按照现有 U-Safe 认证协议对 challenge 签名，再调用 /login。

5.10.5 请求示例

GET {BASE_URL}/api/iot-factory-edge-service/preLogin?usafeSN=USAFE-001&nonce=%3C%E5%AE%A2%E6%88%B7%E7%AB%AF%E9%9A%8F%E6%9C%BA%E6%95%B0%3E&factoryId=20

5.10.6 返回参数

接口采用统一 JSON 响应格式，respData 包含以下字段：

字段	类型	说明
cert	string	服务端认证证书
challenge	string	服务端挑战数据，供客户端签名
sign	string	服务端签名，供客户端验证服务端身份

5.10.7 返回示例

{
  "success": true,
  "respCode": "8000",
  "respMsg": "NoError",
  "respData": {
    "cert": "<authentication certificate>",
    "challenge": "<server challenge>",
    "sign": "<server signature>"
  },
  "respTime": 1792108800
}

5.10.8 主要错误码

错误码	说明
8020	U-Safe 不存在
8031	U-Safe 不可用
8024 / 8026	认证或签名验证失败

其他错误码见附录。

5.11 工站登录

本接口用于完成工站身份认证并获取工站会话令牌。登录成功后，烧录客户端在后续需要工站会话的接口请求中，通过 x-snbps-session 请求头传递返回的 token。

5.11.1 请求 Method

POST

5.11.2 请求 URL

{BASE_URL}/api/iot-factory-edge-service/login

5.11.3 请求 Body

本接口为初始化接口，不要求提前获取工站会话令牌。该接口的 Body 包含以下参数：

字段	类型	是否必填 / 条件	说明
stationId	string	新登录流程必填	非空时执行工站认证；未提供时使用旧版 U-Safe 认证流程
factoryId	integer（int64）	云工厂必填	工厂 ID
password	string	loginType=2 时必填	使用现有 RSA 公钥加密后的密码，不能传入明文密码
usafeSN	string	loginType=3 或旧版流程	Identity U-Safe 编号，须与工站匹配
sign	string	U-Safe 认证时必填	客户端对 `/preLogin` 返回的挑战数据生成的签名
usafeCert	string	否	兼容字段，当前控制器分支未直接使用
clientPcMessage	string	否	客户端信息的 JSON 对象字符串

5.11.4 接口说明

登录方式：根据 /queryLoginType 返回的登录方式执行对应认证流程。
无密码登录： NO_PASSWORD（loginType=1）无需传入密码。
密码登录： PASSWORD（loginType=2）须传入 RSA 加密后的密码。
U-Safe 登录： IDENTITY_USAFE（loginType=3）须先调用 /preLogin，再使用客户端签名完成登录。
会话令牌：登录返回的 token 用于工站会话认证，不应与业务操作中的 uuid 或 traceId 混用。

5.11.5 请求示例

{
  "factoryId": 20,
  "stationId": "STATION-001",
  "password": "<RSA-encrypted password>",
  "clientPcMessage": "{\"hostname\":\"PS-01\"}"
}

5.11.6 返回参数

接口采用统一 JSON 响应格式，respData 包含以下字段：

字段	类型	说明
stationId	string	工站编码
token	string	工站会话令牌
factoryId	integer（int64）	工厂 ID
partnerCode	string	租户编码

5.11.7 返回示例

{
  "success": true,
  "respCode": "8000",
  "respMsg": "NoError",
  "respData": {
    "stationId": "STATION-001",
    "token": "<station session token>",
    "factoryId": 20,
    "partnerCode": "<tenant code>"
  },
  "respTime": 1792108800
}

5.11.8 主要错误码

错误码	说明
8012	工站重复登录
8014	密码错误
8016	工站不存在
8017	不支持的登录方式
8020 / 8021	U-Safe 不存在或不匹配
8036	云工厂 ID 错误

其他错误码见附录。

5.12 工站退出登录

本接口用于删除当前工站的会话缓存，完成工站退出登录。

5.12.1 请求 Method

POST

5.12.2 请求 URL

{BASE_URL}/api/iot-factory-edge-service/logout

5.12.3 请求头

参数	是否必填 / 条件	说明
x-snbps-session	有效退出登录时需要	工站会话令牌，使用 `/login` 接口返回的 `token`

5.12.4 请求参数

本接口无需提供请求参数。

5.12.5 接口说明

会话识别：需要提供有效的 x-snbps-session，才能识别并清理对应工站的会话。
校验规则：本接口未纳入 UkeyPermissionFilter 的强制校验路径，但不能因此省略有效退出登录所需的会话令牌。
退出结果：无法识别工站上下文时，不应认为已成功清理指定工站的会话。

5.12.6 请求示例

curl -X POST "$BASE_URL/api/iot-factory-edge-service/logout" \
  -H "x-snbps-session: $SESSION"

5.12.7 返回参数

接口采用统一 JSON 响应格式，respData 为 null。

5.12.8 返回示例

{
  "success": true,
  "respCode": "8000",
  "respMsg": "NoError",
  "respData": null,
  "respTime": 1792108800
}

5.13 按订单查询批次

本接口用于查询当前工厂下指定订单号对应的运行中批次。

5.13.1 请求 Method

GET

5.13.2 请求 URL

{BASE_URL}/api/iot-factory-edge-service/v1/queryBatchByOrderNumber

5.13.3 请求头

除公共请求头外，本接口还需提供以下请求头：

参数	是否必填	说明
x-snbps-session	是	工站会话令牌，使用 `/login` 接口返回的 `token`

5.13.4 请求参数

该接口通过 Query 参数传递以下字段：

字段	类型	是否必填	说明
orderNumber	string	是	工厂订单号，不能为空或仅包含空白字符

5.13.5 接口说明

查询范围：仅查询当前工厂下与指定订单号对应、状态为 RUNNING 的批次。
批次绑定：本接口仅执行查询，不会自动将查询到的批次绑定至当前工站。

5.13.6 请求示例

GET {BASE_URL}/api/iot-factory-edge-service/v1/queryBatchByOrderNumber?orderNumber=ORDER-001

5.13.7 返回参数

接口采用统一 JSON 响应格式，respData 为批次信息数组，未找到匹配批次时返回空数组 []。数组中的每个对象包含以下字段：

字段	类型	说明
batchId	integer（int64）	批次 ID
batchName	string	批次名称

5.13.8 返回示例

{
  "success": true,
  "respCode": "8000",
  "respMsg": "NoError",
  "respData": [
    {
      "batchId": 10,
      "batchName": "BATCH-001"
    }
  ],
  "respTime": 1792108800
}

5.13.9 主要错误码

错误码	说明
8039	订单号为空
8050	鉴权失败

其他错误码见附录。

5.14 分配工站批次

本接口用于将当前登录工站绑定至指定批次，并同步工站与批次的绑定信息。

5.14.1 请求 Method

POST

5.14.2 请求 URL

{BASE_URL}/api/iot-factory-edge-service/assignBatch

5.14.3 请求头

除公共请求头外，本接口还需提供以下请求头：

参数	是否必填	说明
x-snbps-session	是	工站会话令牌，使用 `/login` 接口返回的 `token`

5.14.4 请求 Body

该接口的 Body 包含以下参数：

字段	类型	是否必填	说明
batchId	integer（int64）	是	待绑定的批次 ID，必须属于当前工厂，且批次未过期、处于运行状态

5.14.5 接口说明

批次要求：只能绑定当前工厂下未过期且处于运行状态的批次。
绑定限制：已通过 Edge 管理端绑定、且不允许覆盖绑定关系的工站，不能通过本接口重新分配批次。
重复绑定：工站已绑定指定批次时，再次绑定相同批次将返回 8011。

5.14.6 请求示例

{
  "batchId": 10
}

5.14.7 返回参数

接口采用统一 JSON 响应格式，respData.batchInfo.batches 为批次详情数组，其结构与 /queryPPCBatchInfo 返回的批次详情相同。

5.14.8 返回示例

{
  "success": true,
  "respCode": "8000",
  "respMsg": "NoError",
  "respData": {
    "batchInfo": {
      "batches": [
        {
          "batchId": "10",
          "batchName": "BATCH-001",
          "programmingType": "SE",
          "bindType": 2
        }
      ]
    }
  },
  "respTime": 1792108800
}

5.14.9 主要错误码

错误码	说明
8009	批次已过期
8010	批次已关闭
8011	工站已绑定该批次
8013	数据解析失败
8016	工站不存在
8032	批次不存在
8035	与 Edge 管理端绑定关系冲突
8050	鉴权失败

其他错误码见附录。

5.15 查询工站批次信息

本接口用于查询工站关联的批次信息、烧录脚本及服务器压力信息。

5.15.1 请求 Method

GET

5.15.2 请求 URL

{BASE_URL}/api/iot-factory-edge-service/queryPPCBatchInfo

5.15.3 请求头

除公共请求头外，本接口还需提供以下请求头：

参数	是否必填	说明
x-snbps-session	是	工站会话令牌，使用 `/login` 接口返回的 `token`

5.15.4 请求参数

该接口通过 Query 参数传递以下字段：

字段	类型	是否必填	说明
usafeSN	string	否	兼容旧版 U-Safe 工站查询
batchId	integer（int64）	否	传入正数时查询指定的运行中批次；两个参数均未提供时，按当前会话工站查询

5.15.5 接口说明

查询与绑定：本接口仅查询批次信息，不会自动执行 /assignBatch 绑定操作。
烧录类型： programmingType 用于区分 MCU、SE、SE_MCU 等烧录类型，具体以实际批次值为准。
枚举使用：烧录类型应以 ProgrammingType 枚举及实际接口响应为准。旧版注释中的 MATTER、SE_MATTER 不能直接作为请求枚举值。

5.15.6 请求示例

GET {BASE_URL}/api/iot-factory-edge-service/queryPPCBatchInfo

5.15.7 返回参数

接口采用统一 JSON 响应格式，主要返回工站关联批次和服务器压力信息。

字段	类型	说明
usafeSN	string	U-Safe 编号
batchInfo.batches	array	工站关联的批次详情数组，无可用批次时可能返回空数组
serverLoadInfo.pressureLevel	integer	服务器压力等级
serverLoadInfo.pressurePercentage	number	服务器压力百分比

5.15.8 返回示例

{
  "success": true,
  "respCode": "8000",
  "respMsg": "NoError",
  "respData": {
    "batchInfo": {
      "batches": [
        {
          "batchId": "10",
          "batchName": "BATCH-001",
          "total": 100,
          "produced": 10,
          "toBeProduced": 90,
          "programmingType": "SE",
          "scriptName": "burn-1.0",
          "scriptMd5": "<md5>",
          "scriptUrl": "<script download URL>"
        }
      ]
    },
    "serverLoadInfo": {
      "pressureLevel": 1,
      "pressurePercentage": 10.0
    }
  },
  "respTime": 1792108800
}

5.15.9 批次详情字段说明

batchInfo.batches 数组中的每个对象包含批次、芯片、烧录脚本及生产进度等信息，具体字段如下：

字段	类型	说明
batchId	string	批次 ID
batchName	string	批次名称
chips	object[]	芯片信息数组，其中 `chipPart`、`chipVendor`、`objectid` 均为 string
env	string	环境信息
extData	string	扩展数据
mark	string	批次标记
notes	string	批次备注
orderNo	string	订单号
produced	integer	已生产数量
toBeProduced	integer	待生产数量
total	integer	批次总数量
productName	string	产品名称
version	string	产品版本
region	string	地区
secureDebugReopen	integer	安全调试开关
supportProtocols	string[]	支持的协议列表
scriptName	string	烧录脚本名称
scriptMd5	string	烧录脚本 MD5 校验摘要
scriptUrl	string	烧录脚本下载地址
vid	string	Matter VID
pid	string	Matter PID
bindType	integer	绑定方式：1 Edge 管理端绑定；2 客户端手动绑定
programmingType	string	烧录类型，如`MCU`、`SE`、`SE_MCU`，应根据实际响应值选择烧录流程

5.15.10 主要错误码

错误码	说明
8013	数据解析失败
8015	工站未绑定批次
8016	工站不存在
8050	鉴权失败

其他错误码见附录。

5.16 获取动态烧录数据

本接口用于为当前工站绑定的批次生成设备烧录数据，并建立本次烧录的生产记录。

5.16.1 请求 Method

GET

5.16.2 请求 URL

{BASE_URL}/api/iot-factory-edge-service/getProgrammingData

5.16.3 请求头

除公共请求头外，本接口还需提供以下请求头：

参数	是否必填	说明
x-snbps-session	是	工站会话令牌，使用 `/login` 接口返回的 token

5.16.4 请求参数

该接口通过 Query 参数传递以下字段：

字段	类型	是否必填 / 条件	说明
uuid	string	否	单次烧录跟踪 ID；未提供时由 `getProgrammingData` 生成，后续调用需保留并复用
ppcliVersion	string	否	客户端脚本版本
usafeSN	string	兼容旧流程	自 3.1.1 起不再作为新流程的主要参数；存在会话工站时优先使用工站信息
chipIndex	integer	否	自 3.1.1 起不再使用

5.16.5 接口说明

烧录跟踪：首次调用建议不传 uuid。获取返回的 uuid 后，应在后续 /uploadRequestData、/executeApdu 或烧录结果上报中复用。
SE 烧录： SE-only 场景下，即使返回的 bundles 为空数组，也会创建烧录记录。
文件下载：大文件的 downloadUrl 应以实际响应为准。
敏感材料：敏感生产材料不会通过 bundle 原文下发。

5.16.6 请求示例

GET {BASE_URL}/api/iot-factory-edge-service/getProgrammingData?ppcliVersion=1.0.0

5.16.7 返回参数

接口采用统一 JSON 响应格式，respData 为批次 Bundle 对象，包含以下字段：

字段	类型	说明
batchId	string	批次 ID
batchName	string	批次名称
uuid	string	本次烧录跟踪 ID
bundles	object[]	本次烧录的数据条目；SE-only 场景下可能返回空数组

5.16.8 返回示例

{
  "success": true,
  "respCode": "8000",
  "respMsg": "NoError",
  "respData": {
    "batchId": "10",
    "batchName": "BATCH-001",
    "uuid": "example-programming-trace",
    "bundles": []
  },
  "respTime": 1792108800
}

5.16.9 主要错误码

错误码	说明
8013	Bundle 数据解析失败
8030	无可用工站批次
8050	鉴权失败

其他错误码见附录。

5.17 获取批次元数据

本接口用于获取完整的批次元数据及固件等文件的下载地址，供客户端准备设备烧录。

5.17.1 请求 Method

GET

5.17.2 请求 URL

{BASE_URL}/api/iot-factory-edge-service/getMetadata

5.17.3 请求头

建议提供以下请求头，以便解析当前工站和工厂上下文：

参数	是否必填 / 条件	说明
x-snbps-session	建议提供	工站会话令牌，使用 `/login` 接口返回的 `token`

本接口未列入 UkeyPermissionFilter 的强制校验路径。

5.17.4 请求参数

该接口通过 Query 参数传递以下字段：

字段	类型	是否必填 / 条件	说明
uuid	string	否	单次烧录跟踪 ID；未提供时可由后续 `getProgrammingData` 生成，后续调用需保留
ppcliVersion	string	否	客户端脚本版本
usafeSN	string	兼容旧流程	自 3.1.1 起不再作为新流程的主要参数；存在会话工站时优先使用工站信息
chipIndex	integer	否	自 3.1.1 起不再使用

5.17.5 接口说明

元数据获取：返回完整的批次 Bundle，执行必要的元数据处理，并移除指定的密钥材料。
生产记录：本接口不会代替 /getProgrammingData 创建本次烧录记录，响应中的 uuid 不能作为新生产会话已创建的依据。
工站上下文：提供有效的 x-snbps-session 可用于解析当前工站信息。

5.17.6 请求示例

GET {BASE_URL}/api/iot-factory-edge-service/getMetadata?usafeSN=USAFE-001

5.17.7 返回参数

接口采用统一 JSON 响应格式，respData 为批次 Bundle 对象，包含以下字段：

字段	类型	说明
batchId	string	批次 ID
batchName	string	批次名称
uuid	string	响应中的烧录跟踪 ID，不代表已创建生产记录
bundles	object[]	完整批次数据条目

5.17.8 返回示例

{
  "success": true,
  "respCode": "8000",
  "respMsg": "NoError",
  "respData": {
    "batchId": "10",
    "batchName": "BATCH-001",
    "uuid": "example-programming-trace",
    "bundles": []
  },
  "respTime": 1792108800
}

上述示例中的空 bundles 仅用于展示响应结构，不代表所有批次均返回空数组。

5.17.9 主要错误码

错误码	说明
8013	数据解析失败
8030	无可用工站批次

其他错误码见附录。

5.18 获取完整烧录数据（兼容接口）

本接口为旧版完整 Bundle 获取接口，其服务方法已标记为 @Deprecated。新客户端建议使用 /getMetadata 和 /getProgrammingData。

5.18.1 请求 Method

GET

5.18.2 请求 URL

{BASE_URL}/api/iot-factory-edge-service/getPPData

5.18.3 请求头

除公共请求头外，本接口还需提供以下请求头：

参数	是否必填	说明
x-snbps-session	是	工站会话令牌，使用 `/login` 接口返回的 `token`

5.18.4 请求参数

该接口通过 Query 参数传递以下字段：

字段	类型	是否必填 / 条件	说明
uuid	string	否	单次烧录跟踪 ID；新流程中未提供时由 `getProgrammingData` 生成，后续调用需保留
ppcliVersion	string	否	客户端脚本版本
usafeSN	string	兼容旧流程	自 3.1.1 起不再作为新流程的主要参数；存在会话工站时优先使用工站信息
chipIndex	integer	否	自 3.1.1 起不再使用

5.18.5 接口说明

批次查询：当前接口根据 usafeSN 定位批次，生成新的 uuid，并返回处理后的完整烧录数据。
无可用批次：未找到可用批次时，可能返回 null。
兼容性：本接口用于兼容旧客户端，新客户端应使用 /getMetadata 和 /getProgrammingData。

5.18.6 请求示例

GET {BASE_URL}/api/iot-factory-edge-service/getPPData?usafeSN=USAFE-001

5.18.7 返回参数

接口采用统一 JSON 响应格式，respData 为批次 Bundle 对象，包含以下字段：

字段	类型	说明
batchId	string	批次 ID
batchName	string	批次名称
uuid	string	本次返回的烧录跟踪 ID
bundles	object[]	处理后的完整烧录数据条目

5.18.8 返回示例

{
  "success": true,
  "respCode": "8000",
  "respMsg": "NoError",
  "respData": {
    "batchId": "10",
    "batchName": "BATCH-001",
    "uuid": "example-programming-trace",
    "bundles": []
  },
  "respTime": 1792108800
}

示例中的空 bundles 仅用于说明响应结构，不能作为所有批次的实际返回内容。SE-only 场景下，getProgrammingData 可返回空 bundles。

5.18.9 Bundle 通用结构

bundles 数组中的每个 Bundle 对象包含以下字段：

字段	类型	说明
type	string	Bundle 类型
section	string	Bundle 所属 Section
ownerId	string	所属对象 ID
authToken	string	认证令牌
authCert	string	认证证书
authSign	string	认证签名
items	object[]	Bundle 数据条目列表

items 数组中的每个条目包含以下字段：

字段	类型	说明
itemId	string	条目 ID
key	string	条目标识
objectId	string	对象 ID
parentId	string	父对象 ID
fieldType	string	字段类型
attribute	JSON object	条目属性，具体结构由字段类型定义

不同批次的 Bundle 字段及内容可能不同。客户端应以服务端实际返回的数据结构和下载地址为准，不应将空 bundles 示例视为所有批次的实际数据。

5.18.10 主要错误码

错误码	说明
8050	鉴权失败

本接口的其他异常行为受旧版流程影响，具体错误码见附录。

5.19 提交中间烧录请求数据

本接口用于根据批次 Bundle 条目上报芯片执行结果，并由对应处理器生成下一阶段的烧录数据。

5.19.1 请求 Method

POST

5.19.2 请求 URL

{BASE_URL}/api/iot-factory-edge-service/uploadRequestData

5.19.3 请求头

除公共请求头外，本接口还需提供以下请求头：

参数	是否必填	说明
x-snbps-session	是	工站会话令牌，使用 `/login` 接口返回的 `token`

5.19.4 请求 Body

该接口的 Body 包含以下参数：

字段	类型	是否必填 / 条件	说明
batchId	string	是	当前工厂的批次 ID
uuid	string	业务上必填	本次 `/getProgrammingData` 返回的烧录跟踪 ID；IDRule 取号要求使用有效且稳定的 `traceId`
bundles	object[]	按需	上报的 Bundle 数据；为空时当前实现返回 `respData=null`
bundles[].type	string	按模板	Bundle 类型
bundles[].section	string	按模板	Bundle 所属 Section
bundles[].deviceId	string	IDRule 场景建议提供	稳定的设备标识；未提供时尝试从 `uuid` 对应记录中解析，首次取号后不得更换
bundles[].items	object[]	非空 Bundle 中必填	Bundle 条目列表，不允许空 `items` 或 `null` 条目
bundles[].items[].key	string	是	非空的条目标识
bundles[].items[].response	object[]	按条目协议	上一步执行结果列表，具体字段由 `fieldType` 及对应处理器协议定义

5.19.5 接口说明

接口用途：本接口用于提交中间烧录数据，不是最终烧录结果上报接口。
数据结构： items[].key 和 response 必须依据实际批次模板及处理器协议填写，不能直接使用示例中的占位符。
设备标识： IDRule 场景下，同一设备应复用稳定的设备标识。首次取号后，不得在后续烧录步骤中更换 deviceId。
空数据处理： bundles 为空时，当前实现返回 respData=null。

5.19.6 请求示例

{
  "batchId": "10",
  "uuid": "<uuid returned by getProgrammingData>",
  "bundles": [
    {
      "section": "<template section>",
      "deviceId": "DEVICE-001",
      "items": [
        {
          "key": "<template item key>",
          "response": [
            {
              "<protocol field>": "<actual execution result>"
            }
          ]
        }
      ]
    }
  ]
}

5.19.7 返回参数

接口采用统一 JSON 响应格式，respData 包含以下字段：

字段	类型	说明
batchId	string	批次 ID
batchName	string	批次名称
uuid	string	本次烧录跟踪 ID
bundles	object[]	对应处理器生成的下一阶段烧录数据条目

5.19.8 返回示例

{
  "success": true,
  "respCode": "8000",
  "respMsg": "NoError",
  "respData": {
    "batchId": "10",
    "batchName": "BATCH-001",
    "uuid": "example-programming-trace",
    "bundles": []
  },
  "respTime": 1792108800
}

5.19.9 主要错误码

错误码	说明
8002	请求参数无效
8003	数据处理失败
8032	批次不存在
8040–8046	证书或密钥协商相关错误
8065	IDRule 规则无效
8066	号段已耗尽
8067	状态冲突
8068	缺少稳定设备标识
8050	鉴权失败

其他错误码见附录。

5.20 上报烧录结果

本接口用于结束已有的设备烧录记录，并生成或更新设备档案，同时兼容旧版客户端。

5.20.1 请求 Method

POST

5.20.2 请求 URL

{BASE_URL}/api/iot-factory-edge-service/programmingResult

5.20.3 请求头

除公共请求头外，本接口还需提供以下请求头：

参数	是否必填	说明
x-snbps-session	是	工站会话令牌，使用 `/login` 接口返回的 `token`

5.20.4 请求 Body

该接口的 Body 包含以下参数：

字段	类型	是否必填 / 条件	说明
uuid	string	是（对接约定）	已有烧录记录的 traceId
batchId	integer（int64）	建议提供	烧录记录中没有批次信息时用于补充定位
result	boolean	建议明确提供	`true` 表示成功，`false` 或 `null` 按失败处理
failureReason	string	否	烧录失败原因
deviceProfile	object	否	CPS 实际烧录数据，字段参见生产数据上传接口中的 `deviceRecord`，包括 `deviceId`、`firmwareVersion`、`seid`、`cplc`、`matterData`、`factoryData` 和 `customData`
changeKeys	object	否	兼容字段，接受 `null`、空字符串或 JSON 对象，其他类型返回 `8002`；当前烧录结果处理流程未进一步使用该字段

5.20.5 接口说明

记录处理：当烧录记录不存在，或无法定位当前工厂批次时，当前方法会跳过设备建档并正常返回。
重复上报：相同状态重复上报，或烧录记录已处于成功状态时，不会重新处理。
结果确认：接口返回 respCode="8000" 不代表一定生成了新的设备档案，应通过设备查询接口确认。
自定义数据： customData 仅允许字符串类型的值，最多包含 50 项。
兼容性：新版统一生产数据上传流程可使用 /v1/deviceData/upload 完成烧录结果上报。

5.20.6 请求示例

{
  "uuid": "<current programming uuid>",
  "batchId": 10,
  "result": true,
  "deviceProfile": {
    "deviceId": "DEVICE-001",
    "firmwareVersion": "1.2.3",
    "customData": {
      "fixture": "A01"
    }
  }
}

5.20.7 返回参数

接口采用统一 JSON 响应格式，成功时 respData 为 null。

5.20.8 返回示例

{
  "success": true,
  "respCode": "8000",
  "respMsg": "NoError",
  "respData": null,
  "respTime": 1792108800
}

5.20.9 主要错误码

错误码	说明
8002	请求参数无效
8007	数据处理或存储错误
8037	设备档案生成失败
8050	鉴权失败

其他错误码见附录。

5.21 SE APDU 步进烧录

本接口用于执行 SE 设备的 APDU 步进烧录。客户端按照服务端返回的 APDU 指令列表执行操作，并提交执行结果，以获取下一阶段指令。当 nextStep 返回 EOF 时，表示烧录流程结束。

5.21.1 请求 Method

POST

5.21.2 请求 URL

{BASE_URL}/api/iot-factory-edge-service/executeApdu

5.21.3 请求头

除公共请求头外，本接口还需提供以下请求头：

参数	必填	说明
x-snbps-session	是	工站会话令牌，使用 `/login` 接口返回的 `token`

5.21.4 请求 Body

该接口的 Body 包含以下参数：

字段	类型	是否必填 / 条件	说明
batchId	string	是	当前工厂的 SE 配置批次 ID，不能省略并仅依赖工站绑定关系
cplc	string	SE 对接时提供	SE 设备的 CPLC 协议值，通常为 84 个字符，用于 SE 设备记录
seId	string	SE 对接时提供	SE 标识，字段名区分大小写，使用 `seId`
nfcUid	string	动力钥匙场景	设备物理编号的协议 Hex 值，兼容输入别名 `nfcId`；首步与续步必须保持一致
programmingTraceId	string	BOF 可省略，其他步骤必填	烧录跟踪 ID，兼容输入别名 `uuid`；`SE_MCU` 场景复用 Matter 会话的 `traceId`，响应仅返回 `programmingTraceId`
currentStep	string	是	首次调用使用 BOF；后续调用原样使用上次响应中的 `nextStep`，不得自行构造步骤游标
commandResults	object	续步必填	上一步 APDU 执行结果；BOF 不传，续步要求 `succeed=true` 且 `results` 与上次指令对应
commandResults.succeed	boolean	续步必填	上一步是否执行成功；`false` 将中止流程并返回 `8053`
commandResults.results	object[]	续步按上次响应提供	APDU 执行结果列表，每项包含 `index`（integer）及 `command`、`checker`、`result`（string）；`index` 应与上一步指令的字符串序号按数值对应

5.21.5 接口说明

首次调用：使用 currentStep="BOF" 开始烧录，并保存响应中的 programmingTraceId，用于后续步骤。
指令执行：客户端必须按照 commands 的顺序执行 APDU，并在续步请求中提交上一批指令的真实执行结果。
步骤控制：后续请求应原样使用上次返回的 nextStep，不得解析或修改服务端步骤游标。收到 EOF 后停止循环，不得再次提交 EOF。
会话恢复：返回 8054 表示当前会话无法继续，应从 BOF 重新开始，不得自动重放之前的 APDU 指令。
会话有效期：当前 SE 会话有效期以服务端配置常量为准。
动力钥匙：首步和续步中的 nfcUid（或 nfcId）必须保持一致，且不能将 seId 作为 NFC UID 使用。

5.21.6 请求示例

首次调用使用 BOF：

{
  "batchId": "10",
  "cplc": "<device CPLC>",
  "seId": "<device SEID>",
  "currentStep": "BOF"
}

5.21.7 返回参数

接口采用统一 JSON 响应格式，respData 包含以下字段：

字段类型说明 nextStep

字段	类型	说明
nextStep	string	服务端返回的下一步骤游标；EOF 表示流程结束
programmingTraceId	string	本次 SE 烧录跟踪 ID
commands	object[]	本步骤需要执行的 APDU 指令列表
commands[].index	string	APDU 指令序号
commands[].checker	string	APDU 响应校验器
commands[].command	string	需要执行的 APDU Hex 指令

5.21.8 返回示例

{
  "success": true,
  "respCode": "8000",
  "respMsg": "NoError",
  "respData": {
    "nextStep": "<server step cursor>",
    "programmingTraceId": "example-programming-trace",
    "commands": [
      {
        "index": "1",
        "checker": "<server-provided checker>",
        "command": "<server-provided APDU hex>"
      }
    ]
  },
  "respTime": 1792108800
}

5.21.9 APDU 续步请求示例

客户端完成上一批 APDU 指令后，使用服务端返回的 programmingTraceId 和 nextStep 提交执行结果。

{
  "batchId": "10",
  "programmingTraceId": "<programmingTraceId from previous response>",
  "currentStep": "<nextStep from previous response>",
  "cplc": "<same device CPLC>",
  "seId": "<same device SEID>",
  "commandResults": {
    "succeed": true,
    "results": [
      {
        "index": 1,
        "command": "<original command>",
        "checker": "<original checker>",
        "result": "<actual card response hex>"
      }
    ]
  }
}

动力钥匙场景下，首次请求和每次续步请求均需携带相同的 nfcUid（或输入别名 nfcId）。

原始生产密钥文件不应额外下载至客户端。相关生产材料由 Edge 准备，并通过当前步骤的 APDU 指令返回。

完整烧录成功并到达 EOF 后，沿用现有产量统计和设备档案处理流程。若卡端明确执行失败，不得将 commandResults.succeed 上报为 true。

5.21.10 动力钥匙设备绑定规则

设备标识：当前动力钥匙流程必须同时提供 nfcUid（兼容输入别名 nfcId）和 seId。
数据格式：两个标识均按设备协议传入偶数位十六进制字符串。当前分配入口要求字段非空、长度不超过 64 字符，并统一转换为大写。
别名使用：不得同时提交值不一致的 nfcUid 和 nfcId。首次调用及所有续步请求均应保持相同的 nfcUid 和设备身份。
材料绑定：生产材料按工厂、批次、NFC UID 和 SEID 的设备绑定关系保存。同一设备即使更换 traceId 或重新发送 BOF，也会优先复用已绑定的材料。
绑定冲突：当 NFC UID 或 SEID 已存在绑定记录，但另一设备标识不一致时，返回 8073。
材料耗尽：无可用生产材料时返回 8072。
历史数据：批次中存在尚未迁移的旧 Redis 或旧生产记录分配状态时，也可能返回 8073，不能通过重复发送 BOF 重新领取材料。

5.21.11 主要错误码

错误码	说明
8006	批次或烧录记录缺失
8047	SE 配置缺失
8048	数据解析失败
8049	CPLC 相关错误
8052	步骤执行结果不匹配
8053	上一步执行失败
8054	会话无法继续，需要重新开始
8055	APDU 处理失败
8056	配置解密失败
8070–8074	生产数据、材料分配或配置相关错误
8050	鉴权失败

其他错误码见附录。

5.22 获取烧录脚本地址

本接口用于获取指定批次对应的烧录脚本下载地址。

5.22.1 请求 Method

POST

5.22.2 请求 URL

{BASE_URL}/api/iot-factory-edge-service/getScriptFile

5.22.3 请求头

建议提供以下请求头，以便解析当前工站和工厂上下文：

参数	是否必填	说明
x-snbps-session	建议提供	工站会话令牌，使用 `/login` 接口返回的 `token`

本接口未列入 UkeyPermissionFilter 的强制校验路径。

5.22.4 请求 Body

该接口的 Body 包含以下参数：

字段	类型	是否必填 / 条件	说明
batchId	integer（int64）	按批次查询时必填	批次 ID
productId	integer（int64）	否	兼容产品维度查询参数
chipPart	string	按需	芯片型号
chipVendor	string	按需	芯片厂商

5.22.5 接口说明

下载地址：客户端应使用接口实际返回的 fileUrl 下载烧录脚本。
脚本校验：接口返回 HTTP 成功不代表客户端已完成本地脚本下载及校验。

5.22.6 请求示例

{
  "batchId": 10
}

5.22.7 返回参数

接口采用统一 JSON 响应格式，respData 包含以下字段：

字段	类型	说明
fileUrl	string	服务端返回的烧录脚本下载地址

5.22.8 返回示例

{
  "success": true,
  "respCode": "8000",
  "respMsg": "NoError",
  "respData": {
    "fileUrl": "<server-generated script download URL>"
  },
  "respTime": 1792108800
}

5.22.9 主要错误码

错误码	说明
8022	获取烧录脚本失败

其他错误码见附录。

5.23 下载文件

本接口用于根据本地文件记录 ID 下载文件。

5.23.1 请求 Method

GET

5.23.2 请求 URL

{BASE_URL}/api/iot-factory-edge-service/download

5.23.3 请求头

需要工厂上下文的调用应提供以下请求头：

参数	是否必填 / 条件	说明
x-snbps-session	需要工厂上下文时	有效的工站会话令牌，使用 `/login` 接口返回的 `token`

5.23.4 请求参数

该接口通过 Query 参数传递以下字段：

字段	类型	是否必填	说明
fileId	integer（int64）	是	本地文件记录 ID
fileName	string	否	客户端期望的下载文件名

5.23.5 接口说明

响应格式：下载成功时返回二进制文件流，并包含 Content-Disposition 等下载响应头，不使用统一的 ClientR JSON 响应结构。
下载地址：客户端可直接使用 /getScriptFile 或 /getMetadata 返回的完整下载 URL，避免手动拼接。
会话要求：需要工厂上下文时，应携带有效的 x-snbps-session。

5.23.6 请求示例

curl -L "$BASE_URL/api/iot-factory-edge-service/download?fileId=100&fileName=burn.zip" \
  -H "x-snbps-session: $SESSION" \
  -o burn.zip

5.23.7 返回参数

成功时返回文件二进制数据流，不返回 JSON 格式的 respData。

5.23.8 主要错误码

错误码	说明
8022	文件记录不存在
8023	文件下载失败

其他错误码见附录。

5.24 上传设备事件日志

本接口用于接收设备烧录过程中的事件日志，按照配置的优先级过滤后通过 MQTT 上报。发送失败时，保存相应的补偿记录。

5.24.1 请求 Method

POST

5.24.2 请求 URL

{BASE_URL}/api/iot-factory-edge-service/v1/eventLog/upload

5.24.3 请求头

除公共请求头外，本接口还需提供以下请求头：

参数	是否必填	说明
x-snbps-session	是	工站会话令牌，使用 `/login` 接口返回的 `token`

5.24.4 请求 Body

该接口的 Body 包含以下参数：

字段	类型	是否必填 / 条件	说明
programmingTraceId	string	是（非 null）	本次烧录跟踪 ID，兼容输入别名 `uuid`
events	object[]	是（非 null）	事件日志列表，空数组可能被直接忽略
events[].eventName	string	建议提供	事件名称
events[].timestamp	string	建议提供	客户端事件时间，格式沿用事件协议
events[].source	string	建议提供	事件来源
events[].priority	string	建议提供	事件优先级，使用 1–5 的数字字符串，数值越大优先级越高；空值或非法值会被过滤
events[].status	string	建议提供	事件状态：`success` 或 `failure`
events[].content	string	否	日志内容，当前实现超过 256 字符时会截断

5.24.5 接口说明

事件过滤：服务端根据配置的优先级阈值过滤事件。低于阈值或优先级无效的事件不会继续上报。
日志同步： HTTP 请求成功仅表示接口已接收并处理请求，不代表所有事件均已成功同步至云端。
失败补偿： MQTT 发送失败时，保存相应的补偿记录。

5.24.6 请求示例

{
  "programmingTraceId": "<current programming traceId>",
  "events": [
    {
      "eventName": "ProgrammingFinished",
      "timestamp": "2026-10-16T10:00:00+08:00",
      "source": "PS",
      "priority": "5",
      "status": "success",
      "content": "Burn completed"
    }
  ]
}

5.24.7 返回参数

接口采用统一 JSON 响应格式，成功时 respData 为 null。

5.24.8 返回示例

{
  "success": true,
  "respCode": "8000",
  "respMsg": "NoError",
  "respData": null,
  "respTime": 1792108800
}

5.24.9 主要错误码

错误码	说明
8050	鉴权失败

此外，请求参数绑定或校验失败也可能产生相应错误，其他错误码见附录。

5.25 生成 Matter Verifier

本接口用于调用 Matter SDK，生成 Matter 配对密码、Salt 和 Verifier。

5.25.1 请求 Method

POST

5.25.2 请求 URL

{BASE_URL}/api/iot-factory-edge-service/generateVerifier

5.25.3 请求头

当前 application.yml 未将本接口列入平台鉴权排除项。如果部署环境启用了平台鉴权，还需提供以下请求头：

参数	是否必填 / 条件	说明
x-snbps-auth-token	启用平台鉴权时	平台鉴权令牌，与工站会话令牌 `x-snbps-session` 不同

5.25.4 请求参数

本接口无需提供请求参数。

5.25.5 接口说明

生成参数：当前固定使用 saltLen=32 字节、iterations=1000，不支持通过请求 Body 覆盖。
运行依赖：服务端需要部署对应的原生 Matter SDK。
状态判断：外层 respCode 与 respData.status 含义不同。前者表示接口业务响应状态，后者为 Matter SDK 返回的状态码。
示例数据：返回示例中的数值仅用于说明字段类型。

5.25.6 请求示例

POST {BASE_URL}/api/iot-factory-edge-service/generateVerifier

5.25.7 返回参数

接口采用统一 JSON 响应格式，respData 包含以下字段：

字段	类型	说明
status	integer	Matter SDK 返回的状态码
passcode	integer	Matter 配对密码
salt	string	Base64 编码的 Salt
verifier	string	Base64 编码的 Verifier

5.25.8 返回示例

{
  "success": true,
  "respCode": "8000",
  "respMsg": "NoError",
  "respData": {
    "status": 0,
    "passcode": 20202021,
    "salt": "<Base64 salt>",
    "verifier": "<Base64 verifier>"
  },
  "respTime": 1792108800
}

5.26 生成 Matter 配网载荷

本接口用于根据指定的 Matter 参数调用 Matter SDK，生成二维码配网载荷和手工配网码。

5.26.1 请求 Method

POST

5.26.2 请求 URL

{BASE_URL}/api/iot-factory-edge-service/generateOnboardingData

5.26.3 请求头

当前 application.yml 未将本接口列入平台鉴权排除项。如果部署环境启用了平台鉴权，还需提供以下请求头：

参数	是否必填 / 条件	说明
x-snbps-auth-token	启用平台鉴权时	平台鉴权令牌，与工站会话令牌 `x-snbps-session` 不同

5.26.4 请求参数

本接口通过 Query 参数或表单参数传递以下字段，不使用 JSON 请求 Body。

字段	类型	是否必填	说明
vid	integer	是	Matter Vendor ID（VID），使用十进制整数，与 Matter 二维码找回接口使用的十六进制文本不同
pid	integer	是	Matter Product ID（PID），使用十进制整数
passcode	integer	是	Matter 配对密码
commissioningFlow	integer	是	Matter SDK 配网流程参数
discoveryMode	integer	是	Matter SDK 设备发现模式参数

5.26.5 接口说明

参数传递：虽然本接口使用 POST 方法，但五个参数均通过 @RequestParam 绑定，客户端应通过 URL Query 或表单参数传递，不应使用 JSON 请求 Body。
参数校验：各参数的有效取值范围由底层 Matter SDK 处理。
VID/PID 格式：本接口使用十进制整数，与 /v1/matter/onboarding-payloads/recover 接口使用的十六进制字符串不同。

5.26.6 请求示例

POST {BASE_URL}/api/iot-factory-edge-service/generateOnboardingData?vid=65522&pid=32769&passcode=20202021&commissioningFlow=0&discoveryMode=2

5.26.7 返回参数

接口采用统一 JSON 响应格式，respData 包含以下字段：

字段	类型	说明
status	integer	Matter SDK 返回的状态码
discriminator	integer	Matter 配网 `Discriminator`
qrcode	string	Matter 二维码配网载荷
manualcode	string	Matter 手工配网码，注意字段名为全小写的 `manualcode`

5.26.8 返回示例

{
  "success": true,
  "respCode": "8000",
  "respMsg": "NoError",
  "respData": {
    "status": 0,
    "discriminator": 3840,
    "qrcode": "<SDK-generated QR code payload>",
    "manualcode": "<SDK-generated manual pairing code>"
  },
  "respTime": 1792108800
}

5.27 生成 Matter Unique ID

本接口用于调用 Matter SDK 生成 Matter Unique ID。

5.27.1 请求 Method

POST

5.27.2 请求 URL

{BASE_URL}/api/iot-factory-edge-service/generateUniqueId

5.27.3 请求头

当前 application.yml 未将本接口列入平台鉴权排除项。如果部署环境启用了平台鉴权，还需提供以下请求头：

参数	是否必填 / 条件	说明
x-snbps-auth-token	启用平台鉴权时	平台鉴权令牌，与工站会话令牌 `x-snbps-session` 不同

5.27.4 请求参数

本接口无需提供请求参数或请求 Body。

5.27.5 接口说明

生成方式：由 Matter SDK 生成 Unique ID，无需客户端提供生成参数。
状态判断： Matter SDK 成功状态码通常为 0，外层接口业务成功码为 8000，两者含义不同。

5.27.6 请求示例

POST {BASE_URL}/api/iot-factory-edge-service/generateUniqueId

5.27.7 返回参数

接口采用统一 JSON 响应格式，respData 包含以下字段：

字段	类型	说明
status	integer	Matter SDK 返回的状态码
result	string	Base64 编码的 Unique ID

5.27.8 返回示例

{
  "success": true,
  "respCode": "8000",
  "respMsg": "NoError",
  "respData": {
    "status": 0,
    "result": "<Base64 uniqueId>"
  },
  "respTime": 1792108800
}

5.28 查询设备信息（旧接口，已废弃）

本接口用于兼容旧版客户端的设备信息查询。新客户端应使用 /v1/device/detail，或根据工站查询场景使用 /v1/device/information/query。

5.28.1 请求 Method

POST

5.28.2 请求 URL

{BASE_URL}/api/iot-factory-edge-service/queryDeviceData

5.28.3 请求头

建议提供以下请求头，以便解析当前工站和工厂上下文：

参数	是否必填 / 条件	说明
x-snbps-session	建议提供	工站会话令牌，使用 `/login` 接口返回的 `token`

本接口未列入 UkeyPermissionFilter 的强制校验路径。

5.28.4 请求 Body

该接口的 Body 包含以下参数：

字段	类型	是否必填 / 条件	说明
batchId	string	是	批次 ID
paramKey	string	是	用于定位参数所属的 Key
paramField	string	是	用于定位具体字段
paramValue	string	是	用于定位设备的字段值
queryKeys	string[]	是	支持的 key 请参考可查询键列表 (queryKeys V1)

5.28.5 接口说明

兼容性：本接口已在 v1.3 文档中声明废弃，仅保留用于兼容旧版客户端。
查询来源：当批次已删除、文件无法读取或本地设备档案未命中时，接口可能回源查询历史记录或云端数据。
查询参数： queryKeys 应遵循旧版 Bundle 查询协议，不能直接使用新版 QueryKeys V2 的字段定义。

5.28.6 请求示例

{
  "batchId": "10",
  "paramKey": "<legacy protocol key>",
  "paramField": "<legacy protocol field>",
  "paramValue": "<actual value>",
  "queryKeys": [
    "<legacy query key>"
  ]
}

5.28.7 返回参数

接口采用统一 JSON 响应格式，respData 包含以下字段：

字段	类型	说明
batchId	string	批次 ID
paramKey	string	查询使用的参数 Key
paramField	string	查询使用的字段
paramValue	string	查询使用的字段值
data	map<string,map<string,object>>	按旧版数据结构返回的设备信息

5.28.8 返回示例

{
  "success": true,
  "respCode": "8000",
  "respMsg": "NoError",
  "respData": {
    "batchId": "10",
    "paramKey": "<legacy protocol key>",
    "paramField": "<legacy protocol field>",
    "paramValue": "<actual value>",
    "data": {}
  },
  "respTime": 1792108800
}

5.28.9 主要错误码

错误码	说明
8006	批次不存在
8003	旧版设备信息查询处理失败

其他错误码见附录。

5.29 更新设备信息（旧接口，已废弃）

本接口用于兼容旧版设备数据模型的更新操作。新客户端应使用 /v1/updateDevicesProfile。

5.29.1 请求 Method

POST

5.29.2 请求 URL

{BASE_URL}/api/iot-factory-edge-service/updateDeviceInfo

5.29.3 请求头

建议提供以下请求头，以便解析当前工站和工厂上下文：

参数	是否必填 / 条件	说明
x-snbps-session	建议提供	工站会话令牌，使用 `/login` 接口返回的 `token`

本接口未列入 UkeyPermissionFilter 的强制校验路径。

5.29.4 请求 Body

该接口的 Body 包含以下参数：

字段	类型	是否必填 / 条件	说明
batchId	integer（int64）	是	批次 ID，注意与旧版查询接口使用的 string 类型不同
paramKey	string	是	用于定位参数所属的 Key
paramField	string	是	用于定位具体字段
paramValue	string	是	用于定位设备的字段值
data	map<string,map<string,string>>	是	需要更新的设备数据

5.29.5 接口说明

兼容性：本接口沿用旧版设备数据模型，新客户端应使用 /v1/updateDevicesProfile。
批次处理：当前服务在指定批次不存在时会直接返回，控制器仍可能返回请求中的 data。
更新确认：返回 respCode="8000" 及 data 回显，不代表数据一定已成功持久化。不能仅凭接口返回成功判断设备信息已更新。

5.29.6 请求示例

{
  "batchId": 10,
  "paramKey": "<legacy protocol key>",
  "paramField": "<legacy protocol field>",
  "paramValue": "<actual value>",
  "data": {}
}

5.29.7 返回参数

接口采用统一 JSON 响应格式，respData 为请求中的 data 对象，类型为 map<string, map<string, string>>。该字段仅回显请求数据，不代表重新查询得到的实际持久化结果。

5.29.8 返回示例

{
  "success": true,
  "respCode": "8000",
  "respMsg": "NoError",
  "respData": {},
  "respTime": 1792108800
}

6. 附录

6.1 附录一：可查询键列表 (queryKeys V2)

数据项	键
Matter 配网相关- PBKDF（密码派生）算法的迭代次数（1000 次）	matterData.iterations
Matter 配网相关-盐值长度（32 字节）	matterData.saltLength
Matter 配网相关-配网流程类型（0 表示标准流程）	matterData.commissioningFlows
设备可发现模式	matterData.discoverableMode
Matter 设备所属 VID	matterData.vid
Matter 设备所属 PID	matterData.pid
区分码	matterData.discriminator
Matter 配网参数-是否启用轮换设备 ID（true 表示启用）	matterData.enableRotatingDeviceId
Matter 手工配网码	matterData.manualCode
Matter 配网密码	matterData.passcode
Matter 配网参数二维码	matterData.qrcode
Matter 配网相关-用于密码派生算法的盐值	matterData.salt
Matter 设备标识-设备唯一标识符（Base64 编码）	matterData.uniqueid
Matter 配网参数-校验值	matterData.verifier
Matter 烧录设备流水号	matterData.serialNumber
Matter DAC 证书 MD5 值	matterData.dacCertMd5
Matter PAI 证书 MD5 值	matterData.paiCertMd5
Matter CD 文件名称	matterData.cdFileName
Matter CD 文件 MD5 值	matterData.cdFileMd5

工厂数据相关，参考 OBIS 产品界面配置	factoryData.vendorName
工厂数据相关，参考 OBIS 产品界面配置	factoryData.hardwareVersion
工厂数据相关，参考 OBIS 产品界面配置	factoryData.hardwareVersionString
工厂数据相关，参考 OBIS 产品界面配置	factoryData.partNumber
工厂数据相关，参考 OBIS 产品界面配置	factoryData.productUrl
工厂数据相关，参考 OBIS 产品界面配置	factoryData.productLabel
工厂数据相关，参考 OBIS 产品界面配置	factoryData.productName
工厂数据相关，参考 OBIS 产品界面配置	factoryData.startAddress

烧录状态	programmingData.programmingStatus
烧录日志	programmingData.programmingLog
烧录时间	programmingData.programmingTime

烧录设备芯片中的 mcuId	chipData.chipUid
芯片蓝牙 mac 地址	chipData.bleMac

固件名称 (返回固件列表)	firmwareData.fwName
固件 md5 (返回固件列表)	firmwareData.fwMd5

自定义字段	customData.自定义字段

6.1.1 补充查询键

提示

本接口的响应字段遵循 queryKeys V2 命名规则，Matter 数据使用 matterData.manualCode、matterData.qrcode 和 matterData.uniqueid，与“查询设备综合信息”接口中的 manualPairingCode、setupPayload 不同，请勿混用。

数据项	键	说明
SE 数据	seData	返回设备档案中完整的 SE 数据对象
整组查询	matterData / factoryData / programmingData / chipData / firmwareData / customData	不带点号的分组名用于查询该分组支持的字段，具体返回内容以当前接口实现为准

6.2 附录二：错误码列表

下表列出了接口使用的客户端业务错误码及对应说明。

不同接口仅涉及其中部分错误码，具体原因及处理方式见对应接口说明。
参数校验、平台鉴权及框架处理过程中产生的错误可能使用其他错误码，不限于本表。
SDK 内部的 status=0 与接口统一响应中的 respCode="8000" 含义不同，不应混用。

respCode	枚举名称	说明
8000	NO_ERROR	操作成功（NoError）
8001	REQUEST_FAILED	请求失败（RequestFailed）
8002	PARAM_ERROR	参数错误（ParamError）
8003	METHOD_ERROR	方法错误（MethodError）
8004	AUTH_ERROR	鉴权失败（AuthError）
8005	USAFE_TYPE_ERROR	U-safe 类型错误（USafeTypeError）
8006	DATA_NOT_FOUND	数据不存在（DataNotFound）
8007	DATA_ERROR	数据错误（DataError）
8008	NOT_ALLOWED	不允许执行该操作（NotAllowed）
8009	BATCH_EXPIRED_ERROR	批次已过期
8010	BATCH_STATUS_CLOSED	批次已关闭
8011	STATION_BATCH_HAS_BIND	该批次已绑定当前工站
8012	STATION_HAS_LOGIN	工站已登录（StationHasLogin）
8013	BATCH_BUNDLE_PARSE_ERROR	解析批次生成的 Bundle 文件失败
8014	STATION_PASSWORD_ERROR	工站密码错误（StationPasswordError）
8015	STATION_NOT_BIND_BATCH	工站未绑定任何批次
8016	STATION_NOT_EXIST	工站不存在
8017	UNKNOWN_LOGIN_TYPE	未知登录类型
8018	FACTORY_NOT_EXIST	工厂不存在
8019	FACTORY_STATUS_LOCKED	工厂已锁定
8020	USAFE_NOT_FOUNT	未找到 U-safe
8021	STATION_USAFE_NOT_MATCH	U-safe 与工站 ID 不匹配
8022	FETCH_BURN_SCRIPT_ERROR	获取烧录脚本失败
8023	DOWNLOAD_BURN_SCRIPT_ERROR	下载烧录脚本失败
8024	PRELOGIN_AUTH_ERROR	登录前鉴权失败
8025	HSM_CERT_SYNC_REQUIRED	未找到 HSM 认证证书。请在云端编辑工厂 HSM 信息，以触发证书同步
8026	SIGN_VERIFY_ERROR	签名验证失败
8027	BATCH_HAS_DONE	批次已完成
8028	BATCH_FILE_NOT_EXIST	操作失败，产品批次文件不存在
8029	BATCH_IMPORT_FAILED	导入批次失败
8030	PS_BURN_STATION_RECORDING_FINISHED	U-safe SN 已完成烧录，或未绑定任何批次
8031	USAFE_UNAVAILABLE	U-safe 不可用
8032	BATCH_NOT_FOUND	未找到批次
8033	BATCH_DOWNLOAD_STATUS_NOT_WAIT	批次下载状态不是等待中
8034	DEVICES_PROGRAMMER_DATA_UPLOAD_ERROR	上传设备烧录器数据失败
8035	STATION_HAS_EDGE_BIND	工站已绑定来自 Edge Service 的批次
8036	CLOUD_FACTORY_ID_ERROR	云端工厂 ID 错误
8037	DEVICE_PROFILE_GENERATE_ERROR	生成设备档案失败
8038	UNSUPPORTED_CERTIFICATE_FORMAT	不支持的证书格式
8039	ORDER_NUMBER_CANNOT_BE_EMPTY	订单号不能为空
8040	CERT_CHAIN_VERIFY_FAILED	Silicon Labs 证书链验证失败
8041	PUBKEY_SIGNATURE_VERIFY_FAILED	芯片临时公钥签名验证失败
8042	ECDH_KEY_AGREEMENT_FAILED	ECDH 密钥协商失败
8043	SESSION_KEY_NOT_FOUND	会话密钥不存在或已过期
8044	KEY_WRAP_FAILED	密钥封装失败
8045	DAC_PUBKEY_SIGNATURE_VERIFY_FAILED	DAC 公钥签名验证失败
8046	BUNDLE_PUBLIC_KEY_NOT_FOUND	未找到指定 keyCode 对应的 Bundle 公钥材料
8047	SE_PROFILE_NOT_FOUND	未找到批次对应的 SE Profile
8048	SE_PROFILE_PARSE_ERROR	解析 SE Profile 失败
8049	CPLC_INVALID	CPLC 无效，长度必须为 84
8050	PERMISSION_CHECK_DENY	授权验证失败，请重新获取验证权限
8051	SERVER_PERFORMANCE_LIMIT	已达到并发限制，请联系工厂管理员检查服务器
8052	APDU_SESSION_INVALID	executeApdu 会话无效，当前步骤的命令执行结果不符合预期
8053	APDU_STEP_FAILED	上一步 APDU 执行失败
8054	APDU_RESTART_REQUIRED	APDU 会话无效或已过期，请重新开始该设备的烧录流程
8055	APDU_PROCESS_FAILED	处理 APDU Profile 步骤失败
8056	SE_PROFILE_DECRYPT_ERROR	解密 SE Profile 失败
8057	TEST_FILE_PARAM_ERROR	测试文件上传参数无效
8058	TEST_FILE_MANIFEST_ERROR	测试文件清单无效
8059	TEST_FILE_STORAGE_ERROR	测试文件本地保存失败
8060	TEST_FILE_TASK_ERROR	保存测试文件上传任务失败
8061	TEST_FILE_UPLOAD_ERROR	上传测试文件至云端存储失败
8064	TEST_DATA_TASK_ERROR	保存测试数据上报任务失败
8065	ID_RULE_INVALID	ID Rule 描述信息无效
8066	ID_RULE_RANGE_EXHAUSTED	ID Rule 可分配范围已耗尽
8067	ID_RULE_CONFLICT	ID Rule 状态与批次描述信息冲突
8068	ID_RULE_DEVICE_KEY_REQUIRED	解析 ID Rule 时需要稳定的设备标识
8069	SCENARIO_TYPE_NOT_BE_NULL	scenarioType 不能为空
8070	DATA_INVALID	生产数据无效
8071	KEY_DECRYPT_FAILED	解密批次保护密钥失败
8072	DATA_EXHAUSTED	生产数据已耗尽
8073	ASSIGNMENT_CONFLICT	生产数据分配与批次或设备存在冲突
8074	PROFILE_INVALID	烧录要求配置 PERSONALIZE 操作及对应的 Applet 选择信息
8101	DEVICE_NOT_FOUND	未找到设备，请检查查询参数
8102	MULTI_DEVICES_FOUND	查询到多个设备，请增加筛选条件
8103	QUERY_CONDITION_REQUIRED	请在 deviceLocator 中至少指定一个有效查询条件

6.3 附录三：可更新键列表 (updateDevicesProfile)

更新设备档案信息接口支持的 key:

数据项	键	值说明
设备扩展字段	extend.扩展字段的 key	支持的扩展字段：vid, pid, chipId, qrcode, pairingCode
env	environment	test / prod
生产时间	manufactureTime	string 时间格式：2020-11-11T01:11:11+08:00
版本名	productVersion	string
批次名	productBatch	string
工厂名	factory	string
烧录站名	programmingStation	string
烧录状态	programmingStatus	Complete / Failed / Unreported
DAC 证书序列号	dacSerialNo	string
DAC 证书 commonName	dacCommonName	string
DAC 证书的 VID	dacVid	string
DAC 证书的 PID	dacPid	string
主体密钥标识	subjectKeyIdentifier	string
颁发机构密钥标识	authorityKeyIdentifier	string
DAC 生效日期	notBefore	string 时间格式：2020-11-11T01:11:11+08:00
DAC 失效日期	notAfter	string 时间格式：2020-11-11T01:11:11+08:00
配对码	pairingCode	string
二维码	qrcode	string
DAC 有效期的到期时间（日期，时间，时区）	expiryDate	string 时间格式：2020-11-11T01:11:11+08:00
DAC 剩余有效天数	leftDays	string
实际签发出的 DAC 证书	certificate	string
factoryData 中的字段	factoryData.key 名称	string 支持删除，可删除工厂数据中对应 key 的条目
脚本文件名称	programmingScript	string 支持删除，可删除对应名称的脚本文件；只能存在一个脚本文件，当上传一个新的脚本文件名称时，将会覆盖原有的脚本文件记录。
固件	firmwareData.固件名称	可更新对应名称固件的 startAddress；支持删除，可删除对应固件
otherFiles	otherFile.文件名称	可更新 otherFile 中对应文件名称的 key；支持删除，可删除对应名称的文件
attachmentFiles	attachment.文件名称	可更新 attachment 中对应文件名称的 key；支持删除，可删除对应名称的文件

6.4 附录四：可查询键列表 (queryKeys V1)

提示

如果某个数据项在产品中未配置，则接口返回该数据项的值为空。
键 fw1.fileName 中的数字 1 表示第一个固件。

数据项	键
CD 文件 MD5	cdFile.md5
CD 文件名	cdFile.fileName
Commissioning flow	matterCommissioningParameter.commissioningFlows
DAC MD5	dacTemplate.md5
Discovery mode	matterCommissioningParameter.discoverableMode
Discriminator	matterCommissioningParameter.discriminator
EnableRotatingDeviceId	matterCommissioningParameter.enableRotatingDeviceId
hardwareVersion	hardwareVersion
hardwareVersionString	hardwareVersionString
mcuId	mcuId
PAI MD5	paiCert.md5
partNumber	partNumber
PID	pid
productLabel	productLabel
productUrl	productUrl
salt	matterCommissioningParameter.salt
softwareVersion	softwareVersion
softwareVersionString	softwareVersionString
SPAKE2+Iterations	matterCommissioningParameter.iterations
UniqueID	matterCommissioningParameter.uniqueId
vendorName	vendorName
verifier	matterCommissioningParameter.verifier
VID	vid
二维码	matterCommissioningParameter.qrcode
固件文件名	fw1.fileName
设备烧录结果	programmingStatus
手工配网码	matterCommissioningParameter.manualCode
原始配网密码	matterCommissioningParameter.passcode

6.5 典型业务调用流程

本节介绍工站烧录、测试与组装场景下的典型接口调用顺序。具体请求参数、响应结构及处理规则见对应接口说明。

6.5.1 工站烧录

工站完成登录、批次查询及分配后，获取烧录数据，执行设备烧录并上报结果。典型调用流程如下：

queryLoginType
    ↓
preLogin（按需）
    ↓
login
    ↓
queryPPCBatchInfo / queryBatchByOrderNumber
    ↓
assignBatch（按需）
    ↓
getMetadata
    ↓
getProgrammingData
    ↓
uploadRequestData（按烧录条目要求）
    ↓
programmingResult / deviceData/upload

对于 SE 烧录，还需注意以下处理规则：

SE-only 场景：可在 BOF 阶段创建生产记录。
SE_MCU 混合烧录场景：应复用 MCU 或 Matter 烧录阶段的同一 traceId，再通过 executeApdu 执行 SE 烧录操作，直至 EOF。

6.5.2 测试与组装

测试和组装场景通过 /v1/deviceData/upload 上报生产数据。如需关联测试文件，应先上传文件，再提交对应的生产数据。典型调用流程如下：

login
    ↓
testFile/upload（按需）
    ↓
deviceData/upload

调用时需注意：

测试场景：首次上传且无附件时，可不提供 traceId，但必须提供 scenarioType。后续上传使用接口返回的 traceId。
文件关联：如需关联测试文件，先调用 /v1/testFile/upload 上传文件，再将返回的 traceId 用于 /v1/deviceData/upload。
组装场景：使用实际组装批次的 batchId，并通过 deviceRecord.testData.result 上报执行结果。

根据业务需要，扫码时可先调用 /v1/matter/onboarding-payloads/recover 恢复 Matter 配网数据；需要查询设备详细信息时，可调用 /v1/device/information/query。

1.修订记录
2. 概述
3. 公共请求头
- 3.1 接口调用约定与鉴权
- 3.2 统一响应与错误处理
4. 接口索引（29 项）
- 4.1 接口范围说明
5. 接口列表
6. 附录

1.修订记录​

2. 概述​

3. 公共请求头​

3.1 接口调用约定与鉴权​

3.1.1 服务地址与请求格式​

3.1.2 工站会话与接口校验​

3.1.3 平台鉴权与工厂上下文​

3.2 统一响应与错误处理​

3.2.1 响应示例​

3.2.2 错误处理​

3.2.3 特殊响应​

4. 接口索引（29 项）​

4.1 接口范围说明​

5. 接口列表​

5.1 查询设备详情​

5.1.1 请求 Method​

5.1.2 请求 URL​

5.1.3 请求 Body​

5.1.4 返回参数​

5.1.5 请求示例​

5.1.6 响应示例​

5.1.7 当前实现说明​

5.2 更新设备档案信息​

5.2.1 请求 Method​

5.2.2 请求 URL​

5.2.3 请求 Body​

5.2.4 返回参数​

5.2.5 请求示例​

5.2.6 响应示例​

5.2.7 操作规则与边界​

设备定位与更新范围​

字段取值规则​

字段更新与删除规则​

其他处理规则​

5.3 上传设备生产数据​

5.3.1 请求 Method​

5.3.2 请求 URL​

5.3.3 请求头​

5.3.4 请求 Body​

5.3.5 deviceRecord 参数说明​

5.3.6 场景处理规则​

参数长度与格式限制​

其他处理规则​

5.3.7 请求示例​

烧录场景​

测试场景​

组装场景​

5.3.8 文件与生产数据关联​

5.3.9 返回参数​

5.3.10 响应示例​

5.3.11 主要错误码​

5.3.12 HTTP 调用示例与续传​

续传规则与注意事项​

5.4 查询设备综合信息​

5.4.1 请求 Method​

5.4.2 请求 URL​

5.4.3 请求头​

5.4.4 请求 Body​

5.4.5 接口说明​

5.4.6 请求示例​

5.4.7 返回参数​

5.4.8 返回示例​

5.4.9 响应字段说明​

generalData：通用信息​

matterData：Matter 数据​

customData：自定义数据​

5.4.10 主要错误码​

5.5 找回 Matter 二维码​

5.5.1 请求 Method​

5.5.2 请求 URL​

5.5.3 请求头​

5.5.4 请求 Body​

5.5.5 接口说明​

5.5.6 请求示例​

5.5.7 返回参数​

5.5.8 返回示例​

5.5.9 主要错误码​

5.6 上传设备测试文件​

5.6.1 请求 Method​

5.6.2 请求 URL​

1.修订记录

2. 概述

3. 公共请求头

3.1 接口调用约定与鉴权

3.1.1 服务地址与请求格式

3.1.2 工站会话与接口校验

3.1.3 平台鉴权与工厂上下文

3.2 统一响应与错误处理

3.2.1 响应示例

3.2.2 错误处理

3.2.3 特殊响应

4. 接口索引（29 项）

4.1 接口范围说明

5. 接口列表

5.1 查询设备详情

5.1.1 请求 Method

5.1.2 请求 URL

5.1.3 请求 Body

5.1.4 返回参数

5.1.5 请求示例

5.1.6 响应示例

5.1.7 当前实现说明

5.2 更新设备档案信息

5.2.1 请求 Method

5.2.2 请求 URL

5.2.3 请求 Body

5.2.4 返回参数

5.2.5 请求示例

5.2.6 响应示例

5.2.7 操作规则与边界

设备定位与更新范围

字段取值规则

字段更新与删除规则

其他处理规则

5.3 上传设备生产数据

5.3.1 请求 Method

5.3.2 请求 URL

5.3.3 请求头

5.3.4 请求 Body

5.3.5 deviceRecord 参数说明

5.3.6 场景处理规则

参数长度与格式限制

其他处理规则

5.3.7 请求示例

烧录场景

测试场景

组装场景

5.3.8 文件与生产数据关联

5.3.9 返回参数

5.3.10 响应示例

5.3.11 主要错误码

5.3.12 HTTP 调用示例与续传

续传规则与注意事项

5.4 查询设备综合信息

5.4.1 请求 Method

5.4.2 请求 URL

5.4.3 请求头

5.4.4 请求 Body

5.4.5 接口说明

5.4.6 请求示例

5.4.7 返回参数

5.4.8 返回示例

5.4.9 响应字段说明

generalData：通用信息

matterData：Matter 数据

customData：自定义数据

5.4.10 主要错误码

5.5 找回 Matter 二维码

5.5.1 请求 Method

5.5.2 请求 URL

5.5.3 请求头

5.5.4 请求 Body

5.5.5 接口说明

5.5.6 请求示例

5.5.7 返回参数

5.5.8 返回示例

5.5.9 主要错误码

5.6 上传设备测试文件

5.6.1 请求 Method

5.6.2 请求 URL