Question

本篇目录

• 一、配置
• 二、签名机制
• 三、全局错误码

禅道从9.6版本开始内置了在第三方应用中集成禅道的功能，可以方便的将禅道的数据和第三方应用打通。第三方应用必须以 GET 方式访问禅道，禅道以 JSON 格式返回数据。下面我们介绍如何配置该功能。

一、配置

用超级管理员用户登录禅道，进入后台 => 二次开发 => 应用，点击【添加应用】按钮新增一个应用，如图：

注意：

1、应用名称、应用代号、密钥是必填项，代号只能为字母或数字的组合，密钥由系统自动生成。

2、IP 和描述为选填项。此处的 IP 是一个白名单，默认没有限制所有 IP 都可以访问。

3、和别的系统相互调用数据，免密登录必须是关闭状态。

二、签名机制

第三方应用在请求禅道数据的时候需要做签名验证，API 的请求格式为 /api.php?m=moduleName&f=methodName&params=params&code=code&time=timestamp&token=token。

m=moduleName&f=methodName&params=params 部分为数据请求参数，根据实际的需求进行设置。

code为应用代号，需要和禅道应用设置中保持一致。

time位时间戳，可以通过PHP的time函数得到。

token为数字签名，其算法为：code、密钥、time字符串合并，再进行 md5。

以上图设置的应用为例，应用代号为 myApp，密钥为 427c579384224abf9570779d82969d1e，请求id为1的项目详情，其 token 计算过程如下：

$code  = 'myApp';
$key   = '427c579384224abf9570779d82969d1e';
$time  = '1557034496';
$token = md5($code . $key . $time);

算得 token = 020ec7c33a7f1a048743849d15fb218a，请求 API 为 /api.php?m=project&f=view&id=1&code=myApp&time=1557034496&token=020ec7c33a7f1a048743849d15fb218a。

注意：时间戳只能用一次，下次请求的时间戳必须大于该时间戳。

三、全局错误码

300001 缺少 code 参数，检查请求 API 中是否包含 code 参数。
300002 缺少 token 参数，检查请求 API 中是否包含 token 参数。
310001 应用不存在， 检查请求的应用在禅道中是否存在，或是否已被删除。
310002 应用未设置密钥，检查请求的应用在禅道中是否设置密钥。
320001 该IP访问被限制访问，检查请求的应用在禅道中的 IP 设置。
330001 不合法的token参数，检查请求 API 中的 token 是否计算正确。

有时会出现请求内跳转的情况，如请求 index 模块的 index 方法时默认会跳转到 my 模块的 index 方法，这时系统通过 session 来验证跳转后的请求是否合法。
340001 缺少session code，检查跳转后 $_SESSION['ENTRY_CODE'] 是否正确。
340002 session验证失败，检查 session 验证逻辑，检查跳转后 $_SERVER['REMOTE_ADDR'] 是否正确。