集成 API
创建 API 集成导入升级任务
鉴权方式
HAP 组织授权开放接口为每个组织提供一套独立的密钥信息（AppKey 和 SecretKey），组织可通过此密钥信息安全调用 HAP 平台开放的各类接口，包括人员组织管理、汇报关系管理、应用管理、流程待办等数据接口。
版本
请求地址
Query 参数
| 名称 | 类型 | 必填 | 描述 |
|---|---|---|---|
appKey | string | 是 | AppKey |
sign | string | 是 | 按组织授权签名规则生成的签名，作为查询参数传入时需进行 URL 编码 |
timestamp | integer<int64> | 是 | 时间戳（与签名所用时间戳一致，精度为毫秒） |
projectId | string | 是 | 组织编号 |
accountId | string | 是 | 操作人账号 ID |
Body 参数
| 名称 | 类型 | 必填 | 描述 |
|---|---|---|---|
operatorId | string | 是 | 操作人 ID |
mediaId | string | 是 | 已上传的 API 集成文件 ID |
integrationId | string | 是 | 需要升级的 API 集成 ID |
overwriteParams | boolean | 是 | — 可选值： true |
connectionParams | object[] | 是 | — |
connectionParams.name | string | 是 | 连接参数名称，区分大小写，同一次请求中不能重复 |
connectionParams.value | string | 是 | 需要设置的参数值；空字符串表示清空，不接受 null |
callback | string<uri> | 否 | 导入升级结果回调地址。须为 HAP 系统可访问且不携带参数的 HTTP 或 HTTPS 地址。 |
响应参数
200调用成功仅表示升级任务创建成功，最终结果通过升级详情查询接口或回调获取。任务状态继续使用 RUNNING、SUCCESS、FAILED。HTTP 200 不一定表示业务成功；请求校验失败时返回 status=2、data 信息列表及 msg。响应结构 1
| 名称 | 类型 | 描述 |
|---|---|---|
success | boolean | 请求是否成功 |
data | object | — |
data.upgradeId | string | 升级任务 ID，用于查询 API 集成升级任务详情。查询响应 success=true 只表示查询成功，最终升级结果以 data.status 为准：RUNNING 执行中、SUCCESS 成功、FAILED 失败。也可通过 callback 接收结果。 |
响应结构 2
| 名称 | 类型 | 描述 |
|---|---|---|
status | integer | 校验状态，2 表示数据校验失败 可选值： 2 |
data | string[] | 校验失败信息列表 |
msg | string | 状态说明 |
响应参数
400连接参数校验失败。overwriteParams=true 时数组缺失或为空、value 为 null、名称重复均可导致创建任务失败；执行阶段校验失败通过任务状态 FAILED 表示。| 名称 | 类型 | 描述 |
|---|---|---|
code | integer | 错误码，2000 表示业务错误，400 表示连接参数校验失败，401 表示鉴权失败 |
message | string | 错误说明 |
exception | string | null | 异常信息 |
响应参数
401鉴权失败| 名称 | 类型 | 描述 |
|---|---|---|
code | integer | 错误码，2000 表示业务错误，400 表示连接参数校验失败，401 表示鉴权失败 |
message | string | 错误说明 |
exception | string | null | 异常信息 |
Callbacks
curl -X POST "https://example.com/integration/v1/integration/ImportUpgrade?appKey=string&sign=string×tamp=0&projectId=string&accountId=string" \ -H "Content-Type: application/json" \ -d '{ "operatorId": "user_123", "mediaId": "file_222", "integrationId": "api_integration_abc123", "overwriteParams": true, "connectionParams": [ { "name": "client_id", "value": "new_client_id" }, { "name": "client_secret", "value": "new_client_secret" } ], "callback": "https://example.com/import/callback" }'{ "data": { "upgradeId": "upg_20250211_000001" }, "success": true}