开发指南

1. 简介

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

注:

1)v4 版本及以前的接口文档点击这里:点击查阅

2)从 v6 版本开始,开放 API 在保证兼容性的情况下,简道云可能会增加(不会减少)相应的出入参数,请开发者考虑参数增加的情况,保证代码的稳定性。如 v6 版本部门接口的更新,添加了seq的入参以及出参,其实不影响 v5 版本的相关逻辑,后续类似处理不会再增加版本。

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」;一个企业最多生成 500 个 API KEY。

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

开发文档中的 参数说明 是专门根据当前表单的配置生成的,可以点开查看详细的说明。也可在参数说明点击 API 调试台 进行接口的查看和调试。

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

示例如下:

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

5. 代码示例

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

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),对照表如下:

错误码

说明

排查建议

1

The request is invalid.

错误的请求,检查参数是否缺失。

1005

The email already exists.

邮箱已存在,可尝试邮箱验证码登录确认是否已注册。

1010

The member doesn't exist.

用户不存在,检查成员参数是否正确传入。

1017

The username is in an invalid format.

用户名不符合格式要求,常规格式为字母数字下划线任意组合,长度50个字符以内。

1018

The email is in an invalid format.

用户邮箱不符合格式要求,检查邮件地址。

1019

The member's nickname is in an invalid format.

用户昵称不符合格式要求,检查是否长度在80个字符以下且无特殊字符。

1022

The member's current company/team doesn't exist.

用户团队不存在,稍后重试,仍然出现可以咨询 技术支持

1024

The mobile number is invalid. Enter a new number and try again.

手机号码不正确,请重新输入手机号。

1027

The phone number already exists.

手机号码已存在,使用手机号验证码登录确认是否已注册。

1058

Do not have permission to call the task list.

用户操作权限不足。

1065

The member has already been added to the team.

当前用户已加入团队,检查当前团队内是否已经有当前用户。

1082

The phone number/email is required.

手机号和邮箱不能同时为空。

1085

The member's nickname is required.

昵称不能为空。

1087

Duplicate unique fields.

唯一性字段重复,检查成员 ID 的重复情况。

1092

The length of the username has exceeded the limit.

工号长度超出限制,确认工号长度在 50 个字符以内。

1096

The request contains invalid member parameter(s).

用户参数不合法,请检查后重试。

1201

The role doesn't exist.

企业角色信息不存在,检查参数后重试。

1202

Unable to operate synchronized role or role groups

无法操作同步的角色/角色组,确认当前角色/角色组非其他平台同步而来。

1203

The role group/role information is invalid.

角色/角色组信息不合法,检查参数后重试。

1205

The role group is required.

必须指定角色组,检查参数后重试。

1206

The role group doesn't exist.

指定的角色组不存在,检查参数后重试。

1207

The length of the role group name has exceeded the limit.

角色/角色组名称长度超限,确保长度在 24 个字符以内。

1208

Can't delete a role group with member(s).

非空角色组不能删除,确保删除角色组下角色后重试。

2004

The app doesn't exist.

应用不存在,检查参数后重试。

3000

The form doesn't exist.

表单不存在,检查参数后重试。

3001

The member or department name is required.

名称不能为空。

3005

The request contains invalid parameter(s).

参数不正确。

3041

The number of Serial No. fields has exceeded the limit in the form.

单个表单流水号控件数量超出上限,有且只能有一个。

3042

Failed to verify the field alias.

字段别名校验失败,检查别名是否含有特殊字符,常规格式为字母数字下划线任意组合。

3083

The number of widgets has exceeded the limit in the form.

控件数量超过上限,一般情况下这个值为 500。

3091

The number of characters in the form name exceeds 100.

表单名称不能超过 100 个字符。

3092

The number of characters in the title exceeds 100.

标题不能超过 100 个字符。

4000

Failed to submit data.

数据提交失败。

4001

Data doesn‘t exist.

数据不存在。

4007

No approver for the workflow.

操作失败,没有流程处理人。

4008

The workflow was closed.

操作失败,流程已经关闭。

4009

Do not have permission to approve.

操作失败,无权限。

4012

Operation failed. This form is being used in other batch editing tasks. Try again later.

操作失败,当前表单正在执行其他批量编辑任务,请稍后重试。

