Factory Edge Service API - v1.5

1. Revision Record

Version	Modified Date	Notes
v1.0	2025/03/26	Initial release
v1.1	2025/12/17	Added "Query Device Details" API, which can be used to retrieve programming status
v1.2	2025/12/22	Updated the required parameter validation and parameter descriptions of the "Query Device Details" API (Supports using the Matter QR code as a query condition to retrieve device information) Added API exception status code definitions Added an error code list
v1.3	2026/01/26	Deprecated "Query Device Data" and "Update Device Info" APIs Added "Update Devices Profile" API
v1.4	2026/09/10	Added the "Upload Device Production Data" API.
v1.5	2026/10/16	Updated the "Query Device Details", "Update Devices Profile", and "Upload Device Production Data" APIs. Added "Query Device Information", "Recover Matter QR Code", "Upload Device Test File", "Connection Heartbeat", "Query Login Options", "Query Programming Station Login Method", "U-Safe Pre-login", "Programming Station Login", "Programming Station Logout", "Query Batches by Order Number", "Assign Programming Station Batch", "Query Programming Station Batch Information", "Get Dynamic Programming Data", "Get Batch Metadata", "Get Full Programming Data" (compatibility API), "Submit Intermediate Programming Request Data", "Report Programming Result", "SE APDU Stepwise Programming", "Get Programming Script URL", "Download File", "Upload Device Event Logs", "Generate Matter Verifier", "Generate Matter Onboarding Payload", and "Generate Matter Unique ID" APIs. Added compatibility notes for the deprecated "Query Device Data" and "Update Device Info" APIs. vAdded common call conventions and error code descriptions.

2. Overview

Factory Edge Service API supports Programming Station login, production batch management, device programming, production data upload, device data queries, and device profile updates. These APIs use HTTP for data transmission, and all requests and responses are encoded in UTF-8.

This document describes the API conventions and common request headers, and provides request parameters, response parameters, and call examples for each API.

3. Common Request Headers

These APIs use the following keys (all lowercase):

Key	Mandatory	Description
content-type	Yes	Content type, unless otherwise specified, should always be application/json;charset=utf-8
x-snbps-factory-id	No	Factory ID
x-snbps-timestamp	No	Request time. For example, 2021-09-17T16:47:05.132+0800
x-snbps-lang	No	Language code, default is English: en-US, supports Simplified Chinese: zh-CN
x-snbps-request-id	No	Request traceID

3.1 API Call Conventions and Authentication

3.1.1 Service Address and Request Format

The service prefix is {BASE_URL}/api/iot-factory-edge-service. {BASE_URL} is the actual Edge address, including protocol, IP address or domain name, and port; it must not already include the service prefix. Paths below are relative to this prefix. JSON requests use UTF-8 encoding. Pass GET parameters in the URL query string; the client generates the boundary for multipart file uploads.

3.1.2 Programming Station Session and API Validation

After a Programming Station (PS) calls /login, retrieve the session token from respData.token and send it in the x-snbps-session header of subsequent requests. The station session token is distinct from a programming traceId or uuid. x-snbps-request-id is only for request tracing and cannot replace the business traceId.

The session lifetime is deployment-dependent and is refreshed when a protected API is called.

UkeyPermissionFilter enforces session validation for the following APIs:

/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

If validation data is missing or invalid, the service returns HTTP 200 with business code 8050.

3.1.3 Platform Authentication and Factory Context

Platform authentication is controlled separately by deployment configuration. In the current repository, application.yml does not exempt the following API paths from platform authentication:

• /v1/device/detail
• /v1/updateDevicesProfile
• /v1/deviceData/upload
• /executeApdu
• /v1/eventLog/upload
• /v1/queryBatchByOrderNumber
• The three /generate* API paths

When platform authentication is enabled in the target environment, these calls also require x-snbps-auth-token. Check the target environment's authentication configuration before integration testing; a valid station session token alone does not establish that all authentication requirements are met.

x-snbps-factory-id carries common factory information. The current factory context is primarily resolved from platform login information or a valid station session; this header alone cannot switch factories.

3.2 Unified Response and Error Handling

Factory Edge Service API generally uses a unified JSON response format, with the following fields:

Field	Type	Mandatory / condition	Description
success	boolean	Response	true indicates business success.
respCode	string	Response	8000 indicates success; see the appendix for other business error codes.
respMsg	string	Response	Status description, affected by the selected language.
respData	object / array / null	Response	Business data for the API; usually null when no data is returned or the business operation fails.
respTime	integer (int64)	Response	Unix timestamp in seconds, not a string.

3.2.1 Response Example

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

3.2.2 Error Handling

Business exceptions (ClientApiException) and expired station sessions are returned with HTTP 200. Callers must check success and respCode rather than relying on the HTTP status alone.

Parameter binding errors, Bean Validation failures, platform authentication failures, and gateway errors are not guaranteed to return HTTP 200. Handle the actual HTTP status and response content.

3.2.3 Special Responses

On success, /download returns a file stream directly rather than the unified JSON format.

4. API Index (29 APIs)

This section lists the current 29 Factory Edge Service APIs, including method, relative path, purpose, and caller identity requirements. See API Call Conventions and Authentication for authentication rules.

No.	Request Method	Relative Path	API Name	Caller Identity
5.1	POST	/v1/device/detail	Query Device Details	Platform authentication depends on deployment configuration.
5.2	POST	/v1/updateDevicesProfile	Update Devices Profile	Platform authentication depends on deployment configuration.
5.3	POST	/v1/deviceData/upload	Upload Device Production Data	Station session; see common conventions for platform authentication.
5.4	POST	/v1/device/information/query	Query Device Information	Station session; see common conventions for platform authentication.
5.5	POST	/v1/matter/onboarding-payloads/recover	Recover Matter QR Code	Station session; see common conventions for platform authentication.
5.6	POST	/v1/testFile/upload	Upload Device Test File	Station session; see common conventions for platform authentication.
5.7	GET	/heartBeat	Connection Heartbeat	Before login / initialization.
5.8	GET	/queryLoginOptions	Query Login Options	Before login / initialization.
5.9	POST	/queryLoginType	Query Programming Station Login Method	Before login / initialization.
5.10	GET	/preLogin	U-Safe Pre-login	Before login / initialization.
5.11	POST	/login	Programming Station Login	Before login / initialization.
5.12	POST	/logout	Programming Station Logout	Provide station context as required.
5.13	GET	/v1/queryBatchByOrderNumber	Query Batches by Order Number	Station session; see common conventions for platform authentication.
5.14	POST	/assignBatch	Assign Programming Station Batch	Station session; see common conventions for platform authentication.
5.15	GET	/queryPPCBatchInfo	Query Programming Station Batch Information	Station session; see common conventions for platform authentication.
5.16	GET	/getProgrammingData	Get Dynamic Programming Data	Station session; see common conventions for platform authentication.
5.17	GET	/getMetadata	Get Batch Metadata	Provide station context as required.
5.18	GET	/getPPData	Get Full Programming Data (Compatibility API)	Station session; see common conventions for platform authentication.
5.19	POST	/uploadRequestData	Submit Intermediate Programming Request Data	Station session; see common cdeploymentns for platform authentication.
5.20	POST	/programmingResult	Report Programming Result	Station session; see common conventions for platform authentication.
5.21	POST	/executeApdu	Execute SE APDU Stepwise Programming	Station session; see common conventions for platform authentication.
5.22	POST	/getScriptFile	Get Programming Script URL	Provide station context as required.
5.23	GET	/download	Download File	Provide station context as required.
5.24	POST	/v1/eventLog/upload	Upload Device Event Logs	Station session; see common conventions for platform authentication.
5.25	POST	/generateVerifier	Generate Matter Verifier	Platform authentication depends on deployment configuration.
5.26	POST	/generateOnboardingData	Generate Matter Onboarding Payload	Platform authentication depends on deployment configuration.
5.27	POST	/generateUniqueId	Generate Matter Unique ID	Platform authentication depends on deployment configuration.
5.28	POST	/queryDeviceData	Query Device Data (Deprecated)	Provide station context as required.
5.29	POST	/updateDeviceInfo	Update Device Info (Deprecated)	Provide station context as required.

4.1 API Scope

This index covers the 29 external routes currently registered by ProgrammingStationController and ExternalSystemController. It excludes administration controllers, the debugging TestController, and the entirely commented-out UsbKeyController.

/v1/testData/upload remains in some filter or authentication exclusion configurations, but no current controller registers it. Upload device production data through /v1/deviceData/upload.

5. API List

5.1 Query Device Details

Query device profiles using locator and filter conditions combined with AND logic, and return the groups or fields specified by queryKeys. If no local record matches, query historical data and then cloud data. If multiple results refer to different products or deviceId values, return error code 8102. If multiple records belong to the same product and device, return the most recent by production time.

5.1.1 Request Method

POST

5.1.2 Request URL

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

5.1.3 Request Body

The request body contains the following parameters:

tip

At least one non-empty value is required among chipUid, bleMac, serialNumber, matterQrcode, and matterManualCode in deviceLocator. Other parameters are auxiliary query conditions. All conditions are combined using AND logic. Provide sufficiently precise parameters to identify the target device. queryKeys only selects returned data groups or fields; it does not participate in device matching.

Name	Type	Mandatory	Description
deviceLocator	object	Yes	Used to retrieve basic device information. When deviceLocator is selected as a query condition, at least one of the following parameters must be provided: chipUid, bleMac, serialNumber, matterQrcode, or matterManualCode
├──chipUid	string	No	mcuId in the programmed device chip
├──bleMac	string	No	Bluetooth MAC address of the chip
├──serialNumber	string	No	Device serial number assigned during programming
├──matterQrcode	string	No	Matter commissioning QR code
├──matterManualCode	string	No	Matter manual commissioning code
filters	object	No	Auxiliary filter conditions used to improve device identification accuracy
├──productionTimeStart	string	No	Device programming production start time. Date format: 2025-12-16T12:02:58+08:00
├──productionTimeEnd	string	No	Device programming production completion time. Date format: 2025-12-17T12:02:58+08:00
├──batchId	string	No	Production batch number
matter	object	No	Matter-related device parameters. Providing this parameter helps improve query accuracy
├──pid	string	No	Matter PID. Including this parameter helps improve device query accuracy
├──vid	string	No	Matter VID. Including this parameter helps improve device query accuracy
customParams	object	No	Custom filter parameters. For details, refer to the description of customParams parameter.
queryKeys	string[]	Recommended	Pass a string array naming groups (such as matterData) or fields (such as chipData.chipUid). If a local device profile matches but queryKeys is omitted or empty, the API returns an empty object {} rather than all fields by default. See the queryKeys V2 list for supported keys.

Description of customParams Parameter

This API accepts custom query conditions in customParams for more flexible filtering. To query fields uploaded for a business use case, add the field names and expected values to this object as key-value pairs.

