跳至主要内容

HAP API V3 规范

V3 接口遵循 RESTful 风格，以资源为中心设计 URL，通过请求方法表达操作意图，使用 JSON 格式传递数据。

一、API 组成​

一个完整的 API 请求由五部分组成：请求方法、请求地址、鉴权、请求参数、响应参数。

1.1 请求方法（Method）​

告诉服务器你要做什么操作。

方法含义说明实际案例
GET查询获取单条或列表数据，不修改资源获取应用信息、获取行记录详情、获取日志
POST新建创建新资源，由服务端分配 ID；查询参数复杂时也使用 POST新建工作表、新建行记录；获取记录列表（含筛选器）
PUT整体更新替换整个资源，未传字段会被清空—
PATCH局部更新只更新传入的字段，其余字段保持不变更新行记录、批量更新行记录
DELETE删除删除指定资源删除工作表、删除行记录、批量删除

1.2 请求地址（Host + URL）​

告诉服务器你要操作哪个资源，由 Host 和 URL 拼接而成：

https://api.mingdao.com   +   /v3/app/worksheets/{worksheet_id}/rows
        ↑ Host（环境域名）              ↑ URL（资源路径）

1.3 鉴权（Authentication）​

鉴权用于验证"你是谁、有没有权限"，凭证统一放在请求 Header 中，每个请求都必须携带。V3 支持三种鉴权方式：

方式Header 参数说明
AppKey + SignHAP-Appkey、HAP-Sign应用密钥鉴权，由管理员创建，以应用管理员身份访问数据
PATAuthorization: Bearer {{access_token}}、HAP-Appid（部分接口必填）个人访问凭证（Personal Access Token），自行创建，以个人身份操作，可设定有效期和权限范围
OAuth 2.0Authorization: Bearer {{access_token}}、HAP-Appid（部分接口必填）用户通过 OAuth 集成完成授权，可配置权限范围，短期有效，支持自动刷新

三种方式对比：

维度AppKey + SignPATOAuth 2.0
创建者管理员个人集成开发者
操作身份应用管理员个人被授权用户
有效期长期可设定短期，自动刷新
适用场景服务端集成个人脚本 / 工具第三方应用集成

1.4 请求参数（Input）​

不同的请求方法，参数的传递位置也不同。参数分三种位置：

Path 参数 — URL 中的资源标识，必填，直接写在路径里：

/v3/app/worksheets/{worksheet_id}/rows/{row_id}
                    ↑ 必填，工作表 ID      ↑ 必填，行记录 ID

Query 参数 — 拼接在 URL ? 后面，适用于 GET 请求的简单条件：

GET /v3/app/worksheets/{worksheet_id}/rows/{row_id}?pageSize=50&pageIndex=1

Body 参数 — 放在请求体里（JSON 格式），适用于 POST、PATCH 请求的复杂数据：

{
  "fields": [...],
  "triggerWorkflow": true
}

1.5 响应参数（Output）​

所有接口统一返回 JSON 格式：

{
  "success": true,       // 是否成功
  "error_code": 1,       // 错误码，1 表示成功
  "error_msg": "string", // 错误信息
  "data": {}             // 业务数据，类型为 object 或 Array[object]
}

二、环境地址​

环境Host
HAP SaaS 环境https://api.mingdao.com
私有部署环境{私有部署 host}/api（示例：https://p-demo.mingdaoyun.cn/api）

三、URL 命名规范​

URL 路径以资源层级为核心进行组织，通过路径结构表达资源归属，通过请求方法表达操作意图。

3.1 资源层级​

子资源挂在父资源路径下，从左到右逐层嵌套：

/v3/app                                          # 应用（顶级资源）
/v3/app/worksheets                               # 工作表集合（应用下）
/v3/app/worksheets/{worksheet_id}                # 单个工作表
/v3/app/worksheets/{worksheet_id}/rows           # 行记录集合（工作表下）
/v3/app/worksheets/{worksheet_id}/rows/{row_id}  # 单条行记录

3.2 增删改查​

