uTools Server API

通过 uTools 的服务端 API,可以将你的应用和 uTools 用户关联,实现帐号互通、接收支付通知、查询用户支付记录等,为保护密钥安全,请仅在服务端调用接口。

获取用户基础信息接口

此接口用于获取 uTools 用户的基础信息、验证用户真实性,与第三方系统进行帐号打通,实现系统间免登录跳转等。

1.1 接口说明

调用地址https://open.u-tools.cn/baseinfo

请求方式get

HeaderAccept:application/json 请求头中须添加此项,否则请求将失败

请求参数

参数名是否必填说明
plugin_id插件 ID
access_tokenuTools 用户的 access_token
timestamp时间戳(秒),误差需小于 10 分钟
sign签名

1.2 获取当前用户临时 access_token

在 uTools 客户端中调用:

// 获取用户服务端临时令牌,2 小时内有效
utools.fetchUserServerTemporaryToken().then((res) => {
	const access_token = res.token;
});
1
2
3
4

1.3 签名方法

  1. 对请求参数按参数名升序排序

  2. 对参数内容进行 url_encode 编码后,组合成 URL 参数形式的字符串,如:access_token=aaaaaaa&plugin_id=ccccc&timestamp=1624329435

  3. 使用 HMAC 方法对字符串生成带有密钥的哈希值,得到签名

// 以下为 php 代码演示签名过程
// 参数
$params = [
  "plugin_id" => "zueadppw", // 可在开发者插件中获得
  "access_token" => "user access_token 32位",
  "timestamp" => "1624329435",
];


// 1. 按照键名对数组进行升序排序
ksort($params);

// 2. 生成 URL-encode 之后的请求字符串
$str = http_build_query($params);

// 3. 使用 HMAC 方法生成带有密钥的哈希值
$secret = "your secret 32位"; // secret 在开发者插件中通过重置获取
$sign = hash_hmac("sha256", $str, $secret);
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

1.4 返回值

若调用成功(http 状态码 200),将返回如下信息:

{
    "resource": {
        "avatar": "https://res.u-tools.cn/assets/avatars/eZCBIawAkspLw8Xg.png",
        "member": 1, // 是否 uTools 会员(0: 否,1: 是)
        "nickname": "却步.",
        "open_id": "00a50cd81c37c4e381e8161b2d762158", // uTools 用户 ID, 对于此插件不变且唯一
        "timestamp": 1624329616,
    },
    "sign": "4dbf21a9d5a0f0e3906a0180522fd6393b4e91f738d57cafddf309afc6c547bb" // 签名算法与 1.3 相同
}
1
2
3
4
5
6
7
8
9
10

若调用失败,将返回如下信息:

{
    "message": "The given data was invalid.", // message 字段始终存在
    "errors": { // 可能没有详细错误信息
        "access_token": [
            "access token 必须是 32 个字符。"
        ]
    }
}
1
2
3
4
5
6
7
8

HTTP 状态码说明

http 状态码说明
200成功返回
400客户端错误
401未知用户(sign 错误,access_token 错误等)
403无权限访问(access_token 过期)
404未找到用户(不存在此用户或违反 uTools 相关协议被禁用)
422请求的参数未通过验证
500uTools 暂时无法提供服务

用户支付成功回调接口

当用户通过 uTools 在你的插件内完成支付,且在开发者工具中配置了回调地址,在收到付款时,会将信息推送到配置的回调地址。

2.1 接口说明

请求方式post

HeadercontentType: application/json

请求参数


{
    "resource": {
        "attach": "", // 附加数据
        "body": "会员1年", // 支付内容
        "created_at": "2021-06-18 16:42:16", // 订单生成时间
        "goods_id": "6n193s7P95p9gA13786YkwQ5oxHpVW4f", // 商品ID
        "open_id": "a331127d654761ac91d086b942aae7b6", // uTools 用户 ID
        "order_id": "KMFSOZt5cMe5A0ClkdCAAyPasyXZJzP6", // uTools 订单号
        "out_order_id": "123456", // 外部订单号
        "paid_at": "2021-06-18 16:42:36", // 用户支付时间
        "pay_fee": 1, // 支付金额(分)
        "plugin_id": "FFFFFFFF", 
        "status": 10, // 是否支付(0: 未支付,10: 已支付)
        "timestamp": 1624346603 // 请求发送时间戳
    },
    "sign": "53e8ab69b940483abd04427fdaf2de9b5294509943df5393b7bf1913af9055fa"
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

2.2 注意事项

  1. 当处理完成后,请返回字符串 SUCCESS
  2. 如果返回值为其他,uTools 会延时后再次通知,最多通知 5 次,时间间隔 [15, 30, 60, 300, 600] 秒。
  3. 通知最长等待 10 秒。
  4. 避免消息伪造,请务必验证 sign,签名方式与获取用户基础信息接口 1.3 一致

支付订单查询接口

此接口用于主动查询订单支付状态。

3.1 接口说明

调用地址: https://open.u-tools.cn/payments/record

请求方式: get

Header: Accept:application/json 请求头中须添加此项,否则请求将失败

请求参数:

参数名是否必填说明
plugin_id插件ID
out_order_id第三方订单号
timestamp时间戳(秒),误差需小于 10 分钟
sign签名,与 1.3 签名方法一致

3.2 返回值

若调用成功(http 状态码 200),将返回如下信息:

{
    "resource": {
        "attach": "", // 附加数据
        "body": "会员1年", // 支付内容
        "created_at": "2021-06-18 16:42:16", // 订单生成时间
        "goods_id": "6n193s7P95p9gA13786YkwQ5oxHpVW4f", // 商品ID
        "open_id": "a331127d654761ac91d086b942aae7b6", // uTools 用户 ID
        "order_id": "KMFSOZt5cMe5A0ClkdCAAyPasyXZJzP6", // uTools 订单号
        "out_order_id": "123456", // 外部订单号
        "paid_at": "", // 用户支付时间
        "pay_fee": 1, // 支付金额(分)
        "plugin_id": "FFFFFFFF", 
        "status": 0, // 是否支付(0: 未支付,10: 已支付)
        "timestamp": 1624346603 // 请求发送时间戳
    },
    "sign": "dbb3d05f6e794ca3b2bc2fa7ef45c3f7cd6a3b20c601b37317863b67998d535e"
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

HTTP 状态码说明

http 状态码说明
200成功返回
400客户端错误
401未知用户(sign 错误)
403无权限访问(timestamp 已过期)
404未找到插件
422请求的参数未通过验证
500uTools 暂时无法提供服务

创建商品接口

此接口用于动态创建商品,主要解决不固定金额商品问题,一般为一次性使用,通过此 API 创建的商品不会出现在开发者工具的商品列表中。

3.1 接口说明

调用地址: https://open.u-tools.cn/goods

请求方式: post

Header: Accept:application/json 请求头中须添加此项,否则请求将失败

请求参数:

参数名是否必填说明
plugin_id插件ID
total_fee商品总金额(分)
title商品名称
timestamp时间戳(秒),误差需小于 10 分钟
sign签名,与 1.3 签名方法一致

3.2 返回值

若调用成功(http 状态码 200),将返回如下信息:

{
    "message": "ZyxrbSpWBH360pSWG0ueYI3rKSWXMcic"
}
1
2
3

返回内容为goods_id,可在 openPayment 中使用

HTTP 状态码说明

http 状态码说明
200成功返回
400客户端错误
401未知用户(sign 错误)
403无权限访问(timestamp 已过期)
404未找到插件
422请求的参数未通过验证
500uTools 暂时无法提供服务