---
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编码生成签名字符串。