通过请求方法 + 路径共同表达操作意图：

GET    /v3/app/worksheets/{worksheet_id}/rows/list       # 查列表（复杂筛选用 POST + /list）
GET    /v3/app/worksheets/{worksheet_id}/rows/{row_id}   # 查详情（路径含 ID）
POST   /v3/app/worksheets/{worksheet_id}/rows            # 新建（集合路径，无 ID）
PATCH  /v3/app/worksheets/{worksheet_id}/rows/{row_id}   # 更新（路径含 ID）
DELETE /v3/app/worksheets/{worksheet_id}/rows/{row_id}   # 删除（路径含 ID）

3.3 批量操作​

集合路径 + /batch，方法区分操作类型：

POST   /v3/app/worksheets/{worksheet_id}/rows/batch      # 批量新建
PATCH  /v3/app/worksheets/{worksheet_id}/rows/batch      # 批量更新
DELETE /v3/app/worksheets/{worksheet_id}/rows/batch      # 批量删除

3.4 特殊功能​

追加功能名，单词或短横线连接：

GET  /v3/app/worksheets/{worksheet_id}/rows/pivot                    # 透视数据（集合级功能）
POST /v3/app/worksheets/{worksheet_id}/rows/{row_id}/share-link      # 分享链接（短横线）
GET  /v3/app/worksheets/{worksheet_id}/rows/{row_id}/logs            # 操作日志
GET  /v3/app/worksheets/{worksheet_id}/rows/{row_id}/discussions     # 讨论
GET  /v3/app/worksheets/{worksheet_id}/rows/{row_id}/relations/{field} # 关联记录

四、参数命名规范​

位置命名风格示例
Header 鉴权参数HAP- 前缀HAP-Appkey、HAP-Sign、HAP-Appid
路径参数 - 资源名称单词或短横线连接app、worksheets、share-link
路径参数 - 资源 ID下划线连接，花括号包裹{worksheet_id}、{row_id}、{app_id}
Query 参数（GET）小驼峰（camelCase）pageSize、pageIndex、responseFormat
Body 参数（POST/PATCH）小驼峰（camelCase）triggerWorkflow、rowIds、fields
响应参数小驼峰（camelCase）total、pageIndex、pageSize
系统字段_ 前缀 + 小驼峰_createdBy、_owner、_createdAt、_updatedAt

五、输入/输出参数结构定义规范​

data 直接返回对象或数组；嵌套结构中，对象的唯一标识统一用 id，不带类型前缀。

示例一：输入对象​

字段列表 fields 下的字段名称直接叫 name，而不是 fieldName：

{
    "name": "测试新建工作表",
    "sectionId": "",
    "createDefaultView": false,
    "fields": [
        {
            "name": "文本",
            "alias": "",
            "type": "2",
            "required": true,
            "isTitle": true
        },
        {
            "name": "单选",
            "alias": "",
            "type": "11",
            "options": [
                { "value": "选项名称1", "index": 1 },
                { "value": "选项名称2", "index": 2 }
            ],
            "config": {
                "isColorOptions": true
            },
            "required": true
        }
    ]
}

示例二：data 响应返回数组​

获取工作表列表：

{
  "success": true,
  "error_code": 0,
  "error_msg": "string",
  "data": [
    {
      "id": "string",
      "name": "string",
      "remark": "string"
    }
  ]
}

示例三：data 响应返回嵌套对象​

获取行记录列表：

{
  "success": true,
  "error_code": 0,
  "error_msg": "string",
  "data": {
    "rows": [
      {
        "id": "row123",
        "fields": [
          {
            "id": "field1",
            "value": "示例值",
            "type": "2",
            "controlName": "文本字段"
          }
        ],
        "_createdBy": {
          "accountId": "user123",
          "fullname": "张三"
        },
        "_owner": {
          "accountId": "user123",
          "fullname": "张三"
        },
        "_createdAt": "2024-03-25T15:52:58.000Z",
        "_updatedAt": "2024-03-25T15:52:58.000Z",
        "_updatedBy": {
          "accountId": "user123",
          "fullname": "张三"
        }
      }
    ],
    "total": 100,
    "pageIndex": 1,
    "pageSize": 20
  }
}

