1. 引言
1.1 文档目的
本文档旨在系统平台接口技术规范进行说明,用于指导开发人员进行相关业务的开发。
1.2 文档范围
2. 接口协议
2.1 基本约束
- 接口数据使用UTF-8编码。
- 接口地址的形式为 服务域名:端口/地址。
- 接口地址请求时,使用HTTP POST, GET,DELETE, PUT 方式。
- 在请求头接口时放置在HTTP Header的Cookie部分 。返回值使用 JSON 数据格式。
- 每个请求都需要加参数请求签名 sign, 见签名规则
- 开发环境:
- 正式环境:
- 接口所有时间段和日期端均采用前闭后开的业务
- 金额的单位统一为分
2.2 常量
名称 | 值 | 说明 |
---|---|---|
app_id | platform | 接口编号,服务器分配 |
app_secret | 123456789 | 对应接口秘钥,服务器分配 |
备注:具体合作编码和秘钥,另行通知
2.3 HTTP 返回状态
stateCode | 含义 | 返回内容 |
---|---|---|
200 | 数据请正常返回 | 正常数据,见各接口格式 |
400 | 业务错误 | 错误代码 |
401 | 未授权 | 错误代码 |
404 | 方法不存在 | 错误代码 |
409 | 冲突请求 | 错误代码 |
421 | 会话超时 | 错误代码 |
422 | 表验证错误 | 错误代码 |
500 | 服务器错误,确认状态并报告问题 | 错误代码 |
301:
{
'status':'FAILS',
"message":"错误内容",
"data":[]
}
500:
{
"message":"Undefined variable:users",
}
401:
{
"message":"Failed to authenticate because of bad credentials or an invalid authorization header.",
}
403:
{
"message":"Failed to authenticate because of bad credentials or an invalid authorization header.",
}
422
{
"message": "Could not create new user.",
"errors": {
"username": [
"The username field is required."
],
"password": [
"The password field is required."
]
}
}
2.4签名方式:
加密签名规则:MD5
明文:$str =
1:获取到明文数组;追加 app_id, datetime 数据,
2:按KEY顺序排列:(多维数据,递归排序)
3: 转成 $key=$val ,并用 & 连接 (http_build_query)
4: 添加 &app_secret=秘钥
md5($str);
参数名 | 必选 | 类型 | 说明 |
---|---|---|---|
app_id | 是 | string | 接口id:另行提供 |
app_secret | 是 | string | 接口秘钥:另行提供 |
datetime | 否 | datetime | 生成请求时间搓, |
biz_content | 是 | 业务数组 | 生成请求时间搓, |
备注
1:注意加密顺序: 按KEY顺序排列。app_secret,拼接在加密传最后
2:加密后 sign 全大写
3:注意datetime 时间,目前定义签名有效期为5分钟。
例子
业务数据:
array(12) {
["account_type"] => string(1) "2"
["bank_type"] => int(1)
["belong_type"] => string(1) "c"
["enter_prise_name"] => string(22) "测试公司1552964283"
["business_licence"] => string(1) "1"
["account_name"] => string(44) "虚拟户账户名称-测试公司1552964283"
["account_sn"] => string(14) "zc201901220008"
["belong_id"] => string(1) "1"
["sys_member"] => int(5)
["op_user"] => string(1) "1"
["open_user_id"] => string(1) "1"
}
签名明文:app_id, app_secret,
account_name=虚拟户账户名称-测试公司1552964283&account_sn=zc201901220008&account_type=2&app_id=platform&bank_type=1&belong_id=1&belong_type=c&business_licence=1&enter_prise_name=测试公司1552964283&op_user=1&open_user_id=1&sys_member=5&app_secret=app_secret
签名密文:E4481C7A716433756FDD6F488A42BFB1