Skip to content

工作表 API 文档 ​

本文档基于明道云(HAP)应用开放接口文档 (v3-beta),提供了完整的工作表 API 使用说明。

概述 ​

应用开放接口文档提供了一个简单的方法来实现应用数据和任何外部数据的集成。API 严格遵循 REST 语义,使用 JSON 编码对象,并依赖标准 HTTP 代码来指示操作结果。

请求格式 ​

  • 对于 GET 请求,所有参数通过拼接在 URL 之后传递
  • 对于 POST / PUT / PATCH / DELETE 请求,请求的主体必须是 JSON 格式,而且 HTTP header 的 Content-Type 需要设置为 application/json

响应格式 ​

  • 所有响应的 HTTP 状态码都是 200
  • 响应的 Content-Type 为 application/json
  • 响应的 body 是 JSON 格式

字段类型对照表 ​

TypeCode描述允许API创建允许API查询
Text2文本✓✓
PhoneNumber3手机-✓
LandlinePhone4座机-✓
Email5邮箱-✓
Number6数值✓✓
Certificate7证件-✓
Currency8金额-✓
SingleSelect9单选✓✓
MultipleSelect10多选✓✓
Dropdown11下拉-✓
Attachment14附件✓✓
Date15日期✓✓
DateTime16时间✓✓
Region19/23/24地区-✓
DynamicLink21自由链接-✓
Divider22分段--
AmountInWords25大写金额-✓
Collaborator26成员✓✓
Department27部门-✓
Rating28等级-✓
Relation29关联记录✓✓
Lookup30他表字段-✓
Formula31公式-✓
Concatenate32文本拼接-✓
AutoNumber33自动编号-✓
SubTable34子表-✓
CascadingSelect35级联选择-✓
Checkbox36检查框-✓
Rollup37汇总-✓
DateFormula38公式(日期)-✓
CodeScan39扫码-✓
Location40定位-✓
RichText41富文本-✓
Signature42签名-✓
OCR43文字识别-✓
Role44角色-✓
Embed45嵌入--
Time46时间✓✓
Barcode47条码-✓
OrgRole48组织角色-✓
Button49API查询(按钮)--
APIQuery50API查询(下拉)--
QueryRecord51查询记录--
Section52标签页--
FunctionFormula53函数公式-✓

筛选器使用指南 ​

筛选器结构 ​

基本语法:

json
Filter = {
  type: 'group' | 'condition';
  // 当 type 为 'group' 时的字段
  logic?: 'AND' | 'OR';
  children?: Filter[]; // 只能全是group或全是condition,不能混合使用。最多只能使用两层children
  // 当 type 为 'condition' 时的字段
  field?: string; // 字段ID或别名
  operator?: FilterOperator; // 运算符
  value?: any; // 值(字符串、数值、数组)
}

支持的运算符 ​

比较运算符 ​

运算符描述示例值
eq等于"Beijing" 或 ["<targetid>"]
ne不等于"London" 或 ["<targetid>"]
gt大于20 或 "2025-02-06 00:00:00"
ge大于等于10
lt小于20
le小于等于100
in是其中一个["value1", "value2"]
notin不是任意一个["value1", "value2"]
contains包含"Ch" 或 ["销售部", "市场部"]
notcontains不包含"Ch" 或 ["销售部", "市场部"]
concurrent同时包含["<id1>", "<id2>"]
belongsto属于["<departmentid>"]
notbelongsto不属于["<departmentid>"]
startswith开头是"张"
notstartswith开头不是"李"
endswith结尾是"公司"
notendswith结尾不是"有限公司"
between在范围内["2025-01-01", "2025-01-31"]
notbetween不在范围内["10", "20"]

为空运算符 ​

运算符描述备注
isempty为空不需要 value 字段
isnotempty不为空不需要 value 字段

使用示例 ​

示例 1: 筛选条件 ​

查询所有1月份入职的姓"张"的职员:

json
{
  "type": "group",
  "logic": "AND",
  "children": [
    {
      "type": "condition",
      "field": "name",
      "operator": "startswith",
      "value": "张"
    },
    {
      "type": "condition",
      "field": "onboard_date",
      "operator": "between",
      "value": ["2025-01-01", "2025-01-31"]
    }
  ]
}

注意事项 ​

  • 嵌套限制: 最多支持两层嵌套(group -> group -> condition)
  • children 类型一致性: 一个group的children只能全是group或全是condition,不能混合
  • logic 必需: 当type为group时,logic字段必须指定为AND或OR
  • 为空运算符: 使用isempty和isnotempty时不需要提供value字段
  • 数组值: 某些运算符需要数组形式的值(如between、in、contains、concurrent、belongsto等)
  • 选项型字段: 所有的选项型字段(单选、多选)需要把对应option的key值放到数组中作为value,使用数组值运算符
  • 关联记录: 关联的记录的筛选需要先查询到对应的record_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数据操作异常

应用接口 ​

获取应用信息 ​

获取应用信息,包含应用下分组、工作表、自定义页面信息

请求

http
GET /v3/app

请求头

text
Appkey: {appkey}
Sign: {签名}

响应示例

json
{
  "success": true,
  "error_code": 0,
  "error_msg": "",
  "data": {
    "organizationId": "28447959-cf7f-4ae9-XXXXXXXXXXXXXXX",
    "appId": "b55d6ceb-b69a-44f0-a011-XXXXXXXXXXXXXXX",
    "name": "客户关系管理",
    "iconUrl": "https://fp1.example.cn/customIcon/sys_13_1_shop.svg",
    "color": "#3054EB",
    "desc": "",
    "sections": [
      {
        "id": "676910ae3e6f2583f5d3edd5",
        "name": "驾驶舱",
        "items": [],
        "childSections": []
      }
    ]
  }
}

工作表接口 ​

获取工作表列表 ​

获取应用下的所有工作表或者指定的工作表列表

请求

http
POST /v3/app/worksheets/list

请求头

text
HAP-Appkey: {HAP应用密钥}
HAP-Sign: {HAP签名}

请求体

json
{
  "responseFormat": "json",
  "worksheets": ["string"]
}

响应示例

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

新建工作表 ​

创建工作表,目前支持字段类型有Text|Number|SingleSelect|MultipleSelect|Date|DateTime|Collaborator|Relation|Attachment

请求

http
POST /v3/app/worksheets

请求头

text
HAP-Appkey: {appkey}
HAP-Sign: {签名}

请求体

json
{
  "name": "测试新建工作表",
  "sectionId": "",
  "fields": [
    {
      "name": "文本",
      "alias": "",
      "type": "2",
      "required": true,
      "isTitle": true
    },
    {
      "name": "数值",
      "alias": "",
      "type": "6",
      "precision": 2,
      "required": true
    },
    {
      "name": "单选",
      "alias": "",
      "type": "11",
      "options": [
        {
          "value": "选项名称1",
          "index": 1
        },
        {
          "value": "选项名称2",
          "index": 2
        }
      ],
      "required": true
    }
  ]
}

响应示例

json
{
  "data": {
    "worksheetId": "worksheet123"
  },
  "success": true
}

获取工作表结构信息 ​

获取工作表配置及其字段信息

请求

http
GET /v3/app/worksheets/{worksheet_id}?responseFormat=json

请求头

text
HAP-Appkey: {appkey}
HAP-Sign: {签名}

响应示例

json
{
  "data": {
    "worksheetId": "65dda1a5a608a40050774c72",
    "name": "会员信息",
    "alias": "",
    "desc": "",
    "remark": "",
    "fields": [
      {
        "id": "632444f6182c34e9180b0676",
        "name": "名称",
        "alias": "",
        "desc": "",
        "type": "2",
        "required": false,
        "isHidden": false,
        "isReadOnly": false,
        "isHiddenOnCreate": false,
        "isUnique": false,
        "isTitle": true,
        "remark": ""
      }
    ],
    "views": [
      {
        "id": "65dda1a5a608a40050774c8f",
        "name": "全部",
        "type": "0"
      }
    ]
  },
  "success": true
}

编辑工作表 ​

