跳到主要内容

HAP 平台 API 概览

API（Application Programming Interface，应用程序编程接口）是一组预先定义的接口。它使开发者在不接触源码、无需理解内部机制的前提下，按约定格式发起请求并获取数据。

平台目前提供 2 类 API：组织相关接口 与 应用接口。

1、组织相关的接口​

组织授权开放接口涵盖：人员、部门、汇报关系、日志、待办等数据。

在「组织管理 > 集成 > 其他 > 开放接口」查看组织密钥(AppKey、SecretKey)与接口文档。

文档地址为：https://apidoc.nocoly.com

2、应用接口​

文档入口​

应用创建后，会自动创建对应的API接口，应用管理员可查看接口文档，并将文档分享给开发者。

入口：点击应用名称右侧按钮，然后点选「API开发文档」。

应用授权​

根据开发者需要，可以创建多个应用授权，一个授权包含AppKey、Sign、接口权限范围等。

V2和V3​

应用接口有API V2 和 API V3两个版本。

  • API V2： 每个工作表自动生成了直接可用的接口，在请求示例中会自动写入 appKey、Sign、worksheetId 等参数。

  • API V3版本： 在 V2 基础上重构整体 API 路径，参数命名更友好，便于 AI 识别。同时新增更多能力，例如：新增/编辑/删除 工作表 API、工作流 API、工作表数据聚合 API、公共查询 API（查人员、部门）。

    V3版本所有应用的接口一致，可直接参考API V3接口文档: https://www.nocoly.com/apidoc

字段和视图对照表​

在每个工作表下，列出了所有字段和视图信息。

  • 字段对照表包括：字段ID、字段名称、类型、控件类型编号、说明。

  • 视图对照表包括：视图ID、视图名称、类型

接口分享和调试​

在接口文档右上角，可对接口进行调试和分享。

  • API V3接口可直接分享地址：https://apifox.nocoly.com/

  • API V2接口分享

    • 在分享的API接口页面中，所有有关密钥信息不会显示，用到密钥信息的示例中会展示为“YOUR_APP_KEY”、YOUR_SIGN”

    • 分享时可以设置链接有效期和密码访问

筛选条件生成器​

通过可视化配置生成筛选代码。

筛选条件生成器入口：应用开发文档 > 应用授权 > 工作表 > 目标工作表 > 字段对照表 > 筛选条件生成器

API调用限流与限制​

  • API调用限制

    目前仅按同一IP限制调用频率，不按应用或用户维度限流。超过调用频率或请求体大小限制的请求将被拒绝。

    接口单个IP的QPS（每秒请求数）请求体大小限制
    新建行记录（addRow）5016MB
    批量新增行记录（addRows）5016MB
    编辑行记录（editRow）5016MB
    批量编辑行记录（editRows）5016MB
    删除行记录（deleteRow）5016MB
    获取记录数量（getFilterRowsTotalNum）50/
    获取记录列表（getFilterRows）50/
    其他接口不限制/
    私有部署不限制25MB
    ⚠️⚠️⚠️

    1.同一个IP超过调用频率限制，API网关层返回HTTP状态码 503：同时返回结构：{"error_code":90001,"success":false,"error_msg":"调用接口超出限制"}.

    如果遇到这个错误，可以考虑以下方法：

    • 为了业务健壮性，加入针对此类错误码的处理，可以加入重试机制
    • 可以在请求里面加入时间间隔，特别是循环请求体里面，如Sleep(200ms)

    2.超过请求体大小的限制，将直接拒绝服务，API网关层返回HTTP状态码 413：Request Entity Too Large.

    如果您需要处理更大的数据负载，可以考虑以下方法：

    • 数据拆分：​将大的数据集拆分成多个较小的部分，分别发送
    • 优化数据结构：​移除不必要的字段，压缩数据结构，以减少请求体的大小

错误码​

代码说明
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数据操作异常