4015

The approver of the transferred node is invalid.

操作失败,当前节点不存在该候选人。

4016

The workflow can't be transferred to oneself.

操作失败,流程不能转交给自己。

4025

Do not have permission for the workflow.

您没有数据流程权限。

4042

Failed to delete the data.

数据删除失败,检查参数后重试。

4402

Failed to validate the aggregation calculation.

聚合计算校验失败,检查参数后重试。

4815

The filter condition is invalid.

过滤条件设置有误,可能是过滤条件过于冗长导致,可咨询 技术支持

5003

The workflow node doesn't exist.

流程节点不存在。

5004

No comment for approval.

未提交流程审批意见。

5009

The approver of the returned node is invalid.

找不到回退后的负责人。

5011

The target node is invalid.

找不到流转节点。

5012

No signature for approval.

未提交流程手写签名。

5034

This node has child workflow(s)/plugin node(s).

目标节点包含子流程/插件节点。

5044

The child workflow is wrongly configured. For example, no initiator for the child workflow.

子流程配置错误或找不到发起人。

5045

The number of child workflow exceeds 200.

发起子流程数据超过上限 200。

5049

The Transfer feature hasn't been enabled at this node.

当前流程节点未开启转交。

5053

The initial department is invalid. Can't flow to the node with multi-level approval.

流入多级主管审批节点失败,未指定发起部门。

6000

There is a sub-department with the same name within the same-level department.

已存在同名部门,检查同级的父部门下所有子部门,排查同名情况。

6001

The parent department doesn't exist.

父部门不存在。

6002

The department doesn't exist.

部门不存在,检查参数后重试。

6003

Can't delete a department with sub-department(s).

存在子部门,不能删除。

6004

Failed to update the department.

部门修改失败。

6005

Failed to create the department.

部门创建失败,稍后重试,仍然出现可以咨询 技术支持

6006

Can't delete a department with member(s).

部门内存在成员,不能删除。

6010

The department ID is in an invalid format.

部门编号不在合法范围内,结合自身部门路径以及父部门,检查参数后重试。

6011

There is a circular relationship among departments.

部门关系存在循环,不允许的部门树关系,检查参数后重试。

6012

The department name is invalid.

部门名称不合法,检查参数后重试。

6013

The department ID already exists.

部门编号重复,检查同级的父部门下所有子部门,排查编号重复情况。

6014

There must be at least one sub-department belonging to the root department.

至少需要一个子部门属于根部门。

6015

Can't delete a root department.

根部门不能被删除。

6017

The number of cascade levels in the department exceeds the limit.

部门级联层数超出限制,部门树深度限制为 16。

6019

The member list is required.

成员列表不能为空,检查参数后重试。

6020

The number of departments in a single import exceeds the limit.

单次导入部门数量超出限制,上限为 10w。

6021

The number of members in a single import exceeds the limit.

单次导入成员数量超出限制,上限为 2w。

6064

The parent department already exists.

已是目标部门的子部门。

7103

System usage exceeds the limit. The system has been suspended. Go to Management > Plan Details to view the usage details and upgrade plan to restore the system.

系统用量超出限制,系统已暂停使用。您可以至「企业管理-版本信息」查看版本使用详情和升级版本以恢复系统。

7212

Monthly data exceeds the limit. Can't submit new data. Contact the business owner to upgrade the plan.

该账号的本月数据流量已用完,无法提交新数据,请联系账号创建者升级版本。

7216

Attachment upload limit exceeded. Contact the link creator to enable cloud coin payment

附件上传量超过当前版本限制,请联系链接发布者开启云币支付。

7217

Attachment upload limit exceeded. Contact the business owner to enable cloud coin payment.

附件上传量超过当前版本限制,请联系企业创建者开启云币支付。

7218

Attachment upload limit exceeded. Contact the link creator to purchase more cloud coins.

附件上传量超过当前版本限制,请联系链接发布者充值云币。

7219

Attachment upload limit exceeded. Contact the business owner to purchase more cloud coins.

附件上传量超过当前版本限制,请联系企业创建者充值云币。

7221

This form has exceeded the limit and is temporarily suspended. Please contact the company creator or system administrator

API 新增数据超出当前版本限制,请联系企业创建者或系统管理员。

8017