六、系统字段说明​

系统字段由平台自动维护，统一使用 _ 前缀，不占用用户自定义字段的命名空间。V3 对 V2 字段名做了语义化升级：

含义V2 字段名V3 字段名
拥有者ownerid_owner
创建人caid_createdBy
创建时间ctime_createdAt
最近修改时间utime_updatedAt
最近修改人uaid_updatedBy
流程名称wfname_processName
节点负责人wfcuaids_nodeAssignees
发起人wfcaid_initiatedBy
发起时间wfctime_initiatedAt
节点开始时间wfrtime_nodeStartedAt
审批完成时间wfcotime_approvalCompletedAt
截止时间wfdtime_dueAt
剩余时间wfftime_remainingTime
流程状态wfstatus_processStatus

七、V3 接口列表​

用户​
接口名称方法URL
获取用户所在组织列表GET/v3/orgs/list
获取当前用户信息GET/v3/users/me
应用管理​
接口名称方法URL
获取应用列表GET/v3/apps/list
创建应用POST/v3/apps
获取应用信息GET/v3/app
创建应用项分组POST/v3/app/sections/batch
批量创建应用项POST/v3/app/items/batch
编辑应用POST/v3/app
删除应用DELETE/v3/app
工作表​
接口名称方法URL
获取工作表列表POST/v3/app/worksheets/list
新建工作表POST/v3/app/worksheets
获取工作表结构信息GET/v3/app/worksheets/{worksheet_id}
更新工作表结构POST/v3/app/worksheets/{worksheet_id}/structure
删除工作表DELETE/v3/app/worksheets/{worksheet_id}
行记录​
接口名称方法URL
获取行记录列表POST/v3/app/worksheets/{worksheet_id}/rows/list
获取行记录详情GET/v3/app/worksheets/{worksheet_id}/rows/{row_id}
新建行记录POST/v3/app/worksheets/{worksheet_id}/rows
更新行记录PATCH/v3/app/worksheets/{worksheet_id}/rows/{row_id}
删除行记录DELETE/v3/app/worksheets/{worksheet_id}/rows/{row_id}
批量新增行记录POST/v3/app/worksheets/{worksheet_id}/rows/batch
批量更新行记录PATCH/v3/app/worksheets/{worksheet_id}/rows/batch
批量删除行记录DELETE/v3/app/worksheets/{worksheet_id}/rows/batch
获取关联记录GET/v3/app/worksheets/{worksheet_id}/rows/{row_id}/relations/{field}
获取行记录透视数据POST/v3/app/worksheets/{worksheet_id}/rows/pivot
获取记录分享链接POST/v3/app/worksheets/{worksheet_id}/rows/{row_id}/share-link
获取行记录日志GET/v3/app/worksheets/{worksheet_id}/rows/{row_id}/logs
获取行记录讨论GET/v3/app/worksheets/{worksheet_id}/rows/{row_id}/discussions
视图​
接口名称方法URL
批量创建视图POST/v3/app/worksheets/{worksheet_id}/views/batch
统计图​
接口名称方法URL
新建统计图POST/v3/app/worksheets/{worksheet_id}/charts
自定义页面​
接口名称方法URL
更新自定义页面PUT/v3/app/custom-pages/{page_id}
工作流​
接口名称方法URL
获取触发流程列表GET/v3/app/workflow/processes
获取触发流程详情GET/v3/app/workflow/processes/{process_id}
触发流程POST/v3/app/workflow/hooks/{process_id}
创建流程POST/v3/app/workflows
批量创建流程节点POST/v3/app/workflows/{workflow_id}/nodes/batch
删除流程节点DELETE/v3/app/workflows/{workflow_id}/nodes/{node_id}
删除流程DELETE/v3/app/workflows/{workflow_id}
获取流程结构GET/v3/app/workflows/{workflow_id}
校验流程POST/v3/app/workflows/{workflow_id}/validate
发布流程POST/v3/app/workflows/{workflow_id}/publish
流程待办​
接口名称方法URL
获取用户流程待办列表GET/v3/app/workflow/instance/list
获取审批待办详情GET/v3/app/workflow/instance/{instance_id}
批量审批POST/v3/app/workflow/instance/batch
撤销POST/v3/app/workflow/instance/{instance_id}/revoke
退回POST/v3/app/workflow/instance/{instance_id}/return
中止POST/v3/app/workflow/instance/{instance_id}/terminate
催办POST/v3/app/workflow/instance/{instance_id}/urge
对话机器人​
接口名称方法URL
新建对话机器人POST/v3/app/chatbots
角色​
接口名称方法URL
获取角色列表GET/v3/app/roles
创建角色POST/v3/app/roles
获取角色详情GET/v3/app/roles/{role_id}
删除角色DELETE/v3/app/roles/{role_id}
添加角色成员POST/v3/app/roles/{role_id}/members
移除角色成员DELETE/v3/app/roles/{role_id}/members
成员退出所有角色DELETE/v3/app/roles/users/{user_id}
向量知识库​
接口名称方法URL
获取向量知识库列表POST/v3/app/knowledge/list
向量知识库检索POST/v3/app/knowledge/search
组织​
接口名称方法URL
查找组织部门GET/v3/departments/lookup
获取地区信息GET/v3/regions/lookup
其他​
接口名称方法URL
查找组织成员GET/v3/users/lookup
获取选项集列表GET/v3/app/optionsets
创建选项集POST/v3/app/optionsets
编辑选项集PUT/v3/app/optionsets/{optionset_id}
停用选项集DELETE/v3/app/optionsets/{optionset_id}

