source/_posts/一卡通v5二维码身份识别接口 - epayment/epayapidocs - Gitiles

 ---
 title: 一卡通v5二维码身份识别接口
 date: 2018-10-14
 tags:

 ---

 ## 1.1文档说明 ##

 本文档用于描述了一卡通二维码身份识别接口，供第三方系统（前置和应用）对接参考。

 ## 1.2约定 ##

 1.	传输编码统一为utf-8
 2.	RSA 加密算法为本接口采用的非对称加密算法，`SIGN_ALGORITHMS ="SHA1WithRSA"`;
 3.	RSA公钥由本系统提供，本系统返回信息的签名数据，第三方系统得到后通过公钥校验算法，验证返回数据的合法性
 4.	HMAC加密算法为用户请求本系统采用的加密算法，`SIGN_ALGORITHMS ="HMAC-SHA1"`;
 5.	具体签名生成参考后面的签名章节
 6.	retcode等于0表示成功，非0表示失败，失败具体信息查看retmsg


 ## 2.1 二维码身份识别 ##

 **请求URL:**

 - `https://ip:port/epayapi/services/thirdparty/common/qrcodecertification`

 **请求方式/格式:**

 - POST
 - application/x-www-form-urlencoded

 **请求参数:**

 |参数名 | 类型 | 必选 | 说明 |
 |-----|------|-----|------|
 |partner_id|String|是&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|本系统分配给各个接入应用的合作伙伴id号|
 |qrcode|String|是&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|二维码|
 |timestamp|String|是|时间戳格式为yyyyMMddhh24miss|
 |sign|String|是|	签名|
 |sign_method|String|是|参数的加密方法选择，可选值是：HMAC 加密方式为HAMC-SHA1|

 **请求内容示例:**
 ```html
 URI：https://ip:port/epayapi/services/thirdparty/common/qrcodecertification

 partner_id:10000
 qrcode:GcS2nsBRzhW72lQgcGdI6s64YSaaWnxlWtIiUSYrPCTzHH0cKkah0HFnr13ejXSL7vkAAQnuwXhoEwNZ11VsVslq95QxqCOisItFJnC1BTg7ZN23cIw1yYyeB2keMICo8FUDkpuUmEY=
 timestamp:20150119130901
 sign:5195f9b9116e4adf67eeebc9935d33dc683f677d
 sign_method:HMAC
 ```

 **返回示例:**

 - 成功

 ```json
 {
 	"retcode":"0",
 	"retmsg":"query success",
 	"stuempno":"09893092",
 	"expiredate":"20191010",
     "sign_method":"HMAC",
     “sign”:5195f9b9116e4adf67eeebc9935d33dc683f677d
 }

 ```

 - 失败

 ```json
 {
 	"retcode":"1",
 	"retmsg":"account not exsit"
 }

 ```

 **返回参数说明:**

 |参数名 | 类型 | 说明 |
 |-----|-----|------|
 |retcode|String|返回码（0=成功，其他为失败）|
 |retmsg|String|返回消息|
 |stuempno|String|学号|
 |expiredate|String|有效期|
 |sign|String|签名，与请求方式签名方式相同|

 ## 附录A-用户请求HMAC签名算法 ##


 - 签名方式：`hmac-sha1`

 - 签名密钥由本系统统一线下提供


 - **签名校验的通用步骤如下：**

 	**第一步，**设所有发送或者接收到的数据为集合M，将集合M内非空参数值的参数按照参数名ASCII码从小到大排序（字典序），使用URL键值对的格式（即key1=value1&key2=value2…）拼接成字符串stringA。

 > 假设传送的参数如下：


 ```
 	partner_id:10000
 	qrcode:cS2nsBRzhW72lQgcGdI6s64YSaaWnxlWtIiUSYrPCTzHH0cKkah0HFnr13ejXSL7vkAAQnuwXhoEwNZ11VsVslq95QxqCOisItFJnC1BTg7ZN23cIw1yYyeB2keMICo8FUDkpuUmEY=
 	timestamp:20150119130901
 	sign:5195f9b9116e4adf67eeebc9935d33dc683f677d
 	sign_method:HMAC
 ```
 > 对参数按照key=value的格式，并按照参数名ASCII字典序排序如下：


 ```
 	partner_id=10000&qrcode=cS2nsBRzhW72lQgcGdI6s64YSaaWnxlWtIiUSYrPCTzHH0cKkah0HFnr13ejXSL7vkAAQnuwXhoEwNZ11VsVslq95QxqCOisItFJnC1BTg7ZN23cIw1yYyeB2keMICo8FUDkpuUmEY=&sign_method=HMAC&timestamp=20150119130901
 ```

 	**特别注意以下重要规则：**


 - 参数名ASCII码从小到大排序（字典序）；


 - 如果参数的值为空不参与签名；


 - 参数名区分大小写；


 - 传送的sign参数不参与签名，用该sign值作校验。

 	**第二步，**用密钥secretkey对stringA字符串，进行hmac-sha1签名，得到sign值signValue。signValue最后采用十六进制小写hex编码生成签名字符串。
	---
	title: 一卡通v5二维码身份识别接口
	date: 2018-10-14
	tags:

	---

	## 1.1文档说明 ##

	本文档用于描述了一卡通二维码身份识别接口，供第三方系统（前置和应用）对接参考。

	## 1.2约定 ##

	1. 传输编码统一为utf-8
	2. RSA 加密算法为本接口采用的非对称加密算法，`SIGN_ALGORITHMS ="SHA1WithRSA"`;
	3. RSA公钥由本系统提供，本系统返回信息的签名数据，第三方系统得到后通过公钥校验算法，验证返回数据的合法性
	4. HMAC加密算法为用户请求本系统采用的加密算法，`SIGN_ALGORITHMS ="HMAC-SHA1"`;
	5. 具体签名生成参考后面的签名章节
	6. retcode等于0表示成功，非0表示失败，失败具体信息查看retmsg


	## 2.1 二维码身份识别 ##

	请求URL:

	- `https://ip:port/epayapi/services/thirdparty/common/qrcodecertification`

	请求方式/格式:

	- POST
	- application/x-www-form-urlencoded

	请求参数:

	\|参数名 \| 类型 \| 必选 \| 说明 \|
	\|-----\|------\|-----\|------\|
	\|partner_id\|String\|是      \|本系统分配给各个接入应用的合作伙伴id号\|
	\|qrcode\|String\|是      \|二维码\|
	\|timestamp\|String\|是\|时间戳格式为yyyyMMddhh24miss\|
	\|sign\|String\|是\| 签名\|
	\|sign_method\|String\|是\|参数的加密方法选择，可选值是：HMAC 加密方式为HAMC-SHA1\|

	请求内容示例:
	```html
	URI：https://ip:port/epayapi/services/thirdparty/common/qrcodecertification

	partner_id:10000
	qrcode:GcS2nsBRzhW72lQgcGdI6s64YSaaWnxlWtIiUSYrPCTzHH0cKkah0HFnr13ejXSL7vkAAQnuwXhoEwNZ11VsVslq95QxqCOisItFJnC1BTg7ZN23cIw1yYyeB2keMICo8FUDkpuUmEY=
	timestamp:20150119130901
	sign:5195f9b9116e4adf67eeebc9935d33dc683f677d
	sign_method:HMAC
	```

	返回示例:

	- 成功

	```json
	{
	"retcode":"0",
	"retmsg":"query success",
	"stuempno":"09893092",
	"expiredate":"20191010",
	"sign_method":"HMAC",
	“sign”:5195f9b9116e4adf67eeebc9935d33dc683f677d
	}

	```

	- 失败

	```json
	{
	"retcode":"1",
	"retmsg":"account not exsit"
	}

	```

	返回参数说明:

	\|参数名 \| 类型 \| 说明 \|
	\|-----\|-----\|------\|
	\|retcode\|String\|返回码（0=成功，其他为失败）\|
	\|retmsg\|String\|返回消息\|
	\|stuempno\|String\|学号\|
	\|expiredate\|String\|有效期\|
	\|sign\|String\|签名，与请求方式签名方式相同\|

	## 附录A-用户请求HMAC签名算法 ##


	- 签名方式：`hmac-sha1`

	- 签名密钥由本系统统一线下提供


	- 签名校验的通用步骤如下：

	第一步，设所有发送或者接收到的数据为集合M，将集合M内非空参数值的参数按照参数名ASCII码从小到大排序（字典序），使用URL键值对的格式（即key1=value1&key2=value2…）拼接成字符串stringA。

	> 假设传送的参数如下：


	```
	partner_id:10000
	qrcode:cS2nsBRzhW72lQgcGdI6s64YSaaWnxlWtIiUSYrPCTzHH0cKkah0HFnr13ejXSL7vkAAQnuwXhoEwNZ11VsVslq95QxqCOisItFJnC1BTg7ZN23cIw1yYyeB2keMICo8FUDkpuUmEY=
	timestamp:20150119130901
	sign:5195f9b9116e4adf67eeebc9935d33dc683f677d
	sign_method:HMAC
	```
	> 对参数按照key=value的格式，并按照参数名ASCII字典序排序如下：


	```
	partner_id=10000&qrcode=cS2nsBRzhW72lQgcGdI6s64YSaaWnxlWtIiUSYrPCTzHH0cKkah0HFnr13ejXSL7vkAAQnuwXhoEwNZ11VsVslq95QxqCOisItFJnC1BTg7ZN23cIw1yYyeB2keMICo8FUDkpuUmEY=&sign_method=HMAC&timestamp=20150119130901
	```

	特别注意以下重要规则：


	- 参数名ASCII码从小到大排序（字典序）；


	- 如果参数的值为空不参与签名；


	- 参数名区分大小写；


	- 传送的sign参数不参与签名，用该sign值作校验。

	第二步，用密钥secretkey对stringA字符串，进行hmac-sha1签名，得到sign值signValue。signValue最后采用十六进制小写hex编码生成签名字符串。