开发指南

1. 简介

简道云的 API 接口包含以下接口：

应用接口

表单&数据接口

文件接口

流程接口

通讯录接口

注：v4 版本及以前的接口文档点击这里：点击查阅。

2. 规则

API 的统一访问地址为：https://api.jiandaoyun.com/api（非直接访问 URL，结合后文 appid 等一起访问）

所有 API 请求都必须通过 HTTPS 进行身份验证和发起

统一采用 POST 请求的形式

数据传输编码为 UTF-8

文件上传接口为 form_data 格式，其他均为 JSON 格式

3. 频率限制

全局最多接受请求：50 次/秒

各个接口的请求频率限制参见各个接口的接口文档：

应用接口

表单&数据接口

文件接口

流程接口

通讯录接口

4. 鉴权方式

简道云使用基于简单令牌的身份验证，API KEY 默认未生成，需要点击创建 API KEY 去生成。

生成方式：「开放平台>>密钥管理>>创建 API KEY」；一个企业最多生成 2 对 API KEY。

对于已创建的 API KEY 还可以进行启用、停用和删除。

开发文档中的「API 文档」是专门根据当前表单的配置生成的，可以点开查看详细的说明。

查看方式：「开放平台 >> 开发文档 >> API 文档」。

通过 HTTP Headers 设置 Authorization 的值为"Bearer YOUR_APIKEY"来进行安全性验证，

示例如下：

$ curl -i https://jiandaoyun.com/api/v1/callback \
  -H "Authorization: Bearer YOUR_APIKEY"

5. 代码示例

我们为开发者提供了一些不同语言版本的代码样例，仅供参考：

python

java

node

6. 错误对照表

所有 API 使用状态码+错误码的响应方式来表示错误原因。接口正确统一返回HTTP 状态码为 2xx 的正确响应。接口错误则统一返回 HTTP 状态码为 400 的错误响应，同时响应内容会返回错误码（code）和错误信息（msg）

HTTP/1.1 400
Content-Type: application/json
{
  "code": 8303,
  "msg": "超出请求频率限制",
}

6.1 状态码

状态返回码对照表如下：

状态返回码	说明
2xx	响应成功
400	响应失败
502	网关异常
579	文件上传失败

6.2 错误码

当状态返回码为 400 时，服务器会返回具体的错误码（code）和错误信息（msg），对照表如下：

错误码	说明
1010	用户不存在
1017	成员编号格式不合法
1019	成员昵称长度超出限制
1024	手机号码不正确
1085	成员昵称不能为空
1087	唯一性字段重复
1096	请求参数不合法
3001	成员/部门名不能为空
3005	接口参数不正确
4000	数据提交失败
4001	数据不存在
4402	聚合计算校验失败
6000	同级部门下存在同名子部门
6001	父部门不存在
6002	部门不存在
6003	存在子部门的部门不能被删除
6004	部门修改失败
6005	部门创建失败
6006	存在成员的部门不能被删除
6010	部门编号不合法
6011	部门关系存在循环
6012	部门名称格式不合法
6013	部门编号重复
6014	至少需要一个子部门属于根部门
6015	不允许删除根部门
6017	部门级联层数超出限制
6020	单次导入部门数量超出限制
6021	单次导入成员数量超出限制
7103	系统超出用量（数据总量、单表数据量）
8017	企业不存在
8301	签名校验失败
8302	没有接口请求权限
8303	企业API请求次数达到频率上限
8304	当前API请求次数达到频率上限
9007	锁获取失败
17018	无效的 API Key
17025	transaction_id 参数格式不正确
17026	transaction_id 重复，请修改后重试
30002	CRM 预设表单暂不支持调用

1. 简介#

2. 规则#

3. 频率限制#

4. 鉴权方式#

5. 代码示例#

6. 错误对照表#

6.1 状态码#

6.2 错误码#