编辑工作表结构,包括新增、编辑、删除字段

请求

http
POST /v3/app/worksheets/{worksheet_id}

请求头

text
HAP-Appkey: {HAP应用密钥}
HAP-Sign: {HAP签名}

请求体

json
{
  "name": "string",
  "alias": "string",
  "remark": "string",
  "sectionId": "string",
  "addFields": [
    {
      "name": "string",
      "type": 0,
      "alias": "string",
      "remark": "string",
      "desc": "string",
      "required": false,
      "isTitle": false,
      "isHidden": false,
      "isReadOnly": false,
      "isHiddenOnCreate": false,
      "isUnique": false,
      "precision": 14,
      "subType": "string",
      "options": [
        {
          "value": "string",
          "index": 0
        }
      ],
      "relation": {
        "showFields": ["string"],
        "bidirectional": true
      },
      "max": 10,
      "dataSource": "string",
      "sourceField": "string"
    }
  ],
  "editFields": [
    {
      "id": "string",
      "name": "string",
      "type": 0,
      "alias": "string",
      "remark": "string",
      "desc": "string",
      "required": false,
      "isTitle": false,
      "isHidden": false,
      "isReadOnly": false,
      "isHiddenOnCreate": false,
      "isUnique": false,
      "precision": 14,
      "subType": "string",
      "options": [
        {
          "value": "string",
          "index": 0
        }
      ],
      "relation": {
        "showFields": ["string"]
      },
      "max": 10,
      "dataSource": "string",
      "sourceField": "string"
    }
  ],
  "removeFields": ["string"]
}

删除工作表 ​

删除工作表

请求

http
DELETE /v3/app/worksheets/{worksheet_id}

请求头

text
HAP-Appkey: {HAP应用密钥}
HAP-Sign: {HAP签名}

工作表行记录接口 ​

新建行记录 ​

新建行记录

请求

http
POST /v3/app/worksheets/{worksheet_id}/rows

请求头

text
HAP-Appkey: {appkey}
HAP-Sign: {签名}

请求体

json
{
  "triggerWorkflow": true,
  "fields": [
    {
      "id": "6847f2a1e66b4b2aa67b1467",
      "value": "HHHH"
    }
  ]
}

响应示例

json
{
  "data": {
    "id": "67890abcdef"
  },
  "success": true
}

获取行记录列表 ​

获取工作表记录列表,包含记录创建者、拥有者信息,各字段对应的值

请求

http
POST /v3/app/worksheets/{worksheet_id}/rows/list

请求头

text
HAP-Appkey: {appkey}
HAP-Sign: {签名}

请求体

json
{
  "pageSize": 20,
  "pageIndex": 1,
  "viewId": "view_123",
  "fields": ["field1", "field2"],
  "filter": {
    "type": "group",
    "logic": "OR",
    "children": [
      {
        "type": "group",
        "logic": "AND",
        "children": [
          {
            "type": "condition",
            "field": "name",
            "operator": "startswith",
            "value": "张"
          }
        ]
      }
    ]
  },
  "sorts": [
    {
      "field": "createdAt",
      "direction": "desc"
    }
  ]
}

响应示例

json
{
  "data": {
    "rows": [
      {
        "id": "row123",
        "_createdBy": {
          "accountId": "user123",
          "fullname": "张三"
        },
        "_owner": {
          "accountId": "user123",
          "fullname": "张三"
        },
        "_createdAt": "2024-03-25 15:52:58",
        "_updatedAt": "2024-03-25 15:52:58",
        "_updatedBy": {
          "accountId": "user123",
          "fullname": "张三"
        }
      }
    ],
    "total": 100,
    "pageIndex": 1,
    "pageSize": 20
  },
  "success": true
}

批量新增行记录 ​

批量新建行记录

请求

http
POST /v3/app/worksheets/{worksheet_id}/rows/batch

请求头

text
HAP-Appkey: {appkey}
HAP-Sign: {签名}

请求体