Parameter structure

• Type: JSON object (key-value collection).
• Key: The extension field name to match (for example, "customData").
• Value: The expected value for this field (for example, "customDataValue").

Example

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

This example indicates querying device records where the reported data customData1 equals "customDataValue1" and customData2 equals "customDataValue2".

Name	Type	Mandatory	Description
key	string	Yes	Used to query the basic key values in the device profile information. The available keys are either system-generated or a set of custom keys uploaded during the programming process
value	string	Yes	Each key corresponds to the value of the query parameter

5.1.4 Response Parameters

tip

The following table shows the data returned when querying all queryKeys. In practice, querying only the required keys can help improve API performance.

Name	Type	Description
respCode	string	8000 indicates success; any other value indicates an error. Detailed error information can be found in respMsg
respMsg	string	Response messages, such as NoError or DataNotFound
respData	object	Query result data
├──matterData	object	Matter data related
├──iterations	string	Iteration count
├──commissioningFlows	string	Commissioning flow
├──discoverableMode	string	Device discoverable mode
├──vid	string	Vendor ID
├──pid	string	Product ID
├──discriminator	string	Discriminator
├──enableRotatingDeviceId	string	Enable rotating device identifier
├──manualCode	string	Manual pairing code
├──passcode	string	Pairing code
├──qrcode	string	Matter commissioning QR code
├──salt	string	Salt
├──saltLength	string	Salt length
├──uniqueid	string	Unique device identifier
├──verifier	string	Password verifier
├──serialNumber	string	Matter device programming serial number
├──dacCertMd5	string	DAC certificate MD5
├──cdFileMd5	string	CD file MD5
├──cdFileName	string	CD file name
├──paiCertMd5	string	PAI certificate MD5
├──factoryData	object	Factory data configuration related
├──vendorName	string	Vendor name
├──hardwareVersion	string	Hardware version
├──hardwareVersionString	string	Hardware version string
├──partNumber	string	Part number
├──productUrl	string	Product URL
├──productLabel	string	Product label
├──productName	string	Product name
├──startAddress	string	Start address
├──programmingData	object	Device programming results related
├──programmingStatus	string	Device programming status Success: success Failure: failure Pending: pending
├──programmingLog	string	Programming log
├──programmingTime	string	Programming time
├──chipData	object	Chip data related
├──chipUid	string	mucId in the programmed device chip
├──bleMac	string	Bluetooth MAC address of the chip
├──firmwareData	object[]	Firmware related
├──fwName	string	Firmware name
├──fwMd5	string	Firmware MD5
├──customData	object	Custom data reported by the customer during production

5.1.5 Request Example

{
  "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 Response Example

Note: This response example shows all result data. In practice, use queryKeys to retrieve only the required data.

{
  "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 Current Implementation Notes

• Supported data groups: matterData、factoryData、programmingData、chipData、firmwareData、customData、seData。
• Field return rules: seData can be returned only as a whole group; specifying seData.xxx does not filter its subfields. Unknown groups in queryKeys add no data. If a requested field is empty or has not been stored, its value may be empty.
• Programming data: programmingData.programmingStatus supports success, failure, and pending. The current local data construction logic does not populate programmingLog with actual log content; do not rely on it for programming logs.
• Authentication: UkeyPermissionFilter does not enforce station session validation for this API. See API Call Conventions and Authentication for platform authentication requirements.

5.2 Update Devices Profile

After a factory modifies device programming data, it can use this API to synchronize the updates to OBIS for centralized management.

5.2.1 Request Method

POST

5.2.2 Request URL

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

5.2.3 Request Body

The request body contains the following parameters:

Name	Type	Mandatory	Description
deviceLocator	object	Yes	Used to retrieve basic device information. When deviceLocator is selected as a query condition, at least one of the following parameters must be provided: chipUid, bleMac, serialNumber, matterQrcode, or matterManualCode
├──chipUid	string	No	mcuId in the programmed device chip
├──bleMac	string	No	Bluetooth MAC address of the chip
├──serialNumber	string	No	Device serial number assigned during programming
├──matterQrcode	string	No	Matter commissioning QR code
├──matterManualCode	string	No	Matter manual commissioning code
filters	object	No	Auxiliary filter conditions used to improve device identification accuracy
├──productionTimeStart	string	No	Device programming production start time. Date format: 2025-12-16T12:02:58+08:00
├──productionTimeEnd	string	No	Device programming production completion time. Date format: 2025-12-17T12:02:58+08:00
├──batchId	string	No	Production batch number
matter	object	No	Matter-related device parameters. Providing this parameter helps improve query accuracy
├──pid	string	No	Matter PID. Including this parameter helps improve device query accuracy
├──vid	string	No	Matter VID. Including this parameter helps improve device query accuracy
customParams	object	No	Custom filter parameters. For details, refer to the description of customParams parameter.
updateParams	object[]	No	Pass updates as an array. Each item contains type, key, and value, all strings. An empty array does not update fields. See the updateParams description for supported keys and operations.

Description of updateParams Parameter

This API accepts system-supported keys in updateParams to modify specified fields in a device record. Provide the field name, target value, and operation type (type) together as an array.

Parameter structure

• Type: JSON array.
• When type is add, a new field record corresponding to the key will be created; if the key already exists, its field value will be updated.
• Some device data supports deletion. When type is delete, the field record corresponding to the key will be deleted.
• For details about the keys supported by this parameter, refer to the updatable keys list (updateDevicesProfile).

Example

[
    {
        "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"
    }
]

The above example indicates:

1. Add the qrcode field and set its value to MT:XXX-S0XXXX; if the field already exists in the device, the existing value will be overwritten.
2. Delete the productURL field from factoryData of the device.
3. Add the qqbb field to factoryData of the corresponding device and set its value to abcd.
4. Add the firmware bootloader-xxx-1.1.s37 to the firmware list of the device and set its startAddress to 00000001. If a firmware with the same name already exists in the device, update its start address to this value.

5.2.4 Response Parameters

Name	Type	Description
respCode	string	8000 indicates success; any other value indicates an error. Detailed error information can be found in respMsg
success	bool	True indicates success
respMsg	string	Response messages, such as NoError or DataNotFound

5.2.5 Request Example

{
  "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 Response Example

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

5.2.7 Operation Rules and Limits

The following requirements apply to fields in updateParams:

Field	Type	Mandatory / condition	Description
updateParams[].type	string	By operation	add creates or overwrites; delete applies only to collection fields that support deletion.
updateParams[].key	string	Yes	A system key or collection prefix listed in Appendix 3.
updateParams[].value	string	For add	Only strings are accepted. Date and integer text must meet the target field format requirements.

Device Location and Update Scope

The device location rules for deviceLocator, filters, matter, and customParams are the same as for Query Device Details. Updates affect local device profiles only; they do not query historical or cloud data.

Field Value Rules

• The environment value supports only test and prod.
• programmingStatus supports Complete, Failed, and Unreported. Other values are currently treated as incomplete.

Field Update and Deletion Rules

• Deletable fields: factoryData.*, firmwareData.*, otherFile.*, attachment.*, and programmingScript.
• Fields that cannot be deleted: scalar keys and extend.* are currently assigned directly from value; delete is not supported.
• Unknown fields: unknown keys are currently skipped and do not necessarily produce a parameter error.

Other Processing Rules

• If updateParams is an empty array, no fields are updated, but the service still attempts to read the target device profile and metadata.
• After an update, the record is marked as awaiting synchronization. Receiving the HTTP response does not mean cloud synchronization is complete.

5.3 Upload Device Production Data

Factories can use this API to upload programming, test, and assembly data generated during device production and maintain the corresponding production record by traceId. At the end of programming, the API reuses the programmingResult processing logic. Test and assembly data are synchronized by a subsequent asynchronous flow.

5.3.1 Request Method

POST

5.3.2 Request URL

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

5.3.3 Request Body

The Content-Type for this API is application/json. In addition to the common request headers, provide the following header:

Field	Mandatory	Description
x-snbps-session	Yes	Station session token returned by /login.

5.3.4 Request Body

The request body contains the following parameters:

Name	Type	Mandatory / condition	Description
traceId	string	By scenario	Production record trace ID; uuid is an accepted alias. In the programming scenario, use the uuid returned by /getProgrammingData. If omitted, a new record may be created. A supplied value must refer to an existing production record or file task; otherwise the API returns 8006.
scenarioType	string	Required for test or custom scenarios	Production scenario name, for example RF-Test. The assembly batch uses assembly, and an existing programming session uses programming. Other scenarios return 8069 if this field is absent.
deviceId	string	Required for test or assembly integration	Device MCU ID. If omitted, deviceRecord.deviceId is used.
batchId	string	Required for assembly integration	Production batch ID. Only a numeric string is treated as an ID. Assembly is identified by batch type, not by scenarioType=assembly alone.
deviceProfileId	string	No	Existing device profile ID; it must correspond to deviceId. If omitted, the service matches an existing profile by device ID.
stationId	string	No	Programming Station code. If omitted, the station in the current session is used. It need not be numeric.
factoryId	string	No	Factory ID. For new records, only a numeric string takes effect; otherwise the factory from the current session is used.
deviceSn	string	No	Device serial number.
result	boolean	Recommended for programming	Programming result: true for success, false for failure. If omitted at the end of programming, it is treated as failure.
failureReason	string	No	Failure reason, stored in the production record.
timestamp	string	No	This API does not use this field to set the production record time; the server generates the creation time.
status	string	No	Custom status. Programming and assembly may generate and overwrite it from the system result; other nonempty values are stored in customStatus.
deviceRecord	object	Per scenario integration contract	Device production data; deviceProfile is an accepted alias. See deviceRecord parameters for its fields.

5.3.5 deviceRecord Parameters

deviceRecord contains data produced by the device at the current production stage.

Name	Type	Required / Condition	Description
deviceId	string	Conditionally required	Device MCU ID; used when top-level deviceId in the request body is empty.
firmwareVersion	string	As needed for programming	Firmware version
seid	string	As needed for SE programming	SEID; use lowercase for the field name.
cplc	string	As needed for SE programming	CPLC data
matterData	map	As needed for Matter programming	Matter data actually programmed.
factoryData	map	No	Factory Data actually programmed. Field names must be nonempty and values must be strings.
customData	map	No	Custom data, up to 50 fields. Field names must be nonempty and no longer than 64 characters, and values must be strings; otherwise 8002 is returned. This upload replaces all existing customData.
testData	map	Required for test / assembly integration	Test data; also accepts the legacy field name diagnosticData. Values may be text or lists of file references. Fields with the same name are appended when both values are lists; otherwise the new value overwrites the old one.

5.3.6 Scenario Handling Rules

Parameter requirements and handling rules for different production scenarios are as follows:

Scenario	traceId and Batch	Data and Status
Programming	Use the existing programming session traceId, usually from /getProgrammingData.	Provide deviceRecord based on the actual programmed content and explicitly pass result. At completion, the API reuses /programmingResult handling. Merely setting scenarioType=programming does not create a complete programming flow.
Test / Custom	The first upload may omit traceId; later uploads use the traceId returned in the response. scenarioType is required.	Provide deviceId and deviceRecord.testData as specified by the integration contract. If a matching device profile exists, it is associated; otherwise only a production record may be created and deviceProfileId is null.
Assembly	batchId identifies the assembly batch. traceId may come from /getProgrammingData or a file task; a new record can also be created if the first upload omits it.	Provide deviceId and deviceRecord.testData. The scenario is fixed to assembly. testData.result affects result status and output counts. The current implementation deduplicates successful assembly records for the same device in the same batch.

Parameter Length and Format Limits

Database field length limits are as follows:

Field	Maximum Length
traceId	64 characters
deviceId	128 characters
deviceSn	64 characters
failureReason	1024 characters
status / scenarioType	64 characters

These length limits do not mean that the API automatically validates every request field. ID values must fall within the Java Long range. Overlong fields, invalid number formats, or violations of database constraints may cause data persistence to fail. Numeric strings must also satisfy the applicable length and value limits.

Other Handling Rules

• Programming data: The integration contract requires at least one of deviceRecord.firmwareVersion, deviceRecord.seid, deviceRecord.cplc, or deviceRecord.matterData, but the current API does not enforce this requirement.
• Test and assembly data: Upload test data in deviceRecord.testData. A top-level customData field in the request body is not recognized as deviceRecord.customData.

5.3.7 Request Example

Programming Scenario

Use the uuid returned by /getProgrammingData as traceId, and submit the programming result and device data.

{
  "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"
    }
  }
}

Test Scenario

The first test report may omit traceId. Specify the test scenario through scenarioType and submit the test data in testData.

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

Assembly Scenario

Use batchId to specify the assembly batch. The first report may omit traceId.

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

5.3.8 Associate Files with Production

To associate a test file, first upload it with POST /v1/testFile/upload and save the returned traceId. Then call this API with the same traceId and reference the file through fileName in testData.

If an existing production record has a traceId, you may pass it when uploading the file. fileTraceId is an internal association field and need not be added to the top level of this API request.

Request example:

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

5.3.9 Response Parameters

This API uses the standard JSON response format. See "Standard Response and Error Handling" for common response fields. respData contains the following fields:

Field	Type	Description
traceId	string	Trace ID ultimately used by the server. Pass it unchanged on subsequent uploads.
deviceProfileId	integer (int64) / null	Associated device profile ID; null if none is associated.
programmingRecordId	integer (int64)	Device production record ID

5.3.10 Response Example

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

5.3.11 Main Error Codes

Error Code	Description
8002	Custom field does not meet requirements.
8006	traceId is not associated with an existing production record or file task.
8007	Data persistence failed.
8032	Batch does not exist.
8037	Device profile creation failed.
8050	Programming Station session expired.
8069	scenarioType is missing for a test or custom scenario.

5.3.12 HTTP Call Example and Subsequent Uploads

The following curl example uploads test data for the first time. BASE_URL contains only the scheme, host, and port, for example http://edge-host:8005. SESSION is the session token returned by /login for the Programming Station. If platform authentication is enabled in the target environment, also supply the x-snbps-auth-token header.

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"}
    }
  }' 

