奥双科技-电子券核销接口文档

奥双科技 2022-6-30 内部文档非授权禁止传播

1.整体调用流程

商户系统->奥双系统: 获得电子券类型
商户系统->奥双系统: 请求派发电子券
商户系统->奥双系统: 请求核销码
商户系统-->用户:展示核销码
用户-->中石油加油站:过机核销

流程说明

请求获得有哪些优惠卷可用
根据获得的优惠券生成电子券
根据电子卷获得核销码
用户到加油站使用核销码核销

2.接口统一调用规则

通知方式：POST
协议：HTTP
字符编码：UTF-8
请求方法：POST
API请求域名：http://api.gasjfdh.com

每次统一请求必须的参数：

属性	类型	说明
sign	String	签名 String 使用MD5对传输参数进行签名
nonce	String	随机字符串
timestamp	String	13位时间戳
appId	String	商户appid 接口双方上线时约定

统一返回值：

code 为0000则为请求正确，其他则是出现错误

{
    "code": "0000",
    "data": {},
    "msg": ""
}

我方分配的数据：

商户APPID
商户secret密钥

签名规则

按字段值的ASCII 码从小到大排序（字典序）；
将排序后的字段值按照k=v&k1=v1的方式拼接成字符串；
最后拼接商户 secret 字段
对拼接后的字符串计算SHA1 摘要，作为签名，并转为大写

示例

merch_secret = 'ABCDE' #商户密钥
data = {
    'token':'GGGhhhJJJJ',
    'phone':'13426063560',
    'key':'123456', # 商户key
}

请求参数拼接后的字符串：

key=123456&phone=13426063560&token=GGGhhhJJJJABCDE

对应MD5签名：

BDA9C7A71877035C10AD4550285CD2CD

签名算法 python 代码

def make_sign(params,merch_secret):
    '''
    签名算法
    '''
    keys = sorted(params.keys()) # ASCII 码从小到大排序
    tem = '%s=%s'
    sign_str = []
    for k in keys:
        sign_str.append( tem %(k,params[k])) # k=v的方式拼接成字符串
    sign_str = '&'.join(sign_str) + merch_secret # & 链接，并在最后添加商户密钥
    my_sign = hashlib.md5(sign_str.encode(encoding='UTF-8')).hexdigest()
    params['sign'] = my_sign.upper() # 签名转为大写
    return params

签名算法 JAVA:

    public static String MD5(String md5) {
       try {
            java.security.MessageDigest md = java.security.MessageDigest.getInstance("MD5");
            byte[] array = md.digest(md5.getBytes());
            StringBuffer sb = new StringBuffer();
            for (int i = 0; i < array.length; ++i) {
              sb.append(Integer.toHexString((array[i] & 0xFF) | 0x100).substring(1,3));
           }
            return sb.toString().toUpperCase();
        } catch (java.security.NoSuchAlgorithmException e) {
        }
        return null;
    }

签名算法 PHP:

<?php
echo strtoupper(md5("key=123456&phone=13426063560&token=GGGhhhJJJJABCDE"));
?>

3 获取电子券类型

电子券系统提供获取电子券类型接口供第三方系统调用。第三方系统按照该接口规范说明，调用该接口获取电子券类型。

接口请求地址：

http://api.gasjfdh.com/third/api/getCouTypes/

在线测试： http://api.gasjfdh.com/third/apitest/#getCouTypes

请求参数：

统计请求参数

输出参数说明