json
{
  "rows": [
    {
      "fields": [
        {
          "id": "field1",
          "value": "值1"
        },
        {
          "id": "field2",
          "value": "值2"
        }
      ]
    },
    {
      "fields": [
        {
          "id": "field1",
          "value": "值3"
        },
        {
          "id": "field2",
          "value": "值4"
        }
      ]
    }
  ],
  "triggerWorkflow": true
}

响应示例

json
{
  "data": {
    "rowIds": ["row1", "row2"]
  },
  "success": true
}

批量更新行记录详情 ​

批量更新行记录

请求

http
PATCH /v3/app/worksheets/{worksheet_id}/rows/batch

请求头

text
HAP-Appkey: {appkey}
HAP-Sign: {签名}

请求体

json
{
  "rowIds": ["row1", "row2"],
  "fields": [
    {
      "id": "field1",
      "value": "新值1"
    },
    {
      "id": "field2",
      "value": "新值2"
    }
  ],
  "triggerWorkflow": true
}

响应示例

json
{
  "data": {
    "failedRowIds": [],
    "successfulRowIds": ["row1", "row2"]
  },
  "success": true
}

批量删除行记录 ​

批量删除行记录

请求

http
DELETE /v3/app/worksheets/{worksheet_id}/rows/batch

请求头

text
HAP-Appkey: {appkey}
HAP-Sign: {签名}

请求体

json
{
  "rowIds": ["row1", "row2", "row3"],
  "triggerWorkflow": true,
  "permanent": false
}

获取行记录详情 ​

获取记录详情信息,包括创建者、拥有者、字段信息、根据字段数据类型生成示例值

请求

http
GET /v3/app/worksheets/{worksheet_id}/rows/{row_id}?includeSystemFields=false

请求头

text
HAP-Appkey: {appkey}
HAP-Sign: {签名}

响应示例

json
{
  "data": {
    "id": "67890abcdef12345",
    "6847f2a1e66b4b2aa67b1467": "示例值",
    "_createdAt": "2024-03-25 15:52:58",
    "_createdBy": {
      "accountId": "user123",
      "fullname": "张三",
      "avatar": "https://example.com/avatar.jpg",
      "status": "1"
    },
    "_updatedAt": "2024-03-25 15:52:58",
    "_updatedBy": {
      "accountId": "user123",
      "fullname": "张三",
      "avatar": "https://example.com/avatar.jpg",
      "status": "1"
    },
    "_owner": {
      "accountId": "user123",
      "fullname": "张三",
      "avatar": "https://example.com/avatar.jpg",
      "status": "1"
    }
  },
  "success": true
}

更新行记录 ​

更新行记录

请求

http
PATCH /v3/app/worksheets/{worksheet_id}/rows/{row_id}

请求头

text
HAP-Appkey: {appkey}
HAP-Sign: {签名}

请求体

json
{
  "fields": [
    {
      "id": "6847f2a1e66b4b2aa67b1467",
      "value": "更新后的值"
    }
  ],
  "triggerWorkflow": true
}

响应示例

json
{
  "success": true,
  "data": {
    "id": "89d4fd5b-91d8-4b0d-babc-263cefed16c7"
  }
}

删除行记录 ​

删除行记录

请求

http
DELETE /v3/app/worksheets/{worksheet_id}/rows/{row_id}

请求头

text
HAP-Appkey: {appkey}
HAP-Sign: {签名}

请求体

json
{
  "triggerWorkflow": false,
  "permanent": true
}

工作流接口 ​

获取流程列表 ​

获取应用下工作流列表

请求

http
GET /v3/app/workflow/processes

请求头

text
HAP-Appkey: {appkey}
HAP-Sign: {签名}

响应示例

json
{
  "data": {
    "processes": [
      {
        "id": "681b8934ec9191462c08417a",
        "name": "新增线索",
        "alias": "",
        "type": 10,
        "description": "新增线索流程",
        "status": 0,
        "_createdAt": "2025-02-17 17:53:44",
        "_updatedAt": "2025-06-17 17:53:44",
        "_owner": {
          "accountId": "e2453de8-1a6a-4d4f-ba36-87fdff880a20",
          "fullname": "卜佳菲",
          "avatar": "https://p1.example.cn/UserAvatar/fe9c4374-68f1-4f64-88ea-47050dff28bd.jpg?imageView2/1/w/100/h/100/q/90",
          "status": "1"
        }
      }
    ]
  },
  "success": true
}