错误码​

错误码说明
0失败
1成功
51请求限流
10000拒绝访问，IP 受限
10001参数错误
10002参数值错误
10005数据操作无权限
10006数据已存在
10007数据不存在或已经删除
10101令牌不存在
10102签名不合法
10105用户访问令牌失效
10106用户访问组织令牌受限
100005字段值重复
100006选项数量已达上限
100007附件数量已达上限
430013应用未找到工作表
430014工作表字段权限不足
430017应用附件上传量不足
430018草稿箱记录数量已达上限
430019必填字段值为空
430020子表数据错误
430021数据不满足业务规则
430022工作表不存在
90000请求次数超出限制
99999数据操作异常

OAuth 相关错误码

分类error_codeerror_msg说明
Token 与授权状态类600100access token 无效或已过期token 不存在、过期、签名非法
Token 与授权状态类600101授权已失效，请重新授权授权被终止，或 scope 变更后未重新授权
Token 与授权状态类600102refresh token 无效或已失效refresh token 已失效、被吊销、不可再使用
Token 与授权状态类600103refresh token 不可再换取新 token授权已终止或应用状态不可用
Token 与授权状态类600104授权不存在使用了不存在的授权关系
应用状态相关600300集成应用已被停用应用处于 Disable 状态
应用状态相关600302集成应用不可用泛化兜底，表示应用状态异常
Scope / 权限相关600311请求的权限范围非法请求了未配置或不存在的 scope
Scope / 权限相关600312权限已变更，请重新授权应用 scope 发生变化
用户权限不足600320当前用户无权限执行该操作Token 具备接口能力，但当前用户无权操作该资源。例如用户不在该组织、项目或空间中，用户角色不允许该操作，或数据行、字段级权限不足
授权流程相关600000授权请求参数错误authorize / token 请求参数不合法
授权流程相关600001redirect_uri 不匹配回调地址与配置不一致
授权流程相关600002授权码无效或已使用code 不存在、过期或已消费
授权流程相关600003授权请求已被取消用户在授权页取消授权
授权流程相关600004授权状态校验失败state 校验失败
应用凭证相关600112凭证无效client_id 或 client_secret 错误
应用凭证相关600113client IP 不在白名单命中 IP 白名单限制

這篇文件對你有幫助嗎？