*输出参数说明*
变量	名称	类型	备注
title	券类型名称	String(100)	券类型名称
alias	券类型别名	String(64)	券类型别名
faceValue	面值金额	Bigdecimal	券面值金额（单位为元），当券类型为折扣券时，面值金额为0
couCategory	券类型	Int(2)	10、满减券 40 折扣券
couDiscountValue	折扣率	Bigdecimal	折扣率例：折扣为9.7折时，为0.97
couDiscountValueStr	折扣展示	String	例：折扣为9.7折时，为“9.7”
couDiscountMaxValue	最大折扣金额	Bigdecimal	当折扣计算后金额大余最大折扣金额时，以最大折扣金额为准
img	券图片路径	String(100)	券图片路径（http全路径）
declare	券使用说明	String(1024)	券使用说明
bizType	使用类型编码	String(4)	使用类型编码 4001: 油品券 4002: 汽油券 4003: 柴油券 4004: 非油券 4006: 异业券
bizTypeDesc	使用类型描述	String(20)	使用类型描述
validType	有效期类型	Int(1)	券有效期类型： 1固定；2动态
validDate	有效期	String	类型1：”2020-01-01#2020-01-02” 类型2：”15”
controlCnt	是否控制库存	Int	0不控制，1控制
cnt	库存数量	Int
faceType	面额类型	Int	1固定金额 3动态金额
ouCode	机构编码	String(20)
ouName	机构名称	String(64)

请求参数示例

{
    "appId": "test",
    "nonce": "1656570598182",
    "timestamp": "1656573937062",
    "sign": "14E23A07DC7404511CBF4CF9FE9F8725"
}

输入参数示例

{
    "code": "0000",
    "data": [
        {
            "alias": "2.99元非油券",
            "bizType": "4004",
            "bizTypeDesc": "非油券",
            "cnt": 26,
            "controlCnt": 1,
            "couCategory": 10,
            "couDiscountMaxValue": 0,
            "couDiscountValue": 0,
            "couDiscountValueStr": "",
            "declare": "<p>2.99元非油券</p>",
            "faceType": 1,
            "faceValue": 2.99,
            "img": "http://11.8.203.88//cnpccoupontest/img/product_img/00/00/23/50.png",
            "limit": 0,
            "ouCode": "1000028",
            "ouName": "河北销售分公司",
            "title": "2.99元非油券",
            "validDate": "30",
            "validType": 2
        },
        {
            "alias": "移动手机积分非油商品兑换测试券",
            "bizType": "4004",
            "bizTypeDesc": "非油券",
            "cnt": 79,
            "controlCnt": 1,
            "couCategory": 10,
            "couDiscountMaxValue": 0,
            "couDiscountValue": 0,
            "couDiscountValueStr": "",
            "declare": "<p>移动手机积分非油商品兑换测试券</p>",
            "faceType": 1,
            "faceValue": 8,
            "img": "http://11.8.202.254//cnpccouponpro/img/product_img/00/10/42/99.png",
            "limit": 0,
            "ouCode": "1000008011",
            "ouName": "山东淄博分公司",
            "title": "移动手机积分非油商品兑换测试券",
            "validDate": "2022-06-17#2022-06-30",
            "validType": 1
        }
    ]
}

4 批量获取电子券

电子券系统提供获取电子券接口供第三方系统调用。第三方系统按照该接口规范说明，调用该接口获取电子券。一次最多传入5种券类型。

接口请求地址：

http://api.gasjfdh.com/third/api/getCoupon/

在线测试： http://api.gasjfdh.com/third/apitest/#getCoupon

请求参数

*变量*	*名称*	*类型*	*必填项*	*备注*
businessId	业务主键	String(32)	是	业务主键，必须全局唯一
batchNo	派发批次号	String(50)	否	如果传入批次号以传入值为准，如果为空系统会自动生成一个派发批次号
alias	券类型别名	String(64)	是	券类型别名
num	张数	Int(2)	是	张数，最小1张，最大20张

输出参数说明：

*变量*	*名称*	*类型*	*备注*
batchNo	派发批次号	String(50)	派发批次号
rows	券列表	Array	派券结果列表
-->createTime	生成券时间	String	生成券时间
-->voucher	电子券标识	String(25)	唯一标识
-->alias	券类型别名	String(50)	券类型别名
-->faceValue	券面值金额	Bigdecimal	券面值（单位为元）
-->couCategory	券类型	Int(2)	10、满减券 40 折扣券
-->couDiscountValue	折扣率	Bigdecimal	折扣率例：折扣为9.7折时，为0.97
-->couDiscountValueStr	折扣展示	String	例：折扣为9.7折时，为“9.7”
-->start	可用开始时间	String	可用开始时间
-->end	可用结束时间	String	可用结束时间
-->img	券图片路径	String(100)	券图片路径（http全路径）
-->declare	券使用说明	String(1024)	券使用说明