获取流程详情 ​

获取流程详情,包含流程请求参数,响应参数

请求

http
GET /v3/app/workflow/processes/{process_id}

请求头

text
HAP-Appkey: {appkey}
HAP-Sign: {签名}

响应示例

json
{
  "data": {
    "id": "681b8934ec9191462c08417a",
    "name": "新增线索",
    "description": "新增线索的描述",
    "inputParameters": [
      {
        "field": "681b8190ec9191462c08283b",
        "fieldname": "名称",
        "alias": "",
        "description": "",
        "type": 2,
        "required": false
      },
      {
        "field": "681b8190ec9191462c08111",
        "fieldname": "渠道",
        "description": "",
        "alias": "",
        "type": 9,
        "options": [
          {
            "key": "option1",
            "value": "选项1"
          }
        ],
        "required": false
      }
    ],
    "outputParameters": [
      {
        "field": "681b8190ec9191462c082222",
        "fieldname": "id",
        "alias": "",
        "description": "",
        "type": 2
      }
    ]
  },
  "success": true
}

触发流程 ​

触发流程

请求

http
POST /v3/app/workflow/hooks/{process_id}

请求头

text
HAP-Appkey: {appkey}
HAP-Sign: {签名}

请求体

json
{
  "text_field": "日报",
  "number_field": 100,
  "checkbox_field": 1,
  "datetime_field": "2025-07-16 15:20",
  "radio_field": "选项B",
  "array_field": ["item1", "item2"],
  "object_array_field": [
    {
      "key": "A",
      "value": 1
    },
    {
      "key": "B",
      "value": 2
    }
  ],
  "user_field": ["user_001"],
  "department_field": ["dept_001"],
  "role_field": ["role_leader"],
  "file_field": ["https://example.com/input/file1.pdf"]
}

响应示例

json
{
  "data": {},
  "success": true
}

选项集接口 ​

获取选项集列表 ​

获取应用下选项集列表

请求

http
GET /v3/app/optionsets

请求头

text
HAP-Appkey: {appkey}
HAP-Sign: {签名}

响应示例

json
{
  "data": {
    "optionsets": [
      {
        "id": "optionset123",
        "name": "状态选项集",
        "accountId": "account123",
        "worksheetIds": ["worksheet123", "worksheet456"],
        "options": [
          {
            "key": "key1",
            "value": "进行中",
            "index": 1,
            "isDeleted": false,
            "color": "#2196F3",
            "score": 50
          },
          {
            "key": "key2",
            "value": "已完成",
            "index": 2,
            "isDeleted": false,
            "color": "#4CAF50",
            "score": 100
          }
        ],
        "enableColor": true,
        "enableScore": true
      }
    ]
  },
  "success": true
}

创建选项集 ​

创建选项集信息 数据包括:选项集名称、选项集信息(选项值、排序、颜色、分值)

请求

http
POST /v3/app/optionsets

请求头

text
HAP-Appkey: {appkey}
HAP-Sign: {签名}

请求体

json
{
  "name": "状态选项集",
  "options": [
    {
      "value": "进行中",
      "index": 1,
      "color": "#2196F3",
      "score": 50
    },
    {
      "value": "已完成",
      "index": 2,
      "color": "#4CAF50",
      "score": 100
    }
  ],
  "enableColor": true,
  "enableScore": true
}

响应示例

json
{
  "data": {
    "optionsetId": "option_set_123"
  },
  "success": true
}

编辑选项集 ​

编辑选项集

请求

http
POST /v3/app/optionsets/{optionset_id}

请求头

text
HAP-Appkey: {appkey}
HAP-Sign: {签名}

请求体

json
{
  "name": "更新后的选项集",
  "options": [
    {
      "key": "key1",
      "value": "更新选项1",
      "index": 1,
      "isDeleted": false,
      "color": "#FF5722",
      "score": 60
    }
  ],
  "enableColor": true,
  "enableScore": true
}