Company/Team doesn't exist or has been closed.

企业不存在或者已经被解散,检查参数后重试。

8301

Failed to verify the API key for authorization.

API 签名校验失败,检查参数后重试。

8302

Do not have permission for the API calls.

没有接口请求权限,检查参数后重试。

8303

The call frequency of the company/team exceeds the frequency limit.

企业 API 请求次数达到频率上限,可等待 1s 后重试,频繁发生可以排查一下企业 API 请求占用情况,或者添加频率限制。

8304

The call frequency exceeds the frequency limit.

当前接口请求次数达到频率上限,可等待 1s 后重试当前接口,频繁发生可以添加频率限制。

9004

Failed to create the task.

队列任务创建失败,稍后重试,仍然出现可以咨询 技术支持

9007

Failed to obtain the lock.

锁获取失败,稍后重试,仍然出现可以咨询 技术支持

17017

The request contains invalid parameter(s).

平台 API 的参数异常,检查参数后重试。

17018

The API key is invalid.

无效的 API Key。

17023

The batch update at one time exceeds the limit.

单次批量修改数量超出限制,上限为 100。

17024

The batch creation at one time exceeds the limit.

单次批量创建数量超出限制,上限为 100。

17025

The transaction_id contains invalid parameter(s).

transaction_id 参数格式不正确。

17026

The transaction_id already exists.

transaction_id 重复,请修改后重试。

17027

Failed to upload the API file.

API文件上传失败,稍后重试,仍然出现可以咨询 技术支持

17032

The field type isn't supported.

不支持的字段类型,检查参数后重试。

17034

The sub-field type isn't supported.

不支持的子表单字段类型,检查参数后重试。

17052

Not included in the IP whitelist.

不在 IP 白名单内,检查对应API Key相关配置。

17053

Not among the authorized apps.

不在应用授权范围内,检查对应API Key相关配置。

17054

Not among the authorized APIs.

不在接口授权范围内,检查对应API Key相关配置。

30002

Unable to retrieve the pre-set CRM form now.

CRM 预设表单暂不支持调用

50000

The target node doesn't exist.

目标节点不存在

50004

The task doesn't exist.

待办任务不存在

50008

Workflow processing error.

流转异常,稍后重试,仍然出现可以咨询 技术支持

50011

The task doesn't exist.

执行实例不存在。

50014

No permission to close the task.

操作人不能为空。

50016

The instance_id is invalid.

流程实例不存在。

50019

The action is not supported.

不支持的审批行为,检查参数后重试。

50021

The data_id is invalid.

关联业务对象不存在。

50031

The data_id is invalid.

流程数据不存在。

50040

This node can't be returned.

当前节点禁止回退,检查节点配置并确认节点未在执行。

50041

Can't return to the current node.

回退节点为当前节点。

50047

Workflow being migrated. Try again later.

流程迁移中,请稍后再试。

50049

Can't return to the Start Node without an initiator.

不允许回退到没有创建者的发起节点。

50051

The workflow has been approved/transferred/returned.

流程已被处理,请刷新后查看。

50053

No approver to add.

加签候选人列表不能为空,检查参数后重试。

50054

Can't add nested approval. For example, after approver A has added approver B, approver B can't add approver C.

不支持嵌套加签,检查参数后重试。

50055

No pre-approver or post-approver was added.

仅支持前后加签任务处理,检查参数后重试。

50056

The parent task is lost. For example, approver A has added approver B. After approver B had approved the assigned task, the initial task for approver A was lost.

加签父任务丢失,可能已经被处理,检查参数后重试。

50057

The Add Approver feature hasn't been enabled.

加签配置未开启。

50059

The member has been added as an approver.

加签候选人不能选择节点负责人。

50060

The approver is invalid.

加签候选人非法。

50061

Can't add more than one approver.

不支持多人加签。。

50062

The added approver is reviewing the task.

待被加签人处理中

50070

Can't return to the plugin node.

不允许回退到插件节点。

50073

Can't return to the in-progress node.

禁止回退到进行中节点。

文档内容是否对您有帮助?
有帮助
没帮助没帮助
如需获取即时帮助,请联系技术支持
咨询
扫码领取100+零代码资料简道云官方微信号400-111-0890
图标在线咨询
立即体验