Subsequent Upload Rules and Notes

• Trace ID: After the first successful upload, save respData.traceId from the response. Pass that value at the top level of subsequent uploads to the same production record, and continue to supply scenarioType. Independent tests must not reuse an existing traceId.
• Identifiers: x-snbps-request-id is only for request tracing and cannot replace the business traceId. Passing a traceId that does not exist and is not associated with a file task returns 8006.
• Test data: Under the same traceId, list fields with the same name in testData are appended. Repeated requests may create duplicate attachment references.
• Custom data: Each upload replaces all existing customData. On a subsequent upload, include every custom field you need to retain.
• Repeated requests: After a network timeout, do not assume that the previous request did not run or that repeated uploads are fully idempotent.

5.4 Query Device Information

This API queries general information, Matter data, and specified custom data in the local device profile. Unlike /v1/device/detail, it cannot select returned fields through queryKeys.

5.4.1 Request Method

POST

5.4.2 Request URL

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

5.4.3 Request Headers

In addition to the common request headers, this API requires the following header:

Field	Required	Description
x-snbps-session	Yes	Programming Station session token returned by /login.

5.4.4 Request Body

The request body contains the following parameters. Supply at least one nonempty device identifier.

Field	Type	Required / Condition	Description
deviceId	string	At least one required	Exact match against deviceId in the device profile; maximum 128 characters.
chipId	string	At least one required	Exact match against chipUid in the device profile; maximum 128 characters.
uniqueId	string	At least one required	Match uniqueId, uniqueid, or the corresponding snake_case fields in Matter data; maximum 128 characters.

5.4.5 Notes

• Query conditions: Multiple nonempty device identifiers are combined with AND; all conditions must match.
• Query scope: Only local device profiles are queried, not the historical database or cloud. If no record matches, the API returns 8101.
• Query result: If multiple records match, the first result is returned. This does not guarantee identifier uniqueness or that the returned device was programmed successfully.
• Programming status: provisionStatus currently always returns Success and cannot, by itself, establish the device's actual programming status.

5.4.6 Request Example

{
  "deviceId": "DEVICE-001"
}

5.4.7 Response Parameters

This API uses the standard JSON response format. respData contains the following data objects:

Field	Type	Description
generalData	object	Device identity, programming information, and product version information.
matterData	object / null	Matter certificate and commissioning data; may be null for non-Matter devices.
customData	object	Device serial number, business identifier, MAC address, and test and calibration data.

Fields without recorded values may be empty.

5.4.8 Response Example

