meta:
- name: 土豆API文档 content: 土豆API文档
- name: keywords content: 土豆API文档
# 请仔细阅读
- 请严格按照接口文档开发,有问题请联系工作人员,或下载实例查看学习代码,接口支持base64加密,AEC加密,DES加密,AES加密,RC4加密,接口验签,IP限制等..在登录土豆API后APP设置里面均可配置,严禁用于非法用途,违规者将给予封号惩罚,一切解释权归
土豆API
所有
# 接口验证方式
- 接口支持post,get方式请求(未标注是哪个接口表示都可以),任何接口请求必须携带askKey(askKey详见),部分接口需要携带apiUserToken(apiUserToken详见),接口支持form-data,x-www-form-urlencoded,json等格式请求,如果开启加密时,不需要对key进行加密,需要对value进行对应加密,使用加密时,建议不要使用get请求,否则会出现加密后的数据被转码而导致服务端解密失败
# 接口验签
- 接口验签,建议加上,可防止非法抓包破解接口,这是一种验证接口是否客户端请求,非客户端会提示验签失败,签名使用的是北京时间,签名参数放需要在请求头,如果开启验签,响应的签名会放在参数内,土豆API响应内容也会返回验签数据,
客户端可以自行验签
,保证数据安全性
# 验签规则V1
# 规则说明
验签字符串拼接规则:验签秘钥 + 时间戳
,通过MD5算法加密(32位小写)。
- 请求头需携带:
time
(当前系统时间戳,毫秒级)、sign
(MD5加密结果)。
# 验签算法sign = MD5(验签秘钥 + 当前系统时间戳(毫秒))
time = 当前系统时间戳(毫秒)
javascript demo
/**
*
* @param {*} signSecretKey 验签秘钥
* @param {*} timestamp 时间戳
* @returns
*/
function signV1(signSecretKey, timestamp) {
return md5(signSecretKey + timestamp)
}
2
3
4
5
6
7
8
9
java demo
/**
* @param time 时间戳
* @param signSecretKey 验签秘钥
* @return
*/
public static String signApiV1Sign(String time,String signSecretKey){
String s = DigestUtils.md5DigestAsHex((signSecretKey+time).getBytes());
return s;
}
2
3
4
5
6
7
8
9
10
lua demo
local md5 = require("md5")
-- 定义函数signApiV1Sign
function signApiV1Sign(time, signSecretKey)
-- 将验签秘钥和时间戳拼接成字符串
local strToHash = signSecretKey.. time
-- 计算MD5并返回十六进制格式的结果
local result = md5.sumhexa(strToHash)
return result
end
2
3
4
5
6
7
8
9
10
# 验签规则V2
# 规则说明
在V1基础上增加请求参数参与签名,通过MD5算法加密(32位小写)。
- 请求头需携带:
time
(时间戳)、sign
(MD5加密结果)。
# 验签步骤
- 过滤参数:移除值为
null
(nil
)、undefined
或空字符串的参数。 - 排序参数:按键名(key)字典升序排序。
- 拼接字符串:
&key1=value1&key2=value2&...&signSecretKey×tamp
(每个参数前加&
)。 - 生成签名:对拼接结果做MD5加密。
sign=md5算法加密后的您的验签字符串+当前系统时间戳(毫秒)
time=当前系统时间戳(毫秒)
// 返回500例子
signSecretKey:1eff25397db71c4af5019e72c31d6737
timestamp:1752131260250
最终拼接参数:&code=500&message=卡密错误&status=false&1eff25397db71c4af5019e72c31d6737&1752131260250
签名:e7f1dded50c64e82d15f98ec33498681
{
"code": "500",
"data": null,
"message": "卡密错误",
"nonce": null,
"pc": null,
"sign": "e7f1dded50c64e82d15f98ec33498681",
"status": false,
"time": "1752131260250"
}
// 返回200例子
signSecretKey:1eff25397db71c4af5019e72c31d6737
timestamp:1752133734750
最终拼接参数:&code=200&data={"verify":true,"remark":null,"type":0,"exTime":"2025-07-11 15:04:07"}&status=true&1eff25397db71c4af5019e72c31d6737&1752133734750
签名:77e2e4b5fb0f156e20a278d4d31bfe7c
{
"code": "200",
"data": {
"verify": true,
"remark": null,
"type": 0,
"exTime": "2025-07-11 15:04:07"
},
"message": "",
"nonce": null,
"pc": null,
"sign": "77e2e4b5fb0f156e20a278d4d31bfe7c",
"status": true,
"time": "1752133734750"
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
javascript demo
/**
* 生成V2版本签名
* @param {string} signSecretKey - 验签秘钥
* @param {string} timestamp - 时间戳
* @param {Object} data - 请求数据对象
* @returns {string} - 生成的MD5签名
*/
function signV2(signSecretKey, timestamp, data) {
// 1. 过滤空值参数
var filteredData = {};
for (var key in data) {
if (data.hasOwnProperty(key)) {
var value = data[key];
if (value !== null && value !== undefined && value !== '') {
filteredData[key] = value;
}
}
}
// 2. 获取排序后的键名数组
var sortedKeys = [];
for (var key in filteredData) {
if (filteredData.hasOwnProperty(key)) {
sortedKeys.push(key);
}
}
sortedKeys.sort();
// 3. 拼接参数字符串(每个参数前加&)
var resultSign = '';
for (var i = 0; i < sortedKeys.length; i++) {
var key = sortedKeys[i];
resultSign = resultSign + '&' + key + '=' + filteredData[key];
}
// 4. 添加秘钥和时间戳
resultSign = resultSign + '&' + signSecretKey + '&' + timestamp;
// 5. 计算MD5签名(假设md5函数已全局可用)
return md5(resultSign);
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
java demo
/**
* @param time 时间戳
* @param signSecretKey 验签秘钥
* @param param 数据
* @return
*/
public static String signApiV2Sign(String time, String signSecretKey, Map<String, String> param) {
TreeMap<String, Object> treeMap = new TreeMap<>(param);
StringBuilder sb = new StringBuilder();
for (Map.Entry<String, Object> entry : treeMap.entrySet()) {
Object value = entry.getValue();
if (value != null && !"".equals(value)) {
String jsonValue;
if (value instanceof Map || value instanceof List || value instanceof JSONObject) {
jsonValue = JSONObject.toJSONString(value, SerializerFeature.WriteMapNullValue);
} else {
jsonValue = value.toString();
}
sb.append("&").append(entry.getKey()).append("=").append(jsonValue);
}
}
sb.append("&").append(signSecretKey).append("&").append(time);
return DigestUtils.md5DigestAsHex(sb.toString().getBytes());
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
lua demo
function signV2(signSecretKey, timestamp, data)
local map = {}
-- 将表数据转换为类似Map的结构,添加空值过滤
for key, value in pairs(data) do
if value ~= nil and value ~= "" then -- 过滤nil和空字符串
map[key] = value
end
end
-- 获取所有的键并进行排序
local sortedKeys = {}
for key in pairs(map) do
table.insert(sortedKeys, key)
end
table.sort(sortedKeys)
local resultSign = ""
-- 拼接字符串
for _, key in ipairs(sortedKeys) do
resultSign = resultSign .. "&" .. key .. "=" .. map[key]
end
resultSign = resultSign .. "&" .. signSecretKey .. "&" .. timestamp
-- 计算md5并返回结果
return md5.sumhexa(resultSign)
end
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
# 验签规则V3
# 规则说明
在V2基础上增加随机字符串nonce
(2分钟内不可重复),进一步提升安全性。
- 请求头需携带:
time
(时间戳)、sign
(签名)、nonce
(随机字符串)。
# 验签步骤
- 过滤参数:同V2步骤1。
- 排序参数:同V2步骤2。
- 拼接字符串:
&key1=value1&key2=value2&...&signSecretKey&time&nonce
(多追加&nonce
)。 - 生成签名:对拼接结果做MD5加密。 验签Demo: javascript demo
/**
* 生成V3签名
* @param {string} time - 时间戳
* @param {string} signSecretKey - 验签秘钥
* @param {Object} param - 请求参数对象
* @param {string} nonce - 随机字符串
* @returns {string} - MD5签名结果
*/
function signApiV3Sign(time, signSecretKey, param, nonce) {
// 1. 过滤空值参数
var filteredParam = {};
for (var key in param) {
if (param.hasOwnProperty(key)) {
var value = param[key];
if (value !== null && value !== undefined && value !== '') {
filteredParam[key] = value;
}
}
}
// 2. 按键名排序
var sortedKeys = [];
for (var key in filteredParam) {
if (filteredParam.hasOwnProperty(key)) {
sortedKeys.push(key);
}
}
sortedKeys.sort();
// 3. 拼接参数字符串
var sb = '';
for (var i = 0; i < sortedKeys.length; i++) {
var key = sortedKeys[i];
sb = sb + '&' + key + '=' + filteredParam[key];
}
// 4. 添加秘钥、时间戳和随机字符串
sb = sb + '&' + signSecretKey + '&' + time + '&' + nonce;
// 5. 计算MD5(假设md5函数已全局可用)
return md5(sb);
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
java demo
/**
* @param time 时间戳
* @param signSecretKey 验签秘钥
* @param param 数据
* @param nonce 随机字符串
* @return
*/
public static String signApiV3Sign(String time, String signSecretKey, Map<String, String> param, String nonce) {
// 按照字典顺序排序
TreeMap<String, Object> treeMap = new TreeMap<>(param);
StringBuilder sb = new StringBuilder();
for (Map.Entry<String, Object> entry : treeMap.entrySet()) {
Object value = entry.getValue();
// 忽略 null 和空字符串的 key
if (value != null && !"".equals(value)) {
String jsonValue;
// 如果是 Map/List/JSONObject 等结构,使用 JSON 序列化,并保留 null
if (value instanceof Map || value instanceof List) {
jsonValue = JSONObject.toJSONString(value, SerializerFeature.WriteMapNullValue);
} else {
jsonValue = value.toString();
}
sb.append("&").append(entry.getKey()).append("=").append(jsonValue);
}
}
sb.append("&").append(signSecretKey).append("&").append(time).append("&").append(nonce);
return DigestUtils.md5DigestAsHex(sb.toString().getBytes());
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
lua demo
function signApiV3Sign(time, signSecretKey, param, nonce)
-- 1. 过滤空值参数
local filteredParam = {}
for key, value in pairs(param) do
if value ~= nil and value ~= "" then
filteredParam[key] = value
end
end
-- 2. 按键名排序
local sortedKeys = {}
for key in pairs(filteredParam) do
table.insert(sortedKeys, key)
end
table.sort(sortedKeys)
-- 3. 拼接参数字符串
local sb = ""
for _, key in ipairs(sortedKeys) do
sb = sb .. "&" .. key .. "=" .. filteredParam[key]
end
-- 4. 添加秘钥、时间戳和随机字符串
sb = sb .. "&" .. signSecretKey .. "&" .. time .. "&" .. nonce
-- 5. 计算MD5
return md5.sumhexa(sb)
end
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
# 加解密规则
请求加密,请求加密规范,请求内容为半加密,需要以key-加密(value),方式请求,其中加密(value)指的是加密算法加密后的值,其中key不需要加密,土豆API给予响应内容,为全加密
正确加密请求实例
实例接口/api/login
请求
{
"userNumber":"MTIzNDc=",
"passWord":"MTIzNDU2"
}
响应内容:
eyJjb2RlIjoiMjAwIiwibWVzc2FnZSI6IiIsInN0YXR1cyI6dHJ1ZSwiZGF0YSI6eyJhcGlVc2VyVG9rZW4iOiJleUowZVhBaU9pSktWMVFpTENKaGJHY2lPaUpJVXpJMU5pSjkuZXlKamRYSnlaVzUwSWpveE5qWTBPVE0wTlRrNU9UTXpMQ0pWVTBWU1ZHOXJaVzVMWlhraU9pSTJPVEUwTlRJNE1UWTRNRFU0TnprNE1EaGZNVEl6TkRjaUxDSjFjMlZ5U1dRaU9qWTVNVFExTWpneE5qZ3dOVGczT1Rnd09Dd2lkWE5sY2s1MWJXSmxjaUk2SWpFeU16UTNJbjAuR0VJMldjWF85TjhuT21fZURxelQyclJzOUJfeXAwcms3aTdHVGFXS3dUQSJ9LCJwYyI6bnVsbCwidGltZSI6bnVsbCwic2luIjpudWxsfQ==
2
3
4
5
6
7
错误加密请求实例
实例接口/api/login
请求
{
"userNumber":"12347",
"passWord":"123456"
}
响应内容:
eyJjb2RlIjoiNTAwIiwibWVzc2FnZSI6IuaVsOaNruino+WvhuWksei0pSIsInN0YXR1cyI6ZmFsc2V9
2
3
4
5
6
7
# 注意
注意,后端http状态码为500时,一般表示为请求数据解析失败或者请求数据解密失败,或者系统错误, 如果http状态码为500,当然解密失败情况只会出现在开发阶段,正式阶段出现加解密异常则为开发者更换了秘钥导致,返回报文为明文数据对象, 开发者可以直接获取数据,如果是业务类型错误,比如用户余额不足,返回的http状态码为200, 错误信息为密文,开发者使用对应解密方法解密数据即可, 凡是上传文件的接口均不支持加解密(不包含base64),后续优化该功能
解密失败请求实例
实例接口api/updateUserBalance
请求:
{
"type":12,
"amount":10
}
2
3
4
响应内容: 此时http状态码为500,不是返回数据码,这点请注意
数据解密失败报文:
{
"timestamp": 1676518671836,
"status": 500,
"error": "Internal Server Error",
"message": "数据解密失败",
"path": "/api/updateUserBalance"
}
数据解析失败报文:
{
"timestamp": 1676519332339,
"status": 500,
"error": "Internal Server Error",
"message": "内容解析失败,请检查提交信息是否正确",
"path": "/api/updateUserBalance"
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
# 请求生产环境地址,下文的baseUrl
https://api.potatocloud.cn
# 请求URL(baseUrl+接口URL)
{baseUrl}/api/test
- 举例
https://api.potatocloud.cn/api/test
# 请求方式
- POST | GET | DELETE | PUT
# 请求头参数
参数名 | 必选 | 类型 | 说明 |
---|---|---|---|
Content-Type | 是 | string | 此参数必传,当请求数据非json时此参数传对应格式如(multipartform-data,application/x-www-form-urlencoded,等)是json请传application/json |
askKey | 是 | string | 此参数必传,验证app的令牌 |
sign | 否 | string | 此参数如果在app设置开启了验签是必传,规则上方有描述 |
time | 否 | string | 当开启验签时,此参数为必传 |
apiUserToken | 否 | string | 除了部分不验证用户令牌的接口以外此参数为必传(注册/登陆/发送验证码 )不是必传,其余都是必传 |
# 接口参数
接口参数每个接口文档有详细的参数描述
# 返回示例
{
"code": "200",
"message": "",
"status": true,
"data": null,
"pc": null,
"time": null,
"sign": null,
"nonce": null
}
2
3
4
5
6
7
8
9
10
11
# 返回参数说明
参数名 | 类型 | 说明 |
---|---|---|
code | string | 200请求成功,403无权限或令牌过期,返回该状态码建议跳转登陆界面让用户进行重新登陆500为错误,message会携带错误信息返回,可以将该详细提示给用户 |
message | string | 错误信息,成功是不会返回错误信息 |
status | boolean | 状态,true 为成功,false 为失败 |
data | json | 返回数据 格式为json,如果需要返回数据时候,该参数会携带数据返回 |
pc | json | 分页对象,携带分页信息,如果不是列表查询该参数为null |
time | String | 时间戳(开启验签时返回不为空) |
sign | String | 签名(开启验签时返回不为空) |
nonce | String | 随机字符串(开启验签V3时返回不为空) |
# 备注
# OCR识别
OCR支持中,英文,以及数字,其他字库联系官方添加 如果OCR识别不支持PNG后缀直接改成jpg这种类型文件,如果出现该情况,请保存新的图像上传识别,由于字库是使用默认字库,如需识别特殊字符可以联系官方训练字库,
- 更多返回错误代码请看首页的错误代码描述
关于我们 →