请求数据示例：

{
    "appId": "test",
    "nonce": "1656570598182",
    "timestamp": "1656574409064",
    "alias": "2.99元非油券",
    "businessId": "122833322",
    "num": "2",
    "batchNo": "",
    "sign": "EA8E629A3F3DFCFB0E70096535B0D282"
}

返回示例：

{
    "code": "0000",
    "data": {
        "batchNo": "20220630153337",
        "rows": [
            {
                "alias": "2.99元非油券",
                "couCategory": 10,
                "couDiscountValue": 0,
                "couDiscountValueStr": "",
                "couTypeCode": "",
                "createTime": "2022-06-30 15:33:37",
                "declare": "<p>2.99元非油券</p>",
                "end": "2022-07-30",
                "faceValue": 2.99,
                "img": "http://11.8.203.88//cnpccoupontest/img/product_img/00/00/23/50.png",
                "start": "2022-06-30",
                "voucher": "202206301533372709"
            },
            {
                "alias": "2.99元非油券",
                "couCategory": 10,
                "couDiscountValue": 0,
                "couDiscountValueStr": "",
                "couTypeCode": "",
                "createTime": "2022-06-30 15:33:37",
                "declare": "<p>2.99元非油券</p>",
                "end": "2022-07-30",
                "faceValue": 2.99,
                "img": "http://11.8.203.88//cnpccoupontest/img/product_img/00/00/23/50.png",
                "start": "2022-06-30",
                "voucher": "202206301533378136"
            }
        ]
    }
}

5 获取核销码

电子券系统提供获取电子券接口供第三方系统调用。第三方系统按照该接口规范说明，调用该接口获取电子券。一次最多传入5种券类型。

接口请求地址：

http://api.gasjfdh.com/third/api/getCheckCode/

在线测试： http://api.gasjfdh.com/third/apitest/#getCheckCode

请求参数

*变量*	*名称*	*类型*	*必填项*	*备注*
businessId	业务主键	String(32)	是	业务主键，必须全局唯一
voucher	电子券标识	String(25)	是	电子券编号

输出参数说明：

*变量*	*名称*	*类型*	*备注*
checkCode	核销码	String(25)	电子券核销凭证

请求数据示例：

{
    "appId": "test",
    "nonce": "1656570598182",
    "timestamp": "1656574717687",
    "businessId": "122833322",
    "voucher": "202206301533378136",
    "sign": "E36C991E9BEACC9A936EBF108A023185"
}

返回示例：

{
    "code": "0000",
    "data": {
        "checkCode": "123456789098776"
    }
}

6 获取电子券状态

电子券系统提供获取电子券类型接口供第三方系统调用。第三方系统按照该接口规范说明，调用该接口获取电子券类型。

接口请求地址：

http://api.gasjfdh.com/third/api/getState/

在线测试： http://api.gasjfdh.com/third/apitest/#getState

请求参数

*变量*	*名称*	*类型*	*必填项*	*备注*
businessId	业务主键	String(32)	是	业务主键，必须全局唯一
voucher	电子券标识	String(25)	是	电子券编号

输出参数说明：

*变量*	*名称*	*类型*	*备注*
state	状态	Int	20未使用 40已使用 90已撤销
usedTime	使用时间	String	核销时间
station	核销站点	String	核销站点4位编码
stationName	核销站点名称	String	核销站点（中文）名称
amount	订单金额	BigDecimal	核销券时的订单总金额

请求数据示例：

{
    "appId": "test",
    "nonce": "1656570598182",
    "timestamp": "1656574873537",
    "businessId": "122833322",
    "voucher": "202206301533378136",
    "sign": "B56E40A055C954CEBE61FC0D1072DE3E"
}

返回示例：

{
    "code": "0000",
    "data": {
        "amount": 0,
        "state": 20,
        "station": "",
        "stationName": "",
        "usedTime": ""
    }
}