{
  "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 Response Field Descriptions

generalData: General information

tip

sourceProgramingBatchId is the actual response field name; retain the original "Programing" spelling.

Field	Type	Description
deviceId	string	Device ID
provisionStatus	string	Programming status; currently always returns Success.
provisionTime	string	Programming time in UTC ISO 8601 format.
sourceProgramingBatchId	string	Source programming batch ID
provisionFactoryId	string	Programming factory ID
provisionStationId	string	Programming Station ID; corresponds to the station primary key in the device profile.
productId	string	Product ID
productName	string	Product name
productVersionId	string	Product version ID
productVersionName	string	Product version name

matterData: Matter data

Field	Type	Description
dacCert	string	DAC certificate in its stored Base64 DER or PEM format.
paiCert	string	PAI certificate in its stored Base64 DER or PEM format.
certDeclaration	string	Certification Declaration (CD), Base64 encoded.
discriminator	integer	Matter Discriminator as a decimal number.
spake2pIterationCount	integer	SPAKE2+ iteration count.
passcode	string	Matter commissioning passcode.
manualPairingCode	string	Matter manual pairing code.
setupPayload	string	Matter commissioning payload.
spake2pVerifier	string	SPAKE2+ verifier; retain the stored value.
spake2pSalt	string	SPAKE2+ salt; retain the stored value.

customData: Custom data

tip

Before returning factoryTestData and calibrationParams, the API recursively removes defined credential fields and does not return the device private key.

Field	Type	Description
serialNumber	string	Device serial number
customId	string	Business identifier
macAddress	string	MAC address
factoryTestData	JSON	Factory test data
calibrationParams	JSON	Device calibration parameters

5.4.10 Main Error Codes

Error Code	Description
8002	All query parameters are empty.
8007	Stored data could not be parsed.
8050	Authentication failed.
8101	No matching device found.

See the appendix for other error codes.

5.5 Recover Matter QR Code

During assembly, this API uses the input programming batch associated with the assembly batch, Matter VID, PID, Discriminator, and the Rotating Device Identifier (RDI) in BLE advertising to find a successfully programmed local device profile and recover its Matter onboarding data.

5.5.1 Request Method

POST

5.5.2 Request URL

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

5.5.3 Request Body

In addition to the common request headers, this API requires the following header:

Parameter	Required	Description
x-snbps-session	Yes	Programming Station session token returned by /login.

5.5.4 Request Body

The request body contains the following parameters:

Field	Type	Required	Description
batchId	string	Yes	Assembly batch ID. It must be associated with an input programming batch, have RUNNING status, and not be expired.
matterProductId	string	Yes	Matter PID as a hexadecimal string without a 0x prefix. Do not use productId or pid as the field name.
matterVendorId	string	Yes	Matter VID as a hexadecimal string without a 0x prefix. Do not use vendorId or vid as the field name.
discriminator	string	Yes	Hexadecimal string whose parsed value is in the range 0x000–0xFFF, for example 0F00. Do not pass a decimal string.
rotatingDeviceIdentifier	string	Yes	RDI from BLE advertising: 18 bytes (36 hexadecimal characters), without a 0x prefix. Use the actual advertised value.

5.5.5 Notes

• Query scope: Only successfully programmed local device profiles in the input programming batch associated with the assembly batch are queried. The API does not look up RDI in the cloud.
• Device matching: The device is matched using VID, PID, Discriminator, and RDI. An RDI mismatch or no matching device returns 8101.
• Data format: VID and PID are matched against their text values in the database. Use the same format as the batch data.

5.5.6 Request Example

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

5.5.7 Response Parameters

This API uses the standard JSON response format. The current implementation returns the following four fields in respData, rather than only setupPayload:

Field	Type	Description
setupPayload	string	Matter QR-code commissioning payload.
deviceId	string	Device ID
deviceProfileId	integer	Device profile ID
manualCode	string	Matter manual onboarding code. The field name is manualCode, not manualPairingCode.

5.5.8 Response Example

{
  "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 Main Error Codes

Error Code	Description
8002	Invalid Discriminator parameter.
8009	Batch has expired.
8010	Batch is not in RUNNING status.
8032	Assembly batch or its association does not exist.
8050	Authentication failed.
8101	No matching device found.

See the appendix for other error codes.

5.6 Upload Device Test File

This API uploads device test files. After receiving a file, it saves the file locally and creates an asynchronous upload task. The HTTP response only confirms receipt and local processing; it does not mean the file has reached cloud storage.

5.6.1 Request Method

POST

5.6.2 Request URL

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

5.6.3 Request Body

This API uses multipart/form-data as its Content-Type. In addition to the common request headers, supply the following header:

Parameter	Required	Description
x-snbps-session	Yes	Programming Station session token returned by /login.

5.6.4 Request Body

This API uploads files through multipart/form-data with the following parameters:

Field	Type	Required	Description
traceId	string (form field)	No	Existing script trace ID, if available; generated automatically if omitted. Pass the returned traceId unchanged to the production data upload API.
files	file[] (multipart parts)	Yes	List of files to upload; include at least one nonempty file. Repeat the files field to upload multiple files in one request. File names must not include a path, must not be . or .., and must be unique within the request.

5.6.5 Notes

• File handling: After receiving a file, the API saves it locally, then creates an asynchronous upload task.
• Task tracking: Pass an existing traceId if available; otherwise the API generates one. Pass the returned traceId unchanged to subsequent production data uploads.
• Upload status: A successful HTTP request does not mean the file has reached cloud storage. Errors during the background upload may not appear in the initial HTTP response.
• File size limits: File size is limited by the deployment's multipart configuration. application.yml defaults to 2 GB per file and 4 GB per request; the dev configuration sets 200 MB and 250 MB, respectively. Environment variables or external configuration may override the actual limits.

5.6.6 Request Example

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 Response Parameters

This API uses the standard JSON response format. respData contains the following fields:

Field	Type	Description
traceId	string	File task trace ID.
fileCount	integer	Number of files received in this request.
status	integer	Asynchronous file upload task status: 1 pending sync; 2 uploading; 3 successful; 4 awaiting retry; 5 failed; 6 local file cleaned up.

5.6.8 Response Example

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

5.6.9 Main Error Codes

Error Code	Description
8057	Invalid upload parameters.
8058	File list or file name does not meet requirements.
8059	Local file storage failed.
8060	Failed to save the file upload task.
8061	Background cloud storage upload failed.
8051	Insufficient storage space or concurrent processing capacity.

Errors during asynchronous background upload may not appear in the initial HTTP response. See the appendix for other error codes.

5.7 Connection Heartbeat

The programming client uses this API to check connectivity to the Edge service.

5.7.1 Request Method

GET

5.7.2 Request URL

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

5.7.3 Request Parameters

This is an initialization API. It does not require a Programming Station session token in advance and has no request parameters.

5.7.4 Notes

The client may call this API periodically as needed. A successful heartbeat only means the Edge HTTP service is reachable; it does not establish that other business services are healthy.

5.7.5 Request Example

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

5.7.6 Response Parameters

This API uses the standard JSON response format. On success, respData is null.

5.7.7 Response Example

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

5.8 Query Login Options

For compatibility with older clients, this API queries whether a U-Safe and a production password are required for the batch assigned to the Programming Station.

5.8.1 Request Method

GET

5.8.2 Request URL

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

5.8.3 Request Parameters

This is an initialization API and does not require a Programming Station session token in advance. Pass the following fields as query parameters:

Field	Type	Required / Condition	Description
usafeSN	string	Provide at least one of usafeSN or stationId.	Legacy U-Safe serial number.
stationId	string	Provide at least one of usafeSN or stationId.	Programming Station code; takes precedence when supplied.

5.8.4 Notes

• Query conditions: The Programming Station and its assigned batch must exist.
• Compatibility: This API supports older clients. In the newer login flow, call /queryLoginType first to determine the Programming Station login method.

5.8.5 Request Example

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

5.8.6 Response Parameters

This API uses the standard JSON response format. respData contains the following fields:

Field	Type	Description
requireUsafe	boolean	Whether U-Safe is required; currently always true.
requirePassword	boolean	Whether a production password is required, as determined by the assigned batch setting.

5.8.7 Response Example

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

5.8.8 Main Error Codes

Error Code	Description
8007	Programming Station or assigned batch not found.

See the appendix for other error codes.

5.9 Query Programming Station Login Method

This API queries the login method for a specified Programming Station and supports reporting client information for compatibility.

5.9.1 Request Method

POST

5.9.2 Request URL

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

5.9.3 Request Body

This is an initialization API and does not require a Programming Station session token in advance. The request body contains the following parameters:

Field	Type	Required / Condition	Description
factoryId	integer (int64)	Required for cloud factories	In cloud mode, verifies that the specified factory exists and is a cloud factory.
stationId	string	Yes	Programming Station code
clientPcMessage	string	No	JSON object string containing client information. Deprecated since 3.3.2; new clients should report it through /login.

5.9.4 Notes

Cloud factory login supports only password or Identity U-Safe authentication.

5.9.5 Request Example

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

5.9.6 Response Parameters

This API uses the standard JSON response format. respData contains the following fields:

Field	Type	Description
loginType	integer	Login method: 1 passwordless; 2 password; 3 Identity U-Safe.

5.9.7 Response Example

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

5.9.8 Main Error Codes

Error Code	Description
8016	Programming Station does not exist.
8036	Invalid cloud factory ID.

See the appendix for other error codes.

5.10 U-Safe Pre-login

This API performs the first step of U-Safe mutual authentication and returns the server certificate, challenge, and signature.

5.10.1 Request Method

GET

5.10.2 Request URL

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

5.10.3 Request Parameters

This is an initialization API and does not require a Programming Station session token in advance. Pass the following fields as query parameters:

Field	Type	Required / Condition	Description
usafeSN	string	Yes	Identity U-Safe serial number.
nonce	string	Yes	Client-generated random challenge.
type	integer	No	Compatibility parameter; the current method does not use its value.
factoryId	integer (int64)	Pass by factory in cloud mode	Used to match the factory scope in cloud mode.

5.10.4 Notes

• Scope: This API is for U-Safe mutual authentication, not direct password login.
• Signature handling: sign in the response is the server signature and cannot be used directly as the client login signature. The client should verify the server's identity, sign challenge according to the existing U-Safe authentication protocol, then call /login.

5.10.5 Request Example

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 Response Parameters

This API uses the standard JSON response format. respData contains the following fields:

Field	Type	Description
cert	string	Server authentication certificate.
challenge	string	Server challenge data for the client to sign.
sign	string	Server signature for the client to verify server identity.

5.10.7 Response Example

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

5.10.8 Main Error Codes

Error Code	Description
8020	U-Safe does not exist.
8031	U-Safe is unavailable.
8024 / 8026	Authentication or signature verification failed.

See the appendix for other error codes.

5.11 Programming Station Login

This API authenticates the Programming Station and obtains a station session token. After a successful login, the programming client passes the returned token in the x-snbps-session header on subsequent requests requiring a station session.

5.11.1 Request Method

POST

5.11.2 Request URL

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

5.11.3 Request Body

This is an initialization API and does not require a Programming Station session token in advance. The request body contains the following parameters:

Field	Type	Required / Condition	Description
stationId	string	Required for new login flow	When nonempty, authenticates the Programming Station; when omitted, uses the legacy U-Safe authentication flow.
factoryId	integer (int64)	Required for cloud factories	Factory ID
password	string	Required when loginType=2	Password encrypted with the existing RSA public key; do not pass plaintext.
usafeSN	string	Required for loginType=3 or legacy flow	Identity U-Safe serial number; must match the Programming Station.
sign	string	Required for U-Safe authentication	Client signature over the challenge returned by /preLogin.
usafeCert	string	No	Compatibility field; not directly used by the current controller branch.
clientPcMessage	string	No	JSON object string containing client information.

5.11.4 Notes

• Login method: Follow the authentication flow corresponding to the method returned by /queryLoginType.
• Passwordless login: NO_PASSWORD (loginType=1) does not require a password.
• Password login: PASSWORD (loginType=2) requires an RSA-encrypted password.
• U-Safe login: IDENTITY_USAFE (loginType=3) requires a prior /preLogin call and a client signature.
• Session token: The returned token authenticates the Programming Station session and must not be confused with a business operation's uuid or traceId.

5.11.5 Request Example

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

5.11.6 Response Parameters

This API uses the standard JSON response format. respData contains the following fields:

Field	Type	Description
stationId	string	Programming Station code
token	string	Programming Station session token
factoryId	integer (int64)	Factory ID
partnerCode	string	Tenant code

5.11.7 Response Example

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

5.11.8 Main Error Codes

Error Code	Description
8012	Programming Station already logged in
8014	Incorrect password
8016	Programming Station does not exist
8017	Unsupported login method
8020 / 8021	U-Safe does not exist or does not match
8036	Invalid cloud factory ID

See the appendix for other error codes.

5.12 Programming Station Logout

This API removes the current Programming Station session from the cache to log the station out.

5.12.1 Request Method

POST

5.12.2 Request URL

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

5.12.3 Request Body

This API should include the following header to identify the current Programming Station and factory context:

Parameter	Required / Condition	Description
x-snbps-session	Required for an effective logout.	Programming Station session token returned by /login

5.12.4 Request Parameters

This API requires no request parameters.

5.12.5 Notes

• Session identification: A valid x-snbps-session is required to identify and clear the corresponding Programming Station session.
• Validation: This API is not on the mandatory UkeyPermissionFilter validation path, but a valid session token is still required to log out effectively.
• Logout result: If the Programming Station context cannot be identified, do not assume that the specified station session was cleared.

5.12.6 Request Example

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

5.12.7 Response Parameters

This API uses the standard JSON response format; respData is null.

5.12.8 Response Example

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

5.13 Query Batches by Order Number

This API queries running batches for a specified order number in the current factory.

5.13.1 Request Method

GET

5.13.2 Request URL

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

5.13.3 Request Body

In addition to the common request headers, this API requires the following header:

Parameter	Mandatory	Description
x-snbps-session	Yes	Programming Station session token from /login

5.13.4 Request Parameters

This API accepts the following query parameter:

Field	Type	Mandatory	Description
orderNumber	string	Yes	Factory order number; it cannot be empty or whitespace only

5.13.5 Notes

• Query scope: Only batches in RUNNING status for the specified order number in the current factory are queried.
• Batch assignment: This API only queries batches; it does not automatically assign the returned batch to the current Programming Station.

5.13.6 Request Example

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

5.13.7 Response Parameters

This API uses the standard JSON response format. respData is an array of batch information, or an empty array [] if no batch matches. Each object contains:

Field	Type	Description
batchId	integer (int64)	Batch ID
batchName	string	Batch name

5.13.8 Response Example

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

5.13.9 Main Error Codes

Error code	Description
8039	Order number is empty
8050	Authentication failed

See the appendix for other error codes.

5.14 Assign Programming Station Batch

This API assigns a specified batch to the currently logged-in Programming Station and synchronizes the station–batch association.

5.14.1 Request Method

POST

5.14.2 Request URL

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

5.14.3 Request Headers

In addition to the common request headers, this API requires the following header:

Parameter	Mandatory	Description
x-snbps-session	Yes	Programming Station session token from /login

5.14.4 Request Body

The request body contains:

Field	Type	Mandatory	Description
batchId	integer (int64)	Yes	Batch ID to assign. It must belong to the current factory, be unexpired, and be running.

5.14.5 Notes

• Batch requirements: Only an unexpired, running batch in the current factory can be assigned.
• Assignment restriction: A Programming Station already assigned through Edge management cannot be reassigned through this API if overriding the association is prohibited.
• Repeated assignment: Assigning the same batch to a station already assigned to it returns 8011.

5.14.6 Request Example

{
  "batchId": 10
}

5.14.7 Response Parameters

This API uses the standard JSON response format. respData.batchInfo.batches is an array of batch details with the same structure as the batch details returned by /queryPPCBatchInfo.

5.14.8 Response Example

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

5.14.9 Main Error Codes

Error code	Description
8009	Batch has expired
8010	Batch is closed
8011	Programming Station is already assigned to this batch
8013	Data parsing failed
8016	Programming Station does not exist
8032	Batch does not exist
8035	Conflict with an assignment made in Edge management
8050	Authentication failed

See the appendix for other error codes.

5.15 Query Programming Station Batch Information

This API queries the batches associated with a Programming Station, programming scripts, and server load information.

5.15.1 Request Method

GET

5.15.2 Request URL

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

5.15.3 Request Headers

In addition to the common request headers, this API requires the following header:

Parameter	Mandatory	Description
x-snbps-session	Yes	Programming Station session token from /login

5.15.4 Request Parameters

This API accepts the following query parameters:

Field	Type	Mandatory	Description
usafeSN	string	No	For legacy U-Safe Programming Station queries
batchId	integer (int64)	No	When positive, queries the specified running batch. If neither parameter is provided, queries by the station in the current session.

5.15.5 Notes

• Query and assignment: This API only queries batch information; it does not perform /assignBatch.
• Programming type: programmingType distinguishes programming types such as MCU, SE, and SE_MCU. Use the value in the actual batch.
• Enum values: Follow the ProgrammingType enum and the actual API response. MATTER and SE_MATTER in older comments must not be used directly as request enum values.

5.15.6 Request Example

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

5.15.7 Response Parameters

This API uses the standard JSON response format and mainly returns the station's associated batches and server load information.

Field	Type	Description
usafeSN	string	U-Safe serial number
batchInfo.batches	array	Array of batches associated with the Programming Station; may be empty if no batch is available
serverLoadInfo.pressureLevel	integer	Server load level
serverLoadInfo.pressurePercentage	number	Server load percentage

5.15.8 Response Example

{
  "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 Batch Detail Fields

Each object in batchInfo.batches contains batch, chip, programming script, and production progress information, including:

Field	Type	Description
batchId	string	Batch ID
batchName	string	Batch name
chips	object[]	Chip information array; chipPart, chipVendor, and objectid are strings
env	string	Environment information
extData	string	Extended data
mark	string	Batch marker
notes	string	Batch notes
orderNo	string	Order number
produced	integer	Quantity produced
toBeProduced	integer	Quantity remaining
total	integer	Total batch quantity
productName	string	Product name
version	string	Product version
region	string	Region
secureDebugReopen	integer	Secure debug switch
supportProtocols	string[]	Supported protocol list
scriptName	string	Programming script name
scriptMd5	string	Programming script MD5 digest
scriptUrl	string	Programming script download URL
vid	string	Matter VID
pid	string	Matter PID
bindType	integer	Assignment method: 1, Edge management; 2, manual client assignment
programmingType	string	Programming type, such as MCU, SE, or SE_MCU; choose the programming flow from the actual response value

5.15.10 Main Error Codes

Error code	Description
8013	Data parsing failed
8015	Programming Station has no assigned batch
8016	Programming Station does not exist
8050	Authentication failed

See the appendix for other error codes.

5.16 Get Dynamic Programming Data

This API generates device programming data for the batch assigned to the current Programming Station and creates a production record for this programming operation.

5.16.1 Request Method

GET

5.16.2 Request URL

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

5.16.3 Request Headers

In addition to the common request headers, this API requires the following header:

Parameter	Mandatory	Description
x-snbps-session	Yes	Programming Station session token from /login

5.16.4 Request Parameters

This API accepts the following query parameters:

Field	Type	Mandatory / condition	Description
uuid	string	No	Trace ID for a single programming operation. If omitted, getProgrammingData generates one; retain and reuse it in later calls.
ppcliVersion	string	No	Client script version
usafeSN	string	Legacy flow compatibility	Since 3.1.1, no longer a primary parameter in the new flow. Station information takes precedence when a session station exists.
chipIndex	integer	No	No longer used since 3.1.1.

5.16.5 Notes

• Programming trace: Omit uuid on the initial call. After obtaining the returned uuid, retain and reuse it in subsequent /uploadRequestData, /executeApdu, or programming result requests.
• SE programming: In an SE-only scenario, a programming record is created even if the returned bundles array is empty.
• File download: Use the downloadUrl in the actual response for large files.
• Sensitive material: Sensitive production material is not sent as plaintext in a bundle.

5.16.6 Request Example

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

5.16.7 Response Parameters

This API uses the standard JSON response format. respData is a batch Bundle object containing:

Field	Type	Description
batchId	string	Batch ID
batchName	string	Batch name
uuid	string	Trace ID for this programming operation
bundles	object[]	Data entries for this programming operation; may be an empty array in an SE-only scenario

5.16.8 Response Example

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

5.16.9 Main Error Codes

Error code	Description
8013	Bundle data parsing failed
8030	No available Programming Station batch
8050	Authentication failed

See the appendix for other error codes.

5.17 Get Batch Metadata

This API returns complete batch metadata and download URLs for firmware and other files so the client can prepare device programming.

5.17.1 Request Method

GET

5.17.2 Request URL

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

5.17.3 Request Headers

The following header is recommended to resolve the current Programming Station and factory context:

Parameter	Mandatory / condition	Description
x-snbps-session	Recommended	Programming Station session token from /login

This API is not on the mandatory UkeyPermissionFilter validation path.

5.17.4 Request Parameters

This API accepts the following query parameters:

Field	Type	Mandatory / condition	Description
uuid	string	No	Trace ID for a single programming operation. If omitted, a later getProgrammingData call may generate one; retain it for later calls.
ppcliVersion	string	No	Client script version
usafeSN	string	Legacy flow compatibility	Since 3.1.1, no longer a primary parameter in the new flow. Station information takes precedence when a session station exists.
chipIndex	integer	No	No longer used since 3.1.1.

5.17.5 Notes

• Metadata retrieval: Returns the complete batch Bundle, performs the necessary metadata processing, and removes specified key material.
• Production record: This API does not replace /getProgrammingData in creating a programming record. The uuid in its response does not prove that a new production session was created.
• Programming Station context: A valid x-snbps-session can be used to resolve the current Programming Station.

5.17.6 Request Example

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

5.17.7 Response Parameters

This API uses the standard JSON response format. respData is a batch Bundle object containing:

Field	Type	Description
batchId	string	Batch ID
batchName	string	Batch name
uuid	1string	Programming trace ID in the response; does not prove that a production record was created
bundles	object[]	Complete batch data entries

5.17.8 Response Example

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

The empty bundles array in the example illustrates the response structure only; it does not mean every batch returns an empty array.

5.17.9 Main Error Codes

Error code	Description
8013	Data parsing failed
8030	No available Programming Station batch

See the appendix for other error codes.

5.18 Get Full Programming Data (Compatibility API)

This is the legacy API for retrieving a complete Bundle. Its service method is marked @Deprecated. New clients should use /getMetadata and /getProgrammingData.

5.18.1 Request Method

GET

5.18.2 Request URL

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

5.18.3 Request Headers

In addition to the common request headers, this API requires the following header:

Parameter	Mandatory	Description
x-snbps-session	Yes	Programming Station session token from /login

5.18.4 Request Parameters

This API accepts the following query parameters:

Field	Type	Mandatory / condition	Description
uuid	string	No	Trace ID for a single programming operation. In the new flow, getProgrammingData generates one if omitted; retain it for later calls.
ppcliVersion	string	No	Client script version
usafeSN	string	Legacy flow compatibility	Since 3.1.1, no longer a primary parameter in the new flow. Station information takes precedence when a session station exists.
chipIndex	integer	No	No longer used since 3.1.1.

5.18.5 Notes

• Batch query: This API identifies the batch by usafeSN, generates a new uuid, and returns the processed complete programming data.
• No available batch: The response may be null if no usable batch is found.
• Compatibility: This API supports legacy clients. New clients should use /getMetadata and /getProgrammingData.

5.18.6 Request Example

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

5.18.7 Response Parameters

This API uses the standard JSON response format. respData is a batch Bundle object containing:

Field	Type	Description
batchId	string	Batch ID
batchName	string	Batch name
uuid	string	Programming trace ID returned in this response
bundles	object[]	Processed complete programming data entries

5.18.8 Response Example

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

The empty bundles array in the example illustrates the response structure and is not the actual content for every batch. In an SE-only scenario, /getProgrammingData may return an empty bundles array.

5.18.9 Common Bundle Structure

Each Bundle object in the bundles array contains:

Field	Type	Description
type	string	Bundle type
section	string	Section to which the Bundle belongs
ownerId	string	Associated object ID
authToken	string	Authentication token
authCert	string	Authentication certificate
authSign	string	Authentication signature
items	object[]	List of Bundle data entries

Each entry in the items array contains:

Field	Type	Description
itemId	string	Entry ID
key	string	Entry key
objectId	string	Object ID
parentId	string	Parent object ID
fieldType	string	Field type
attribute	JSON object	Entry attributes; structure depends on field type

Bundle fields and content may differ by batch. Clients should follow the actual server response and download URLs; do not treat the empty bundles example as actual data for every batch.

5.18.10 Main Error Codes

Error code	Description
8050	Authentication failed

Other exceptional behavior of this legacy API depends on the old flow. See the appendix for specific error codes.

5.19 Submit Intermediate Programming Request Data

This API reports chip execution results for batch Bundle entries and lets the corresponding processor generate the next stage of programming data.

5.19.1 Request Method

POST

5.19.2 Request URL

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

5.19.3 Request Headers

In addition to the common request headers, this API requires the following header:

Parameter	Mandatory	Description
x-snbps-session	Yes	Programming Station session token from /login

5.19.4 Request Body

The request body contains:

Field	Type	Mandatory / condition	Description
batchId	string	Yes	Batch ID in the current factory
uuid	string	Required by business rules	Programming trace ID returned by /getProgrammingData; IDRule number allocation requires a valid, stable traceId
bundles	object[]	As needed	Reported Bundle data; if empty, the current implementation returns respData=null
bundles[].type	string	Per template	Bundle type
bundles[].section	string	Per template	Section to which the Bundle belongs
bundles[].deviceId	string	Recommended for IDRule	Stable device identifier. If omitted, the service attempts to resolve it from the record for uuid. Do not change it after initial number allocation.
bundles[].items	object[]	Required for a nonempty Bundle	List of Bundle entries; empty items or null entries are not allowed
bundles[].items[].key	string	Yes	Nonempty entry key
bundles[].items[].response	object[]	Per item protocol	List of results from the previous step; fields are defined by fieldType and the corresponding processor protocol

5.19.5 Notes

• Purpose: This API submits intermediate programming data; it does not report the final programming result.
• Data structure: Populate items[].key and response according to the actual batch template and processor protocol. Do not use the placeholders in the example directly.
• Device identifier: In an IDRule scenario, reuse a stable device identifier for the same device. Do not change deviceId in later programming steps after the first number allocation.
• Empty data: If bundles is empty, the current implementation returns respData=null.

5.19.6 Request Example

{
  "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 Response Parameters

This API uses the standard JSON response format. respData contains:

Field	Type	Description
batchId	string	Batch ID
batchName	string	Batch name
uuid	string	Programming trace ID for this operation
bundles	object[]	Next-stage programming data entries generated by the corresponding processor

5.19.8 Response Example

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

5.19.9 Main Error Codes

Error code	Description
8002	Invalid request parameters
8003	Data processing failed
8032	Batch does not exist
8040–8046	Certificate or key agreement error
8065	Invalid IDRule rule
8066	Number range exhausted
8067	State conflict
8068	Stable device identifier is missing
8050	Authentication failed

See the appendix for other error codes.

5.20 Report Programming Result

This API closes an existing device programming record and creates or updates the device profile, while remaining compatible with legacy clients.

5.20.1 Request Method

POST

5.20.2 Request URL

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

5.20.3 Request Headers

In addition to the common request headers, this API requires the following header:

Parameter	Mandatory	Description
x-snbps-session	Yes	Programming Station session token from /login

5.20.4 Request Body

The request body contains:

Field	Type	Mandatory / condition	Description
uuid	string	Yes (integration contract)	traceId of an existing programming record
batchId	integer (int64)	Recommended	Used as additional context when the programming record lacks batch information
result	boolean	Explicitly recommended	true means success; false or null is treated as failure
failureReason	string	No	Reason for programming failure
deviceProfile	object	No	Actual CPS programming data. Fields are described under deviceRecord in the Production Data Upload API, including deviceId, firmwareVersion, seid, cplc, matterData, factoryData, and customData.
changeKeys	object	No	Compatibility field. Accepts null, an empty string, or a JSON object; other types return 8002. The current programming result flow does not use this field further.

5.20.5 Notes

• Record handling: If the programming record does not exist or the current factory batch cannot be identified, the current method skips device profile creation and returns normally.
• Duplicate report: A repeated report with the same status, or a report for a record already in success status, is not processed again.
• Result confirmation: respCode="8000" does not necessarily mean a new device profile was created. Confirm through a device query API.
• Custom data: customData values must be strings and may contain at most 50 entries.
• Compatibility: The newer unified production data upload flow can report programming results through /v1/deviceData/upload.

5.20.6 Request Example

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

5.20.7 Response Parameters

This API uses the standard JSON response format. On success, respData is null.

5.20.8 Response Example

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

5.20.9 Main Error Codes

Error code	Description
8002	Invalid request parameters
8007	Data processing or storage error
8037	Device profile creation failed
8050	Authentication failed

See the appendix for other error codes.

5.21 SE APDU Stepwise Programming

This API performs stepwise APDU programming of an SE device. The client executes the APDU commands returned by the server in order and submits their results to obtain the next commands. A nextStep value of EOF means the programming flow is complete.

5.21.1 Request Method

POST

5.21.2 Request URL

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

5.21.3 Request Headers

In addition to the common request headers, this API requires the following header:

Parameter	Mandatory	Description
x-snbps-session	Yes	Programming Station session token from /login

5.21.4 Request Body

The request body contains:

Field	Type	Mandatory / condition	Description
batchId	string	Yes	SE configuration batch ID in the current factory. It cannot be omitted in reliance on the station assignment alone.
cplc	string	Provide for SE integration	CPLC protocol value of the SE device, usually 84 characters, used for the SE device record
seId	string	Provide for SE integration	SE identifier. The field name is case-sensitive: use seId.
nfcUid	string	For power keys	Protocol hex value of the device physical identifier; nfcId is accepted as an input alias. It must remain identical on initial and subsequent steps.
programmingTraceId	string	Optional for BOF; required for other steps	Programming trace ID; uuid is accepted as an input alias. In an SE_MCU flow, reuse the Matter session traceId. The response returns only programmingTraceId.
currentStep	string	Yes	Use BOF on the initial call. On subsequent calls, use nextStep from the previous response unchanged; do not construct a step cursor.
commandResults	object	Required for subsequent steps	Previous APDU execution result. Omit for BOF. For subsequent steps, succeed must be true and results must correspond to the previous commands.
commandResults.succeed	boolean	Required for subsequent steps	Whether the previous step succeeded. false stops the flow and returns 8053.
commandResults.results	object[]	For subsequent steps, follow the previous response	List of APDU execution results. Each entry contains index (integer) and command, checker, and result (strings). index must numerically match the string sequence number of the previous command.

5.21.5 Notes

• Initial call: Start programming with currentStep="BOF" and save programmingTraceId from the response for later steps.
• Command execution: The client must execute APDU commands in the order of commands and submit the actual results of the previous batch in the next request.
• Step control: Use the previous response's nextStep unchanged in the next request. Do not parse or modify the server step cursor. Stop at EOF; do not submit EOF again.
• Session recovery: 8054 means the current session cannot continue. Restart from BOF; do not automatically replay earlier APDU commands.
• Session lifetime: The current SE session lifetime is defined by a server configuration constant.
• Power key: nfcUid (or its input alias nfcId) must stay the same on the initial and subsequent steps. Do not use seId as the NFC UID.

5.21.6 Request Example

Use BOF on the initial call:

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

5.21.7 Response Parameters

This API uses the standard JSON response format. respData contains:

Field	Type	Description
nextStep	string	Next server step cursor; EOF means the flow is complete
programmingTraceId	string	Trace ID of this SE programming operation
commands	object[]	List of APDU commands to execute in this step
commands[].index	string	APDU command sequence number
commands[].checker	string	APDU response checker
commands[].command	string	APDU hex command to execute

5.21.8 Response Example

{
  "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 Subsequent-Step Request Example

After executing the previous batch of APDU commands, the client submits the results using programmingTraceId and nextStep returned by the server.

{
  "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>"
      }
    ]
  }
}

For a power key, include the same nfcUid (or input alias nfcId) in the initial request and every subsequent request. Do not download the raw production key file separately to the client. Edge prepares the relevant production material and returns it through the APDU commands for the current step. After successful programming reaches EOF, use the existing production count and device profile handling flow. If command execution on the card clearly failed, do not report commandResults.succeed as true.

5.21.10 Power Key Device Binding Rules

• Device identifiers: The current power key flow requires both nfcUid (input alias nfcId is supported) and seId.
• Data format: Pass both identifiers as even-length hexadecimal strings as required by the device protocol. The current allocation endpoint requires non-empty values of at most 64 characters and converts them to uppercase.
• Alias usage: Do not submit nfcUid and nfcId with different values. Keep the same nfcUid and device identity in the initial call and every continuation request.
• Material binding: Production materials are stored against the device binding of factory, batch, NFC UID, and SEID. Even if a device changes traceId or resends BOF, previously bound materials are reused first.
• Binding conflict: If an NFC UID or SEID is already bound but the other device identifier differs, the API returns 8073.
• Material exhaustion: If no production materials are available, the API returns 8072.
• Historical data: If a batch still has an allocation state from legacy Redis or production records that has not been migrated, the API may also return 8073. Resending BOF does not allocate new materials.

5.21.11 Main Error Codes

Error code	Description
8006	Batch or programming record is missing
8047	SE configuration is missing
8048	Data parsing failed
8049	CPLC-related error
8052	Step execution result does not match
8053	Previous step failed
8054	Session cannot continue; restart required
8055	APDU processing failed
8056	Configuration decryption failed
8070–8074	Production data, material allocation, or configuration error
8050	Authentication failed

See the appendix for other error codes.

5.22 Get Programming Script URL

This API obtains the programming script download URL for a specified batch.

5.22.1 Request Method

POST

5.22.2 Request URL

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

5.22.3 Request Headers

Provide the following request header to resolve the current station and factory context:

Parameter	Mandatory	Description
x-snbps-session	Recommended	Station session token returned by /login

This API is not on the mandatory validation path list of UkeyPermissionFilter.

5.22.4 Request Body

The request body contains the following parameters:

Field	Type	Mandatory / condition	Description
batchId	integer (int64)	Required when querying by batch	Batch ID
productId	integer (int64)	No	Compatibility parameter for product-based queries
chipPart	string	As needed	Chip model
chipVendor	string	As needed	Chip vendor

5.22.5 Notes

• Download URL: The client should download the programming script from the fileUrl returned by the API.
• Script verification: An HTTP success response does not mean the client has completed local script download and verification.

5.22.6 Request Example

{
  "batchId": 10
}

5.22.7 Response Parameters

This API uses the standard JSON response format. respData contains the following field:

Field	Type	Description
fileUrl	string	Programming script download URL returned by the server

5.22.8 Response Example

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

5.22.9 Main Error Codes

Error code	Description
8022	Failed to get the programming script

See the appendix for other error codes.

5.23 Download File

This API downloads a file by its local file record ID.

5.23.1 Request Method

GET

5.23.2 Request URL

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

5.23.3 Request Headers

Calls requiring factory context should provide the following request header:

Parameter	Mandatory / condition	Description
x-snbps-session	When factory context is required	Valid station session token returned by /login

5.23.4 Request Parameters

Pass the following fields as query parameters:

Field	Type	Mandatory	Description
fileId	integer (int64)	Yes	Local file record ID
fileName	string	No	Download filename requested by the client

5.23.5 Notes

• Response format: On success, the API returns a binary file stream with download headers such as Content-Disposition. It does not use the standard ClientR JSON response structure.
• Download URL: The client can use the full download URL returned by /getScriptFile or /getMetadata rather than building it manually.
• Session requirement: Provide a valid x-snbps-session when factory context is required.

5.23.6 Request Example

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 Response Parameters

On success, the API returns a binary file stream, not JSON respData.

5.23.8 Main Error Codes

Error code	Description
8022	File record does not exist
8023	File download failed

See the appendix for other error codes.

5.24 Upload Device Event Logs

This API receives event logs produced during device programming, filters them by configured priority, and reports them through MQTT. If sending fails, it saves a compensation record.

5.24.1 Request Method

POST

5.24.2 Request URL

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

5.24.3 Request Headers

In addition to the common request headers, provide the following header:

Parameter	Mandatory	Description
x-snbps-session	Yes	Station session token returned by /login

5.24.4 Request Body

The request body contains the following parameters:

Field	Type	Mandatory / condition	Description
programmingTraceId	string	Yes (non-null)	Programming trace ID; uuid is also accepted as an input alias
events	object[]	Yes (non-null)	Event log list; an empty array may be ignored
events[].eventName	string	Recommended	Event name
events[].timestamp	string	Recommended	Client event time in the format defined by the event protocol
events[].source	string	Recommended	Event source
events[].priority	string	Recommended	Event priority as a numeric string from 1 to 5; larger values mean higher priority. Empty or invalid values are filtered out.
events[].status	string	Recommended	Event status: success or failure
events[].content	string	No	Log content; the current implementation truncates it after 256 characters.

5.24.5 Notes

• Event filtering: The server filters events by the configured priority threshold. Events below the threshold or with invalid priority are not reported further.
• Log synchronization: A successful HTTP request means only that the API received and processed the request; it does not mean every event has been synchronized to the cloud.
• Failure compensation: If MQTT sending fails, the server saves a compensation record.

5.24.6 Request Example

{
  "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 Response Parameters

This API uses the standard JSON response format. On success, respData is null.

5.24.8 Response Example

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

5.24.9 Main Error Codes

Error code	Description
8050	Authentication failed

Request parameter binding or validation may also produce errors. See the appendix for other error codes.

5.25 Generate Matter Verifier

This API calls the Matter SDK to generate a Matter passcode, Salt, and Verifier.

5.25.1 Request Method

POST

5.25.2 Request URL

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

5.25.3 Request Headers

The current application.yml does not exclude this API from platform authentication. If platform authentication is enabled in the deployment, provide the following header:

Parameter	Mandatory / condition	Description
x-snbps-auth-token	When platform authentication is enabled	Platform authentication token, distinct from the station session token x-snbps-session

5.25.4 Request Parameters

This API requires no request parameters.

5.25.5 Notes

• Generation parameters: The current implementation fixes saltLen at 32 bytes and iterations at 1000. They cannot be overridden in the request body.
• Runtime dependency: The corresponding native Matter SDK must be deployed on the server.
• Status interpretation: The outer respCode and respData.status have different meanings. The former indicates the API business response status; the latter is the status returned by the Matter SDK.
• Example data: Numeric values in the response example illustrate field types only.

5.25.6 Request Example

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

5.25.7 Response Parameters

This API uses the standard JSON response format. respData contains the following fields:

Field	Type	Description
status	integer	Status code returned by the Matter SDK
passcode	integer	Matter passcode
salt	string	Base64-encoded Salt
verifier	string	Base64-encoded Verifier

5.25.8 Response Example

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

5.26 Generate Matter Onboarding Payload

This API calls the Matter SDK with specified Matter parameters to generate a QR code onboarding payload and manual pairing code.

5.26.1 Request Method

POST

5.26.2 Request URL

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

5.26.3 Request Headers

The current application.yml does not exclude this API from platform authentication. If platform authentication is enabled in the deployment, provide the following header:

Parameter	Mandatory / condition	Description
x-snbps-auth-token	When platform authentication is enabled	Platform authentication token, distinct from the station session token x-snbps-session

5.26.4 Request Parameters

The API accepts the following query or form parameters, not a JSON request body.

Field	Type	Mandatory	Description
vid	integer	Yes	Matter Vendor ID (VID) as a decimal integer, unlike the hexadecimal text used by the Matter payload recovery API
pid	integer	Yes	Matter Product ID (PID) as a decimal integer
passcode	integer	Yes	Matter passcode
commissioningFlow	integer	Yes	Matter SDK commissioning flow parameter
discoveryMode	integer	Yes	Matter SDK device discovery mode parameter

5.26.5 Notes

• Parameter transport: Although this API uses POST, all five parameters are bound with @RequestParam. Pass them through URL query or form parameters, not a JSON request body.
• Parameter validation: The underlying Matter SDK determines the valid range for each parameter.
• VID/PID format: This API uses decimal integers, unlike the hexadecimal strings used by /v1/matter/onboarding-payloads/recover.

5.26.6 Request Example

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

5.26.7 Response Parameters

This API uses the standard JSON response format. respData contains the following fields:

Field	Type	Description
status	integer	Status code returned by the Matter SDK
discriminator	integer	Matter onboarding Discriminator
qrcode	string	Matter QR code onboarding payload
manualcode	string	Matter manual pairing code; note that the field name manualcode is all lowercase

5.26.8 Response Example

{
  "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 Generate Matter Unique ID

This API calls the Matter SDK to generate a Matter Unique ID.

5.27.1 Request Method

POST

5.27.2 Request URL

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

5.27.3 Request Headers

The current application.yml does not exclude this API from platform authentication. If platform authentication is enabled in the deployment, provide the following header:

Parameter	Mandatory / condition	Description
x-snbps-auth-token	When platform authentication is enabled	Platform authentication token, distinct from the station session token x-snbps-session

5.27.4 Request Parameters

This API requires no request parameters or request body.

5.27.5 Notes

• Generation: The Matter SDK generates the Unique ID; the client supplies no generation parameters.
• Status interpretation: A successful Matter SDK status is usually 0, while the outer API business success code is 8000. They have different meanings.

5.27.6 Request Example

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

5.27.7 Response Parameters

This API uses the standard JSON response format. respData contains the following fields:

Field	Type	Description
status	integer	Status code returned by the Matter SDK
result	string	Base64-encoded Unique ID

5.27.8 Response Example

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

5.28 Query Device Data (Legacy API, Deprecated)

This API supports device data queries by legacy clients. New clients should use /v1/device/detail, or /v1/device/information/query for station query scenarios.

5.28.1 Request Method

POST

5.28.2 Request URL

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

5.28.3 Request Body

Provide the following request header to resolve the current station and factory context:

Parameter	Mandatory / condition	Description
x-snbps-session	Recommended	Station session token returned by /login

This API is not on the mandatory validation path list of UkeyPermissionFilter.

5.28.4 Request Body

The request body contains the following parameters:

Field	Type	Mandatory / condition	Description
batchId	string	Yes	Batch ID
paramKey	string	Yes	Key identifying the parameter group
paramField	string	Yes	Field to locate
paramValue	string	Yes	Field value identifying the device
queryKeys	string[]	Yes	See the queryable keys list (queryKeys V1) for supported keys.

5.28.5 Notes

• Compatibility: This API was declared deprecated in the v1.3 document and remains only for legacy clients.
• Query source: If the batch was deleted, a file cannot be read, or no local device profile matches, the API may query historical records or cloud data.
• Query parameters: queryKeys must follow the legacy Bundle query protocol. Do not use field definitions from the newer QueryKeys V2 directly.

5.28.6 Request Example

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

5.28.7 Response Parameters

This API uses the standard JSON response format. respData contains the following fields:

Field	Type	Description
batchId	string	Batch ID
paramKey	string	Parameter Key used by the query
paramField	string	Field used by the query
paramValue	string	Field value used by the query
data	map<string,map<string,object>>	Device information in the legacy data structure

5.28.8 Response Example

{
  "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 Main Error Codes

Error code	Description
8006	Batch does not exist
8003	Legacy device information query failed

See the appendix for other error codes.

5.29 Update Device Information (Legacy API, Deprecated)

This API supports updates using the legacy device data model. New clients should use /v1/updateDevicesProfile.

5.29.1 Request Method

POST

5.29.2 Request URL

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

5.29.3 Request Headers

Provide the following request header to resolve the current station and factory context:

Parameter	Mandatory / condition	Description
x-snbps-session	Recommended	Station session token returned by /login

This API is not on the mandatory validation path list of UkeyPermissionFilter.

5.29.4 Request Body

The request body contains the following parameters:

Field	Type	Mandatory / condition	Description
batchId	integer (int64)	Yes	Batch ID; note that this differs from the string type used by the legacy query API
paramKey	string	Yes	Key identifying the parameter group
paramField	string	Yes	Field to locate
paramValue	string	Yes	Field value identifying the device
data	map<string,map<string,string>>	Yes	Device data to update

5.29.5 Notes

• Compatibility: This API uses the legacy device data model. New clients should use /v1/updateDevicesProfile.
• Batch handling: If the specified batch does not exist, the current service returns directly, while the controller may still return the data from the request.
• Update confirmation: respCode="8000" and an echoed data value do not prove that data was persisted. Do not infer a successful device information update solely from the API response.

5.29.6 Request Example

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

5.29.7 Response Parameters

This API uses the standard JSON response format. respData is the data object from the request, of type map<string, map<string, string>>. It only echoes request data; it does not represent a fresh read of persisted state.

5.29.8 Response Example

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

6. Appendix

6.1 Appendix One: Queryable Keys (queryKeys V2)

Data item	Key
Matter commissioning: PBKDF iterations (1000)	matterData.iterations
Matter commissioning: salt length (32 bytes)	matterData.saltLength
Matter commissioning flow type (0 = standard flow)	matterData.commissioningFlows
Device discovery mode	matterData.discoverableMode
Matter Vendor ID	matterData.vid
Matter Product ID	matterData.pid
Discriminator	matterData.discriminator
Matter commissioning: rotating device ID enabled (true = enabled)	matterData.enableRotatingDeviceId
Matter manual pairing code	matterData.manualCode
Matter passcode	matterData.passcode
Matter onboarding QR code	matterData.qrcode
Matter salt used by the password derivation algorithm	matterData.salt
Matter device Unique ID (Base64 encoded)	matterData.uniqueid
Matter Verifier	matterData.verifier
Matter programming device serial number	matterData.serialNumber
Matter DAC certificate MD5	matterData.dacCertMd5
Matter PAI certificate MD5	matterData.paiCertMd5
Matter CD filename	matterData.cdFileName
Matter CD file MD5	matterData.cdFileMd5
Factory data; see the OBIS product configuration UI	factoryData.vendorName
Factory data; see the OBIS product configuration UI	factoryData.hardwareVersion
Factory data; see the OBIS product configuration UI	factoryData.hardwareVersionString
Factory data; see the OBIS product configuration UI	factoryData.partNumber
Factory data; see the OBIS product configuration UI	factoryData.productUrl
Factory data; see the OBIS product configuration UI	factoryData.productLabel
Factory data; see the OBIS product configuration UI	factoryData.productName
Factory data; see the OBIS product configuration UI	factoryData.startAddress
Programming status	programmingData.programmingStatus
Programming log	programmingData.programmingLog
Programming time	programmingData.programmingTime
MCU ID in the programmed chip	chipData.chipUid
Chip Bluetooth MAC address	chipData.bleMac
Firmware name (returns firmware list)	firmwareData.fwName
Firmware MD5 (returns firmware list)	firmwareData.fwMd5
Custom field	customData.<custom field>

6.1.1 Additional Query Keys

tip

This API follows queryKeys V2 naming. Matter data uses matterData.manualCode, matterData.qrcode, and matterData.uniqueid, which differ from manualPairingCode and setupPayload in the "Query Device Information" API; do not mix them.

Data item	Key	Description
SE data	seData	Returns the complete SE data object in the device profile
Query entire group	matterData / factoryData / programmingData / chipData / firmwareData / customData	A group name without a dot queries its supported fields; the exact response depends on the current implementation.

6.2 Appendix Two: Error Code List

The following table lists client business error codes used by the APIs and their descriptions.

• Each API uses only a subset of these codes. See the corresponding API description for causes and handling.
• Parameter validation, platform authentication, and framework processing may produce other error codes not listed here.
• An SDK status of 0 has a different meaning from respCode="8000" in the standard API response; do not confuse them.

respCode	Enum name	Description
8000	NO_ERROR	Operation succeeded (NoError)
8001	REQUEST_FAILED	Request failed (RequestFailed)
8002	PARAM_ERROR	Invalid parameter (ParamError)
8003	METHOD_ERROR	Invalid method (MethodError)
8004	AUTH_ERROR	Authentication failed (AuthError)
8005	USAFE_TYPE_ERROR	Invalid U-Safe type (USafeTypeError)
8006	DATA_NOT_FOUND	Data not found (DataNotFound)
8007	DATA_ERROR	Invalid data (DataError)
8008	NOT_ALLOWED	Operation not allowed (NotAllowed)
8009	BATCH_EXPIRED_ERROR	Batch expired
8010	BATCH_STATUS_CLOSED	Batch closed
8011	STATION_BATCH_HAS_BIND	Batch already assigned to this station
8012	STATION_HAS_LOGIN	Station already logged in (StationHasLogin)
8013	BATCH_BUNDLE_PARSE_ERROR	Failed to parse the Bundle file generated for the batch
8014	STATION_PASSWORD_ERROR	Incorrect station password (StationPasswordError)
8015	STATION_NOT_BIND_BATCH	Station has no assigned batch
8016	STATION_NOT_EXIST	Station does not exist
8017	UNKNOWN_LOGIN_TYPE	Unknown login type
8018	FACTORY_NOT_EXIST	Factory does not exist
8019	FACTORY_STATUS_LOCKED	Factory is locked
8020	USAFE_NOT_FOUNT	U-Safe not found
8021	STATION_USAFE_NOT_MATCH	U-Safe does not match station ID
8022	FETCH_BURN_SCRIPT_ERROR	Failed to get programming script
8023	DOWNLOAD_BURN_SCRIPT_ERROR	Failed to download programming script
8024	PRELOGIN_AUTH_ERROR	Pre-login authentication failed
8025	HSM_CERT_SYNC_REQUIRED	HSM authentication certificate not found. Edit factory HSM information in the cloud to trigger certificate synchronization.
8026	SIGN_VERIFY_ERROR	Signature verification failed
8027	BATCH_HAS_DONE	Batch completed
8028	BATCH_FILE_NOT_EXIST	Operation failed: product batch file does not exist
8029	BATCH_IMPORT_FAILED	Failed to import batch
8030	PS_BURN_STATION_RECORDING_FINISHED	U-Safe SN has completed programming or is not assigned to a batch
8031	USAFE_UNAVAILABLE	U-Safe unavailable
8032	BATCH_NOT_FOUND	Batch not found
8033	BATCH_DOWNLOAD_STATUS_NOT_WAIT	Batch download status is not pending
8034	DEVICES_PROGRAMMER_DATA_UPLOAD_ERROR	Failed to upload device adapter data
8035	STATION_HAS_EDGE_BIND	Station already assigned a batch from the Edge Service
8036	CLOUD_FACTORY_ID_ERROR	Invalid cloud factory ID
8037	DEVICE_PROFILE_GENERATE_ERROR	Failed to generate device profile
8038	UNSUPPORTED_CERTIFICATE_FORMAT	Unsupported certificate format
8039	ORDER_NUMBER_CANNOT_BE_EMPTY	Order number must not be empty
8040	CERT_CHAIN_VERIFY_FAILED	Silicon Labs certificate chain verification failed
8041	PUBKEY_SIGNATURE_VERIFY_FAILED	Chip temporary public key signature verification failed
8042	ECDH_KEY_AGREEMENT_FAILED	ECDH key agreement failed
8043	SESSION_KEY_NOT_FOUND	Session key does not exist or has expired
8044	KEY_WRAP_FAILED	Key encapsulation failed
8045	DAC_PUBKEY_SIGNATURE_VERIFY_FAILED	DAC public key signature verification failed
8046	BUNDLE_PUBLIC_KEY_NOT_FOUND	Bundle public key material for the specified keyCode not found
8047	SE_PROFILE_NOT_FOUND	SE Profile for the batch not found
8048	SE_PROFILE_PARSE_ERROR	Failed to parse SE Profile
8049	CPLC_INVALID	Invalid CPLC; length must be 84
8050	PERMISSION_CHECK_DENY	Authorization verification failed; obtain verification permission again
8051	SERVER_PERFORMANCE_LIMIT	Concurrency limit reached; ask the factory administrator to check the server
8052	APDU_SESSION_INVALID	Invalid executeApdu session: command result for the current step does not match the expected result
8053	APDU_STEP_FAILED	Previous APDU execution failed
8054	APDU_RESTART_REQUIRED	APDU session invalid or expired; restart programming for this device
8055	APDU_PROCESS_FAILED	Failed to process APDU Profile step
8056	SE_PROFILE_DECRYPT_ERROR	Failed to decrypt SE Profile
8057	TEST_FILE_PARAM_ERROR	Invalid test file upload parameters
8058	TEST_FILE_MANIFEST_ERROR	Invalid test file manifest
8059	TEST_FILE_STORAGE_ERROR	Failed to save test file locally
8060	TEST_FILE_TASK_ERROR	Failed to save test file upload task
8061	TEST_FILE_UPLOAD_ERROR	Failed to upload test file to cloud storage
8064	TEST_DATA_TASK_ERROR	Failed to save test data report task
8065	ID_RULE_INVALID	Invalid ID Rule description
8066	ID_RULE_RANGE_EXHAUSTED	ID Rule allocation range exhausted
8067	ID_RULE_CONFLICT	ID Rule status conflicts with batch description
8068	ID_RULE_DEVICE_KEY_REQUIRED	A stable device identifier is required to parse the ID Rule
8069	SCENARIO_TYPE_NOT_BE_NULL	scenarioType must not be empty
8070	DATA_INVALID	Invalid production data
8071	KEY_DECRYPT_FAILED	Failed to decrypt batch protection key
8072	DATA_EXHAUSTED	Production data exhausted
8073	ASSIGNMENT_CONFLICT	Production data allocation conflicts with batch or device
8074	PROFILE_INVALID	Programming requires a PERSONALIZE operation and corresponding Applet selection information
8101	DEVICE_NOT_FOUND	Device not found; check query parameters
8102	MULTI_DEVICES_FOUND	Multiple devices matched; add filters
8103	QUERY_CONDITION_REQUIRED	Specify at least one valid query condition in deviceLocator

6.3 Appendix Three: Updatable Keys (updateDevicesProfile)

Keys supported by the Update Devices Profile API:

Data item	Key	Value description
Device extension field	extend.<extension field key>	Supported extension fields: vid, pid, chipId, qrcode, pairingCode
env	environment	test / prod
Production time	manufactureTime	string Time format: 2020-11-11T01:11:11+08:00
Version name	productVersion	string
Batch name	productBatch	string
Factory name	factory	string
Programming station name	programmingStation	string
Programming status	programmingStatus	Complete / Failed / Unreported
DAC certificate serial number	dacSerialNo	string
DAC certificate commonName	dacCommonName	string
DAC certificate VID	dacVid	string
DAC certificate PID	dacPid	string
Subject key identifier	subjectKeyIdentifier	string
Authority key identifier	authorityKeyIdentifier	string
DAC effective date	notBefore	string Time format: 2020-11-11T01:11:11+08:00
DAC expiration date	notAfter	string Time format: 2020-11-11T01:11:11+08:00
Pairing code	pairingCode	string
QR code	qrcode	string
DAC expiration time (date, time, and time zone)	expiryDate	string Time format: 2020-11-11T01:11:11+08:00
Remaining days of DAC validity	leftDays	string
Issued DAC certificate	certificate	string
Field in factoryData	factoryData.<key name>	string Supports deletion of the corresponding key in factory data.
Script filename	programmingScript	string Supports deletion of the script file with this name. Only one script file may exist; uploading a new script filename overwrites the prior file record.
Firmware	firmwareData.<firmware name>	The startAddress of the named firmware may be updated. Deletion of the named firmware is supported.
otherFiles	otherFile.<filename>	The key of the named file in otherFile may be updated. Deletion of the named file is supported.
attachmentFiles	attachment.<filename>	The key of the named attachment may be updated. Deletion of the named file is supported.

6.4 Appendix Four: Queryable Keys (queryKeys V1)

tip

• If a data item is not configured for the product, the API returns an empty value for it.
• The digit 1 in the key fw1.fileName denotes the first firmware file.

Data item	Key
CD file MD5	cdFile.md5
CD filename	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
QR code	matterCommissioningParameter.qrcode
Firmware filename	fw1.fileName
Device programming result	programmingStatus
Manual pairing code	matterCommissioningParameter.manualCode
Original passcode	matterCommissioningParameter.passcode

6.5 Typical Business Call Flows

This section gives typical API call sequences for station programming, testing, and assembly. See each API description for its request parameters, response structure, and handling rules.

6.5.1 Station Programming

After login, batch query, and assignment, the station obtains programming data, programs the device, and reports the result. A typical call flow is:

queryLoginType
    ↓
 preLogin (as needed)
    ↓
 login
    ↓
 queryPPCBatchInfo / queryBatchByOrderNumber
    ↓
 assignBatch (as needed)
    ↓
 getMetadata
    ↓
 getProgrammingData
    ↓
 uploadRequestData (as required by programming items)
    ↓
 programmingResult / deviceData/upload

For SE programming, also observe the following rules:

• SE-only scenario: A production record may be created at the BOF stage.
• Mixed SE_MCU programming: Reuse the same traceId from the MCU or Matter programming stage, then execute SE programming operations through executeApdu until EOF.

6.5.2 Testing and Assembly

Testing and assembly data is reported through /v1/deviceData/upload. To associate a test file, upload the file first, then submit the related production data. A typical call flow is:

login
    ↓
 testFile/upload (as needed)
    ↓
 deviceData/upload

When calling these APIs, note:

• Testing: For the first upload without attachments, traceId may be omitted, but scenarioType is required. Use the traceId returned by the API for subsequent uploads.
• File association: To attach a test file, first upload it through /v1/testFile/upload, then use the returned traceId in /v1/deviceData/upload.
• Assembly: Use the batchId of the actual assembly batch and report the execution result through deviceRecord.testData.result.

Depending on the business flow, a scan may first call /v1/matter/onboarding-payloads/recover to recover Matter onboarding data. Use /v1/device/information/query when detailed device information is needed.