删除选项集 ​

删除选项集

请求

http
DELETE /v3/app/optionsets/{optionset_id}

请求头

text
HAP-Appkey: {appkey}
HAP-Sign: {签名}

角色接口 ​

获取角色列表 ​

获取应用下角色列表

请求

http
GET /v3/app/roles

请求头

text
HAP-Appkey: {appkey}
HAP-Sign: {签名}

创建角色 ​

创建角色 信息包含:角色名称、描述、权限信息

请求

http
POST /v3/app/roles

请求头

text
HAP-Appkey: {appkey}
HAP-Sign: {签名}

请求体

json
{
  "name": "新角色",
  "description": "角色描述",
  "permissionScope": 100,
  "type": 0,
  "hideAppForMembers": true,
  "globalPermissions": {
    "addRecord": true,
    "share": true,
    "import": true,
    "export": true,
    "discuss": true,
    "systemPrint": true,
    "attachmentDownload": true,
    "log": true
  }
}

获取角色详情 ​

获取角色详情

请求

http
GET /v3/app/roles/{role_id}

请求头

text
HAP-Appkey: {appkey}
HAP-Sign: {签名}

删除角色 ​

删除角色

请求

http
DELETE /v3/app/roles/{role_id}

请求头

text
HAP-Appkey: {appkey}
HAP-Sign: {签名}

公共查询接口 ​

查找成员 ​

根据输入的人员名称匹配用户,返回用户 ID、姓名、已脱敏的手机号和邮箱。

请求

http
GET /v3/users/lookup?name={人员名称}

请求头

text
HAP-Appkey: {appkey}
HAP-Sign: {签名}

响应示例

json
{
  "data": {
    "users": [
      {
        "accountId": "user_001",
        "name": "Alice",
        "mobile": "138****5678",
        "email": "ali****@mail.com",
        "departments": [
          {
            "id": "dept_001",
            "name": "销售部",
            "path": "公司/销售部",
            "pathNodes": []
          }
        ]
      }
    ]
  },
  "success": true
}

查找部门 ​

根据输入的部门名称匹配部门,返回部门 ID 和名称。

请求

http
GET /v3/departments/lookup?name={部门名称}

请求头

text
HAP-Appkey: {appkey}
HAP-Sign: {签名}

响应示例

json
{
  "data": {
    "departments": [
      {
        "id": "7fb381a3-d559-4b0c-a8fd-e1e8a6272442",
        "name": "销售一部",
        "path": "华东大区/上海分公司/销售部",
        "pathNodes": []
      }
    ]
  },
  "success": true
}

获取地区信息 ​

获取地区信息,支持按ID查询或模糊搜索

请求

http
GET /v3/regions?id={地区ID}&search={搜索内容}

请求头

text
HAP-Appkey: {appkey}
HAP-Sign: {签名}

响应示例

json
{
  "data": {
    "regions": [
      {
        "id": "110000",
        "name": "北京市",
        "path": "北京市",
        "last": false
      },
      {
        "id": "120000",
        "name": "天津市",
        "path": "天津市",
        "last": false
      }
    ]
  },
  "success": true
}

注意事项 ​

  1. 认证方式: 所有请求都需要在请求头中包含 Appkey 和 Sign 进行签名认证
  2. 字段值格式:
    • 附件类型字段:[{"name":"文件名称,带后缀","url":"url/base64"}]
    • 关联记录类型:多条记录rowId用逗号(,)分割
    • 日期类型:格式为 2018-8-8 或 2018-8-8 12:00:00
  3. 工作流触发: 默认情况下,创建、更新、删除记录会触发工作流,可通过 triggerWorkflow 参数控制
  4. 分页查询: 列表查询接口支持分页,pageSize 最大为 1000,pageIndex 从 1 开始
  5. 筛选器: 筛选器最多支持两层嵌套,children 类型必须一致

维护负责人:技术部
最后更新:2025-01-19
文档来源:明道云(HAP)应用开放接口文档 v3-beta

衣星科技知识库 © 2025