E码通电子凭证服务平台 通用接口接入规范

E码通电子凭证服务平台

通用接口接入规范

V 1.0

文档变更记录

版本	日期	变更内容	操作者	备注
V 1.0	2011-05-05	创建	Bill	初始版本
V 1.01	2011-06-02	增加下属机构码	Bill	完善调整
V 1.02	2011-06-16	增加短/彩信内容验证码放置位置控制	Bill	消息内容调整
V 1.03	2011-06-22	生成凭证请求增加可选参数	Bill	参数调整
V1.04	2011-11-11	通知增加当前验证数	Bill	参数调整
V1.05	2011-11-18	增加凭证同步方法	Bill
V1.06	2011-12-01	1.增加离线验证的凭证同步方法。 2.增加凭证生成与分发（无商品号）无回调方法。	Bill

 

目 录

1． 前言 3

1．1 接口定义 3

1．2 术语定义 3

2． 接口协议 4

2．1 协议规定 4

2．2 请求参数约定 4

2．3 回调参数定义（生成结果列表） 4

2．4 流水号验证 5

2．5 时间戳验证 5

2．6 签名验证 5

3． 接口处理流程 6

4． 消息定义 6

4.1 商品提交请求 7

4.1.1 商品提交请求消息 7

4.1.2 商品提交返回结果 8

4.2 凭证的生成和分发(无商品号) 8

4.2.1 生成和分发请求消息 8

4.2.2 生成请求返回结果 10

4.2.3 回调消息 11

4.3 凭证的生成 (不分发) 12

4.3.1 生成请求消息 12

4.3.2 生成请求返回结果 13

4.3.3 回调消息 13

4.4 凭证的生成和分发(有商品号) 15

4.4.1 生成和分发请求消息 15

4.4.2 短信和彩信内容构造规则 16

4.4.3 生成请求返回结果 17

4.4.4 回调消息 17

4.5 凭证使用查询 19

4．5．1 凭证使用查询消息 19

4．5．2 凭证使用查询结果 20

4.6 凭证的转发 21

4.6.1 转发请求消息 21

4.6.2 转发请求结果 22

4.7 凭证的重发 23

4.7.1 凭证重发请求 23

4.7.2 重发请求返回结果 23

4.8 凭证的废除 24

4.8.1 凭证废除请求 24

4.8.2 废除请求返回结果 24

4.9 账单查询 25

4．9．1 账单查询消息 25

4．9．2 账单查询结果 26

4.10 通知消息 27

4.10.1 消息头 27

4.10.2 消息体 28

4.11 凭证同步 29

4．11．1 请求消息 29

4．11．2 返回结果 29

4.12 凭证的生成和分发(无商品号，无回调) 30

4.12.1请求消息 30

4.12.2 生成请求返回结果 32

4.13 离线验证，凭证同步（软件商店专用） 34

4.13.1请求消息 34

4.13.2返回结果 35

5. 结果提示定义 36

1． 前言

E码通电子凭证服务平台通用接口（以下简称通用接口或接口），是电子凭证服务平台为广大用户或商家提供的通用API，为用户使用平台的服务，进行电子凭证的生成、分发和验证提供便利。

1．1 接口定义

接口是指由用户系统发起请求，平台对请求的消息进行处理，并将处理结果返回给用户系统的API程序。接口的返回类型有两种形式，一种是同步的返回方式，一般如凭证查询、账单查询等使用这种方式，即查询的结果跟请求结果一起返回。另一种是异步的方式，如各种凭证的生成请求，请求的返回结果只是提示此次请求的成功与否，生成的执行结果将以回调或文件下载的方式，提供给用户系统——请求者。如果需要以回调的方式取回生成结果，必须提供有效的回调地址。

1．2 术语定义

术语	意义
终端	验证二维码的POS机
回调	由平台以异步方式向请求者发送请求的执行结果

 

2． 接口协议

2．1 协议规定

接口通讯协议统一使用HTTP协议，字符集使用UTF-8，请求方法使用POST。

请求接口地址：

正式环境调用地址：http://ecode.ematong.com/gcert/submsg

 

2．2 请求参数约定

序号	参数	参考值	意义	备注
1	method	requestmessage	消息方法
2	format	json	消息体格式	或xml
3	version	1.0	版本
4	appkey	1234567890123456	商家的key
5	message	{"request_message": {"message": {"req_type":"01","num_iid":"1011234578","title":"面包","price":1.20","mms_pic":"http://www.com.cn/image/g1234.jpg ","descs":"商品描述","server_print_text":"终端打印的服务内容","detail_url":" http://www.com.cn/goods.htm "} } }	消息体内容
6	flowno	100000001	请求流水号
7	timestamp	2011-04-20 08:50:15	时间戳
8	sign	7E65B60DCFA42B043FCF57169867082C	数字签名

注：请求接口的method的值固定为：requestmessage

2．3 回调参数定义（生成结果列表）

序号	参数	参考值	意义	备注
1	method	callbackmessage	消息方法
2	format	json	消息体格式	或xml
3	version	1.0	版本
4	appkey	1234567890123456	商家的key
5	message	{"callback_message":{"message":{"result_msg":"成功！","total":2,"items":{"item":[{"codedata":"2342247913651296","trade_id":"30000287","file_url":"http://tb.ematong.com/gcert/upload/2342247913651296.gif"},{"codedata":"8114789713666421","trade_id":"30000288","file_url":"http://tb.ematong.com/gcert/upload/8114789713666421.gif"}]},"result_id":"00","req_flowno":"100100071"}}}	消息体内容
6	timestamp	2011-04-20 08:50:15	时间戳
7	sign	7E65B60DCFA42B043FCF57169867082C	数字签名

注：（1）回调消息的method的值固定为：callbackmessage，format与请求的格式相同。

（2）请求中的回调地址必须是有效地址，收到消息后必须返回：“true”。否则将每隔5秒发送一次，最多不超过三次。

2．4 流水号验证

流水号必须大于以前请求的流水号。

2．5 时间戳验证

时间戳取系统当前时间，超过5分钟的消息为无效请求。

2．6 签名验证

将请求参数按字母排序后，拼装成namevalue形式，并在首尾加上平台提供的密钥，再做MD5加密，并转为大写。

例如：将foo=1,bar=2,baz=3 排序为bar=2,baz=3,foo=1 

参数名和参数值链接后，得到拼装字符串bar2baz3foo1，然后在首尾加上平台提供的密钥6p9ft7excee9al3e7k3wssaho9ou1z6，再进行md5加密。

得到类似如下的结果：

6D2ED8801DF0004B67C694FBBC7AB508

3． 接口处理流程

 

 

4． 消息定义

消息，即接口参数中message的内容，包含具体需要执行的指令，和各项参数的数据规定。消息的格式目前支持json和xml两种，具体使用哪种格式，在请求或通知的参数中预以指定。请求时使用哪种格式，返回结果就使用哪种格式。

消息请求类型定义，对应于下面消息定义中req_type字段：

序号	请求类型（req_type）	意义	格式	备注
1	01	商品提交	文本
2	02	凭证生成和分发（无商品号）	文本	短彩信内容由用户系统构造
3	03	凭证生成（不分发）	文本
4	04	凭证使用查询	文本
5	05	凭证转发	文本
6	06	凭证重发	文本
7	07	凭证废除	文本
8	08	账单查询	文本
9	12	有商品号凭证生成和分发	文本	短彩信内容将获取商品信息
10	21	修改终端密码	文本	E链通专用
11	09	凭证同步	文本	已生成未收到回调时用
12	22	凭证生成和分发（无商品号）	文本	无回调，直接返回生成的凭证。
13	10	应用商店离线验证后，与通用平台进行验证同步	文本	软件商店专用

 

4.1 商品提交请求

提交商品目的是为了由平台构造短信/彩信内容，如果短信/彩信内容由用户系统构造，却不需要提交商品。

4.1.1 商品提交请求消息

<?xml version="1.0" encoding="UTF-8"?>

<request_message>

<message>

<req_type>01</req_type>

<organ_id></organ_id>

<num_iid>1011234578</num_iid>

<title>面包</title>

<price>1.20</price>

<pic_url>http://www.com.cn/iamge/g12343.jpg</mms_pic>

<server_print_text>终端打印的服务内容</server_print_text>

  <desc>商品描述</desc>

<detail_url>http://www.com.cn/goods.htm</detail_url>

</message>

</request_message>

 

Json格式：

{"request_message":

{"message":

{"req_type":"01","num_iid":"1011234578","title":"面包","price":"1.20","pic_url":"http://www.com.cn/image/g1234.jpg ","desc":"商品描述","server_print_text":"终端打印的服务内容","detail_url":" http://www.com.cn/goods.htm "}

}

}

 

Json格式与xml格式字段相同，以下不再列举。

 

消息字段意义：

字段	意义	类型	长度	允许空
request_message	消息头：请求消息	文本		N
message	消息体：消息内容	文本		N
req_type	请求类型: 01：商品提交请求	文本	2	N
organ_id	下属机构ID（可为空）	数字	6
num_iid	商品数字ID（每个商品必须唯一）	数字	30	N
title	商品简称	文本	100	N
price	价格	文本	10	N
pic_url	商品图片（图片格式必须为jpg）	文本	255
desc	商品描述	文本	255
server_print_text	终端机打印的服务内容	文本	255	N
detail_url	商品	文本	255

4.1.2 商品提交返回结果

<?xml version="1.0" encoding="UTF-8"?>

<response_message>

<message>

<result_id>00</result_id>

<result_msg>success</result_msg>

</message>

</response_message>

 

消息字段意义：

字段	意义	类型	长度	备注
Response_message	消息头：返回消息
Message	消息体：消息内容
Result_id	返回结果ID	数字	2
Result_msg	返回结果说明	文本	32

 

4.2 凭证的生成和分发(无商品号)

短信/彩信内容由用户系统自行设计或构造。

4.2.1 生成和分发请求消息

<?xml version="1.0" encoding="UTF-8"?>

<request_message>

<message>

<req_type>02</req_type>

<organ_id></organ_id>

<send_type>00</send_type>

<title>面包</title>

<price>2.20</price>

<mms_title>面包</mms_title>

<mms_content>凭此信息可至实体店兑换面包一份！有效期…</mms_content>

<sms_content>凭此信息可至实体店兑换面包一份！有效期…</sms_content>

<valid_start_time>2011-05-20 20:30:00</valid_start_time>

<valid_datetime>2011-05-20 20:30:00</valid_datetime>

<valid_times>1</valid_times>

<send_mobile>13612345678</send_mobile>

  <server_print_text>终端打印的服务内容</server_print_text>

  <send_total>2</send_total>

<rece_mobile>13612345678,13612345679</rece_mobile>

<type>0</type>

<callback_url>http://www.com.cn/callback</callback_url>

  <param1><param1>

<param2><param2>

<param3><param3>

<param4><param4>

<param5><param5>

</message>

</request_message>

 

请求消息字段意义：

字段	意义	类型	长度	允许空
request_message	消息头：请求消息			N
message	消息体：消息内容			N
req_type	请求类型: 02：交易请求	文本	32	N
organ_id	下属机构ID（没有下属机构不用填写）	数字	6
send_type	分发类型:00:彩信+短信（默认）；01：只发彩信；02：只发短信；11：只发短信码	文本	2	N
title	商品标题	文本	100	N
price	商品总价格（单价*valid_times）	文本	30	N
mms_title	彩信标题	文本	255	N
mms_content	彩信内容（可在内容中加入：{验证码}，作为验证放置的地方，缺省内容前面自动加上验证码）	文本	1024	N
sms_content	短信内容（可在内容中加入：{验证码}，作为验证放置的地方，缺省内容前面自动加上验证码）每条不超过70个字	文本	180	N
valid_start_time	验证开始时间yyyy-mm-dd hh:mm:ss	文本	19	Y
valid_datetime	验证截止时间yyyy-mm-dd hh:mm:ss	文本	19	N
valid_times	有效次数（可验证次数）	数字	3	N
send_mobile	发送手机号	文本	11	N
send_total	发送条数（上限：1000）	数字	4	N
rece_mobile	接收手机号（逗号分隔）	文本	11	N
server_print_text	终端机打印的服务内容	文本	255	N
type	回调类型：0：使用回调地址取结果；1：从客户端下载结果。	数字	1	N
callback_url	回调地址	文本	250	N
param1	可选参数1	文本	255	Y
param2	可选参数2	文本	255	Y
param3	可选参数3	文本	255	Y
param4	可选参数4	文本	255	Y
param5	可选参数5	文本	255	Y

注：

（1）短信彩信内容构造方法请参考：4.4.2 短信和彩信内容构造规则。

（2）回调地址必须是有效的地址，收到消息必须返回：“true”，否则每隔5秒重发一次，但最多不超过三次。（下同）

（3）终端打印的“服务内容”样式：（下同）

 

4.2.2 生成请求返回结果

<?xml version="1.0" encoding="UTF-8"?>

<response_message>

<message>

<result_id>00</result_id>

<result_msg>success</result_msg>

</message>

</response_message>

 

请求结果消息字段意义：

字段	意义	类型	长度	备注
Response_message	消息头：返回消息
Message	消息体：消息内容
Result_id	返回结果ID	数字	2
Result_msg	返回结果说明	文本	32

4.2.3 回调消息

<?xml version="1.0" encoding="UTF-8"?>

<callback_message>

<message>

<result_id>00</result_id>

<result_msg>success</result_msg>

<req_flowno>10000101</req_flowno>

<total>2</total>

<items>

<item>

<organ_id></organ_id>

<trade_id>10000101</trade_id>

<codedata>7021764460328234<codedata>

<file_url>http://www.ecode.com/pz/upload/7021764460328234.gif<file_url>

<rece_mobile>13612345678</rece_mobile>

</item>

<item>

<organ_id></organ_id>

<trade_id>10000102</trade_id>

<codedata>7021764460328212<codedata>

<file_url>http://www.ecode.com/pz/upload/7021764460328212.gif<file_url>

<rece_mobile>13612345679</rece_mobile>

</item>

</items>

</message>

</callback_message>

 

回调消息字段意义

字段	意义	类型	长度	备注
callback _message	消息头：回调消息
message	消息体：消息内容
result_id	返回结果ID	数字	2
result_msg	返回结果说明	文本	32
req_flowno	请求流水号	数字	32	对应请求的流水号
total	列表总数	数字	4
items	列表标签	文本
item	条目标签	文本
trade_id	系统生成的交易流水号	数字	32	可作为凭证或账务查询
codedata	二维码	数字	16
file_url	二维码文件	文本	250
rece_mobile	接收手机	数字	11

 

4.3 凭证的生成 (不分发)

只生成凭证，不发短信和彩信。

4.3.1 生成请求消息

<?xml version="1.0" encoding="UTF-8"?>

<request_message>

<message>

<req_type>03</req_type>

  <organ_id></organ_id>

<send_total>2</send_total>

<title>面包</title>

<price>2.20</price>

<server_print_text>终端打印的服务内容</server_print_text>

<valid_start_time>2011-05-20 20:30:00</valid_start_time>

<valid_datetime>2011-05-20 20:30:00</valid_datetime>

<valid_times>1</valid_times>

<send_total>2</send_total>

<type>0</type>

<callback_url>http://www.com.cn/callback</callback_url>

<param1><param1>

<param2><param2>

<param3><param3>

<param4><param4>

<param5><param5>

</message>

</request_message>

 

消息字段意义：

字段	意义	类型	长度	允许空
request_message	消息头：请求消息			N
message	消息体：消息内容			N
req_type	请求类型: 03：交易请求	文本	32	N
organ_id	下属机构ID（没有下属机构不用填写）	数字	6
send_type	分发类型:00:彩信+短信（默认）；01：只发彩信；02：只发短信；11：只发短信码	文本	2	N
send_total	生成条数	数字	32	N
title	商品简称	文本	100	N
price	商品价格	文本	30	N
server_print_text	服务内容	文本	255	N
valid_start_time	验证开始时间yyyy-mm-dd hh:mm:ss	文本	19	Y
valid_datetime	验证截止时间yyyy-mm-dd hh:mm:ss	文本	19	N
valid_times	可验证次数	数字	3	N
send_total	生成条数（上限：1000）	数字	4	N
type	回调类型：0：使用回调地址取结果；1：从客户端下载结果。	数字	1	N
callback_url	回调地址	文本	250	N
param1	可选参数1： “one”: 不回调，将生成的凭证直接返回，Callback_url地址为空。	文本	255	Y
param2	可选参数2	文本	255	Y
param3	可选参数3	文本	255	Y
param4	可选参数4	文本	255	Y
param5	可选参数5	文本	255	Y

4.3.2 生成请求返回结果

<?xml version="1.0" encoding="UTF-8"?>

<response_message>

<message>

<result_id>00</result_id>

<result_msg>成功！</result_msg>

</message>

</response_message>

如果是无回调的返回：

<?xml version="1.0" encoding="UTF-8"?>

<callback_message>

<message>

<result_id>00</result_id>

<result_msg>成功！</result_msg>

<req_flowno>10000101</req_flowno>

<total>2</total>

<items>

<item>

<organ_id></organ_id>

<trade_id>10000101</trade_id>

<codedata>7021764460328234<codedata>

<file_url>http://www.ecode.com/pz/upload/7021764460328234.gif<file_url>

</item>

<item>

<organ_id></organ_id>

<trade_id>10000102</trade_id>

<codedata>7021764460328212<codedata>

<file_url>http://www.ecode.com/pz/upload/7021764460328212.gif<file_url>

</item>

</items>

</message>

</callback_message>

 

 

消息字段意义：无回调的字段意义请参考回调的字段意义

字段	意义	类型	长度	备注
Response_message	消息头：返回消息
Message	消息体：消息内容
Result_id	返回结果ID	数字	2
Result_msg	返回结果说明	文本	32

4.3.3 回调消息

<?xml version="1.0" encoding="UTF-8"?>

<callback_message>

<message>

<result_id>00</result_id>

<result_msg>成功！</result_msg>

<req_flowno>10000101</req_flowno>

<total>2</total>

<items>

<item>

<organ_id></organ_id>

<trade_id>10000101</trade_id>

<codedata>7021764460328234<codedata>

<file_url>http://www.ecode.com/pz/upload/7021764460328234.gif<file_url>

</item>

<item>

<organ_id></organ_id>

<trade_id>10000102</trade_id>

<codedata>7021764460328212<codedata>

<file_url>http://www.ecode.com/pz/upload/7021764460328212.gif<file_url>

</item>

</items>

</message>

</callback_message>

 

回调消息字段意义

字段	意义	类型	长度	备注
callback _message	消息头：回调消息
message	消息体：消息内容
result_id	返回结果ID	数字	2
result_msg	返回结果说明	文本	32
req_flowno	请求流水号	数字	32	对应请求的流水号
total	列表总数	数字	4
items	列表标签	文本
item	条目标签	文本
trade_id	系统生成的交易流水号	数字	32	可作为凭证或账务查询
codedata	二维码	数字	16
file_url	二维码文件	文本	250

 

 

4.4 凭证的生成和分发(有商品号)

短信/彩信内容按商品信息，由平台按一定的规则构造。

4.4.1 生成和分发请求消息

<?xml version="1.0" encoding="UTF-8"?>

<request_message>

<message>

<req_type>12</req_type>

  <organ_id></organ_id>

<num_iid>1121356987</num_iid>

<send_type>00</send_type>

<valid_start_time>2011-05-20 20:30:00</valid_start_time>

<valid_datetime>2011-05-20 20:30:00</valid_datetime>

<valid_times>1</valid_times>

<send_mobile>13612345678</send_mobile>

<send_total>2</send_total>

<rece_mobile>13612345678,13612345679</rece_mobile>

<phrase>给接收者的祝福语</phrase>

<type>0</type>

<callback_url>http://www.com.cn/callback</callback_url>

<param1><param1>

<param2><param2>

<param3><param3>

<param4><param4>

<param5><param5>

</message>

</request_message>

 

消息字段意义：

字段	意义	类型	长度	允许空
request_message	消息头：请求消息			N
message	消息体：消息内容			N
req_type	请求类型: 12：交易请求	文本	32	N
organ_id	下属机构ID（可为空）	数字	6
num_iid	商品ID	数字	32	N
send_type	分发类型:00:彩信+短信（默认）；01：只发彩信；02：只发短信；11：只发短信码	文本	2	N
valid_start_time	验证开始时间yyyy-mm-dd hh:mm:ss	文本	19	Y
valid_datetime	验证截止时间yyyy-mm-dd hh:mm:ss	文本	19	N
valid_times	有效次数（可验证次数）	数字	3	N
send_mobile	发送手机号	文本	11	N
send_total	发送条数（上限：1000）	数字	4	N
rece_mobile	接收手机号，以逗号分隔（手机数必须与发送条数相同）	文本	11	N
phrase	祝福语	文本	255	N
type	回调类型：0：使用回调地址取结果；1：从客户端下载结果。	数字	1	N
callback_url	回调地址	文本	250	N
param1	可选参数1	文本	255	Y
param2	可选参数2	文本	255	Y
param3	可选参数3	文本	255	Y
param4	可选参数4	文本	255	Y
param5	可选参数5	文本	255	Y

4.4.2 短信和彩信内容构造规则

1．短信内容规范

格式： 

[{验证码}]您的手机号为{send_mobile}的朋友{phrase}凭此信息可至{servarea}兑换{title}一份！有效期截至{ valid_datetime }，过期无效。更多服务信息，请登录{shop_title}（网址：{shop_url}）

范例：

 

2．彩信内容范例

文字内容格式同短信。

范例：

 

4.4.3 生成请求返回结果

<?xml version="1.0" encoding="UTF-8"?>

<response_message>

<message>

<result_id>00</result_id>

<result_msg>success</result_msg>

</message>

</response_message>

 

消息字段意义：

字段	意义	类型	长度	备注
response_message	消息头：返回消息
message	消息体：消息内容
result_id	返回结果ID	数字	2
result_msg	返回结果说明	文本	32

4.4.4 回调消息

<?xml version="1.0" encoding="UTF-8"?>

<callback_message>

<message>

<result_id>00</result_id>

<result_msg>success</result_msg>

<req_flowno>10000101</req_flowno>

<total>2</total>

<items>

<item>

<organ_id></organ_id>

<trade_id>10000101</trade_id>

<codedata>7021764460328234<codedata>

<file_url>http://www.ecode.com/pz/upload/7021764460328234.gif<file_url>

<rece_mobile>13612345678</rece_mobile>

</item>

<item>

<organ_id></organ_id>

<trade_id>10000102</trade_id>

<codedata>7021764460328212<codedata>

<file_url>http://www.ecode.com/pz/upload/7021764460328212.gif<file_url>

<rece_mobile>13612345679</rece_mobile>

</item>

</items>

</message>

</callback_message>

 

回调消息字段意义

字段	意义	类型	长度	备注
callback _message	消息头：回调消息
message	消息体：消息内容
result_id	返回结果ID	数字	2
result_msg	返回结果说明	文本	32
req_flowno	请求流水号	数字	32	对应请求的流水号
total	列表总数	数字	4
items	列表标签	文本
item	条目标签	文本
trade_id	系统生成的交易流水号	数字	32	可作为凭证或账务查询
codedata	二维码	数字	16
file_url	二维码文件	文本	250
rece_mobile	接收手机	数字	11

 

4.5 凭证使用查询

4．5．1 凭证使用查询消息

<?xml version="1.0" encoding="UTF-8"?>

<request_message>

<message>

<req_type>04</req_type>

  <organ_id></organ_id>

<trade_id></trade_id>

<posno><posno>

<fields>trade_id,send_mobile,rece_mobile,send_type,order_status,posno,code,resend_times, createtime,valid_datetime,valid_times,cert_status</fields>

<start_time>2011-04-10 00:00:00</start_time>

<end_time>2011-04-11 23:59:59</end_time>

<page_no>1</send_type>

<page_size>10</page_size>

</message>

</request_message>

 

消息字段意义：

字段		意义	类型	长度	允许空
request_message		消息头：请求消息			N
message		消息体：消息内容			N
req_type		请求类型: 04：查询请求	文本	32	N
organ_id	下属机构id（可为空）		数字	6
trade_id		交易ID：非空按ID查询，为空按页查询	数字	32
posno		终端号：非空查询该终端号所验证的凭证	文本	32
fields		查询字段(可选)	文本	255	N
start_time		开始时间yyyy-mm-dd hh:mm:ss	文本	20	N
end_time		结束时间yyyy-mm-dd hh:mm:ss	文本	20	N
page_no		页码	数字	2	N
page_size		每页行数	数字	3	N

 

查询字段fields意义：

字段		意义	类型	长度	备注
organ_id	下属机构ID		数字	6
trade_id		交易序列号	数字	32
send_mobile		发送手机号	文本	11
rece_mobile		接收手机号	文本	11
send_type		发送类型	文本	2
order_status		订单状态	文本	32
posno		验证终端号	文本	32
code		二维码	文本	16
resend_times		重发次数	数字	2
createtime		交易创建时间	日期时间	19
valid_date		有效期	日期时间	19
valid_times		可验证次数	数字	2
cert_status		凭证使用状态	文本	32

 

4．5．2 凭证使用查询结果

1．Xml格式结果

<?xml version="1.0" encoding="UTF-8"?>

<response_message>

<message>

<result_id>00</result_id>

<result_msg>Success!</result_msg>

<total>2</total>

<items>

<item>

<organ_id></organ_id>

<code>8581513016655648</code>

<cert_status>已验证</cert_status>

<send_type>00</send_type>

<send_mobile>13512345678</send_mobile>

<valid_times>5</valid_times>

<resend_times>0</resend_times>

<posno>00005464</posno>

<rece_mobile>13600128800</rece_mobile>

<order_status>已验证</order_status>

<createtime>2011-05-16 12:18:34</createtime>

<trade_id>30000102</trade_id>

<valid_datetime>2011-06-10 12:10:00</valid_datetime>

</item>

<item>

<organ_id></organ_id>

<code>7132815521647540</code>

<cert_status>已验证</cert_status>

<send_type></send_type>

<send_mobile></send_mobile>

<valid_times>1</valid_times>

<resend_times>0</resend_times>

<posno>00005464</posno>

<rece_mobile></rece_mobile>

<order_status>已验证</order_status>

<createtime>2011-05-16 12:00:03</createtime>

<trade_id>30000101</trade_id>

<valid_datetime>2011-06-10 12:10:00</valid_datetime>

</item>

</items>

</message>

</response_message>

 

2．Json格式结果

{"response_message":{"message":{"result_msg":"Success!","total":2,"items":{"item":[{"code":"8581513016655648","cert_status":"已验证","send_type":"00","send_mobile":"13512345678","valid_times":5,"resend_times":0,"posno":"00005464","rece_mobile":"13600128800","order_status":"已验证","createtime":"2011-05-16 12:18:34","trade_id":"30000102","valid_datetime":"2011-06-10 12:10:00"},{"code":"7132815521647540","cert_status":"已验证","send_type":null,"send_mobile":null,"valid_times":1,"resend_times":0,"posno":"00005464","rece_mobile":null,"order_status":"已验证","createtime":"2011-05-16 12:00:03","trade_id":"30000101","valid_datetime":"2011-06-10 12:10:00"}]},"result_id":"00"}}}

 

消息字段意义：

字段	意义	类型	长度	备注
response_message	消息头：返回消息
message	消息体：消息内容
result_id	返回结果ID	文本	2
result_msg	返回结果说明	文本	32
total	查询结果条数	数字
items	列表	List
item	列表数据	字段数据

注：列表将以交易创建时间的倒序排列，即最后的交易排在最前面。返回字段以请求的fields字段为准。

4.6 凭证的转发

4.6.1 转发请求消息

<?xml version="1.0" encoding="UTF-8"?>

<request_message>

<message>

<req_type>05</req_type>

<trade_id>10012</trade_id>

<send_type>00</send_type>

<mms_title>面包</mms_title>

<mms_content>凭此信息可至实体店兑换面包一份！有效期…</mms_content>

<sms_content>凭此信息可至实体店兑换面包一份！有效期…</sms_content>

<rece_mobile>13612345678</rece_mobile>

</message>

</request_message>

 

 

消息字段意义：

字段		意义	类型	长度	允许空
request_message		消息头：请求消息			N
message		消息体：消息内容			N
req_type		请求类型: 05：转发	文本	32	N
trade_id		交易ID	数字	32	N
mms_title		彩信标题	文本	255	N
mms_content	彩信内容（可在内容中加入：{验证码}，作为验证放置的地方，缺省内容前面自动加上验证码）		文本	1024	N
sms_content	短信内容（可在内容中加入：{验证码}，作为验证放置的地方，缺省内容前面自动加上验证码）每条不超过70个字		文本	130	N
rece_mobile		接收手机号	文本	11	N

注：使用原来的发送内容转给其它接收者。

4.6.2 转发请求结果

<?xml version="1.0" encoding="UTF-8"?>

<response_message>

<message>

<result_id>00</result_id>

<result_msg>success</result_msg>

</message>

</response_message>

 

消息字段意义：

字段	意义	类型	长度	备注
response_message	消息头：返回消息
message	消息体：消息内容
result_id	返回结果ID	数字	2
result_msg	返回结果说明	文本	32

 

4.7 凭证的重发

4.7.1 凭证重发请求

<?xml version="1.0" encoding="UTF-8"?>

<request_message>

<message>

<req_type>06</req_type>

<trade_id>10012</trade_id>

<send_type>00</send_type>

<mms_title>面包</mms_title>

<mms_content>凭此信息可至实体店兑换面包一份！有效期…</mms_content>

<sms_content>凭此信息可至实体店兑换面包一份！有效期…</sms_content>

</message>

</request_message>

 

 

消息字段意义：

字段		意义	类型	长度	允许空
request_message		消息头：请求消息			N
message		消息体：消息内容			N
req_type		请求类型: 06：重发请求	文本	32	N
trade_id		交易ID	数字	32	N
mms_title		彩信标题	文本	255	N
mms_content	彩信内容（可在内容中加入：{验证码}，作为验证放置的地方，缺省内容前面自动加上验证码）		文本	1024	N
sms_content	短信内容（可在内容中加入：{验证码}，作为验证放置的地方，缺省内容前面自动加上验证码）每条不超过70个字		文本	130	N

 

 

4.7.2 重发请求返回结果

<?xml version="1.0" encoding="UTF-8"?>

<response_message>

<message>

<result_id>00</result_id>

<result_msg>success</result_msg>

</message>

</response_message>

 

消息字段意义：

字段	意义	类型	长度	备注
response_message	消息头：返回消息
message	消息体：消息内容
result_id	返回结果ID	数字	2
result_msg	返回结果说明	文本	32

 

4.8 凭证的废除

4.8.1 凭证废除请求

<?xml version="1.0" encoding="UTF-8"?>

<request_message>

<message>

<req_type>07</req_type>

<trade_id>10012</trade_id>

</message>

</request_message>

 

 

消息字段意义：

字段	意义	类型	长度	允许空
request_message	消息头：请求消息			N
message	消息体：消息内容			N
req_type	请求类型: 07：废除请求	文本	32	N
trade_id	交易ID	数字	32	N

 

 

4.8.2 废除请求返回结果

<?xml version="1.0" encoding="UTF-8"?>

<response_message>

<message>

<result_id>00</result_id>

<result_msg>success</result_msg>

</message>

</response_message>

 

消息字段意义：

字段	意义	类型	长度	备注
response_message	消息头：返回消息
message	消息体：消息内容
result_id	返回结果ID	数字	2
result_msg	返回结果说明	文本	32

 

4.9 账单查询

4．9．1 账单查询消息

<?xml version="1.0" encoding="UTF-8"?>

<request_message>

<message>

<req_type>08</req_type>

  <organ_id></organ_id>

<fields>flowno,posno,status,type,inpay,num,amount,createtime</fields>

<type>1</type>

<page_no>1</send_type>

<page_size>10</page_size>

</message>

</request_message>

 

消息字段意义：

字段		意义	类型	长度	允许空
request_message		消息头：请求消息			N
message		消息体：消息内容			N
req_type		请求类型: 08：查询请求	文本	32	N
organ_id	下属机构id（可为空）		数字	6
fields		查询字段	文本	255	N
type		查询类型：1：凭证；2：彩信；3：短信；4：验证	数字	1	N
page_no		页码	数字	2	N
page_size		每页行数	数字	11	N

 

查询字段fields意义：

字段	意义	类型	长度	备注
flowno	请求流水号	数字	32
posno	终端号	数字	32
status	说明	文本	32
type	类别	文本	16	凭证；彩信；短信；验证
inpay	收支	文本	16	充值；支出
num	数量	数字	10
amount	余额	数字	10
createtime	账单日期	日期时间	20

 

4．9．2 账单查询结果

1．Xml格式结果

<?xml version="1.0" encoding="UTF-8"?>

<response_message>

<message>

<result_id>00</result_id>

<result_msg>Success!</result_msg>

<total>2</total>

<items>

<item>

<num>1000</num>

<amount>1104</amount>

<type>凭证</type>

<inpay>充值</inpay>

<posno></posno>

<status>凭证充值</status>

<createtime>2011-05-25 16:39:44</createtime>

<flowno></flowno>

</item>

<item>

<num>1000</num>

<amount>104</amount>

<type>凭证</type>

<inpay>支出</inpay>

<posno></posno>

<status>凭证支出</status>

<createtime>2011-05-25 16:33:16</createtime>

<flowno>20001206</flowno>

</item>

</items>

</message>

</response_message>

2．Json格式结果

{"response_message":{"message":{"result_msg":"Success!","total":2,"items":{"item":[{"num":1000,"amount":1104,"type":"凭证","inpay":"充值","posno":null,"status":"凭证充值","createtime":"2011-05-25 16:39:44","flowno":null},{"num":1000,"amount":104,"type":"凭证","inpay":"支出","posno":null,"status":"凭证支出","createtime":"2011-05-25 16:33:16","flowno":"20001206"}]},"result_id":"00"}}}

 

消息字段意义：

字段	意义	类型	长度	备注
response_message	消息头：返回消息
message	消息体：消息内容
result_id	返回结果ID	文本	2
result_msg	返回结果说明	文本	32
total	查询结果条数	数字
items	列表	List
item	列表内容	字段与值

4.10 通知消息

凭证状态发生变化，即凭证使用时，平台将以通知的形式，给用户系统发送变更消息。通知的回调地址，可在商家信息修改中进行管理。

通知消息的处理方法同回调消息处理。

4.10.1 消息头

消息头字段定义：

序号	参数	参考值	意义	备注
1	method	notifymessage	消息方法
2	format	json	消息体格式
3	version	1.0	版本
4	appkey	1234567890123456	商家的key
5	message	{"notify_message":{"message":{"organid":1,"valid_times":2,"posno":"00005464","rece_mobile":"13600128603","status":"已验证","codedata":"7852529514792243","trade_id":"30000346","valid_date":"2011-06-08 13:56:37"}}}	消息体内容
6	timestamp	2011-04-20 08:50:15	时间戳
7	sign	7E65B60DCFA42B043FCF57169867082C	数字签名

注：（1）通知消息的mothod固定为：notifymessage

（2）消息只有一种格式：json

（3）用户系统接收到消息必须返回：true。否则消息将每隔5秒发送一次，但最多不超过三次。

4.10.2 消息体

消息体例子：

{"notify_message":{"message":{"organid":1,"valid_times":2,"posno":"00005464","rece_mobile":"13600128603","status":"已验证","codedata":"7852529514792243","trade_id":"30000346","valid_date":"2011-06-08 13:56:37"}}}

 

消息体字段定义：

字段	意义	类型	长度	备注
notify _message	消息头：通知消息
message	消息体：消息内容
trade_id	系统生成的交易流水号	数字	32	可作为凭证或账务查询
codedata	二维码	数字	16
status	使用状态	文本	250
rece_mobile	接收者手机	数字	11
valid_date	验证时间	日期时间	19
valid_times	已验证次数	数字	2
valid_num	未验证次数	数字	2
valid_curr	当前验证次数	数字
organid	下属机构	数字	32
posno	终端编号	数字	32
param1	可选参数1	文本	255
param2	可选参数2	文本	255
param3	可选参数3	文本	255
param4	可选参数4	文本	255
param5	可选参数5	文本	255
param6	可选参数6	文本	255

4.11 凭证同步

凭证已经生成，由于网络原因或者没有申请回调消息，可以提供请求的流水号同步生成的凭证。特别注意：消息的格式必须和请求凭证时的格式相同。

4．11．1 请求消息

<?xml version="1.0" encoding="UTF-8"?>

<request_message>

<message>

<req_type>09</req_type>

  <param1>123456</param1>

</message>

</request_message>

 

消息字段意义：

字段		意义	类型	长度	允许空
request_message		消息头：请求消息			N
message		消息体：消息内容			N
req_type		请求类型: 09：凭证同步	文本	32	N
param1	生成请求时的流水号		文本	32	N

 

4．11．2 返回结果

返回结果与回调消息类似：

<?xml version="1.0" encoding="UTF-8"?>

<response_message>

<message>

<result_id>00</result_id>

<result_msg>成功！</result_msg>

<req_flowno>10000101</req_flowno>

<total>2</total>

<items>

<item>

<organ_id></organ_id>

<trade_id>10000101</trade_id>

<codedata>7021764460328234<codedata>

<file_url>http://www.ecode.com/pz/upload/7021764460328234.gif<file_url>

</item>

<item>

<organ_id></organ_id>

<trade_id>10000102</trade_id>

<codedata>7021764460328212<codedata>

<file_url>http://www.ecode.com/pz/upload/7021764460328212.gif<file_url>

</item>

</items>

</message>

</response_message>

 

回调消息字段意义

字段	意义	类型	长度	备注
response_message	消息头：返回消息
message	消息体：消息内容
result_id	返回结果ID	数字	2
result_msg	返回结果说明	文本	32
req_flowno	请求流水号	数字	32	对应请求的流水号
total	列表总数	数字	4
items	列表标签	文本
item	条目标签	文本
trade_id	系统生成的交易流水号	数字	32	可作为凭证或账务查询
codedata	二维码	数字	16
file_url	二维码文件	文本	250

 

 

4.12 凭证的生成和分发(无商品号，无回调)

此方法与4.2的方法的区别是本方法没有回调，直接返回生成的凭证。使用本方法应尽量避免一次生成多条，以免处理时间过长，造成连接超时。短信/彩信内容由用户系统自行设计或构造。

4.12.1请求消息

<?xml version="1.0" encoding="UTF-8"?>

<request_message>

<message>

<req_type>22</req_type>

<organ_id></organ_id>

<send_type>00</send_type>

<title>面包</title>

<price>2.20</price>

<mms_title>面包</mms_title>

<mms_content>凭此信息可至实体店兑换面包一份！有效期…</mms_content>

<sms_content>凭此信息可至实体店兑换面包一份！有效期…</sms_content>

<valid_start_time>2011-05-20 20:30:00</valid_start_time>

<valid_datetime>2011-05-20 20:30:00</valid_datetime>

<valid_times>1</valid_times>

<send_mobile>13612345678</send_mobile>

  <server_print_text>终端打印的服务内容</server_print_text>

  <send_total>2</send_total>

<rece_mobile>13612345678,13612345679</rece_mobile>

<type>0</type>

<param1><param1>

<param2><param2>

<param3><param3>

<param4><param4>

<param5><param5>

</message>

</request_message>

 

请求消息字段意义：

字段	意义	类型	长度	允许空
request_message	消息头：请求消息			N
message	消息体：消息内容			N
req_type	请求类型: 22：交易请求	文本	32	N
organ_id	下属机构ID（没有下属机构不用填写）	数字	6
send_type	分发类型:00:彩信+短信（默认）；01：只发彩信；02：只发短信	文本	2	N
title	商品标题	文本	100	N
price	商品价格	文本	30	N
mms_title	彩信标题	文本	255	N
mms_content	彩信内容（可在内容中加入：{验证码}，作为验证放置的地方，缺省内容前面自动加上验证码）	文本	1024	N
sms_content	短信内容（可在内容中加入：{验证码}，作为验证放置的地方，缺省内容前面自动加上验证码）每条不超过70个字	文本	130	N
valid_start_time	验证开始时间yyyy-mm-dd hh:mm:ss	文本	19	Y
valid_datetime	验证截止时间yyyy-mm-dd hh:mm:ss	文本	19	N
valid_times	有效次数（可验证次数）	数字	1	N
send_mobile	发送手机号	文本	11	N
send_total	发送条数（上限：1000）	数字	4	N
rece_mobile	接收手机号（逗号分隔）	文本	11	N
server_print_text	终端机打印的服务内容	文本	255	N
type	回调类型：0：使用回调地址取结果；1：从客户端下载结果。	数字	1	N
param1	可选参数1	文本	255	Y
param2	可选参数2	文本	255	Y
param3	可选参数3	文本	255	Y
param4	可选参数4	文本	255	Y
param5	可选参数5	文本	255	Y

注：

（1）短信彩信内容构造方法请参考：4.4.2 短信和彩信内容构造规则。

（2）终端打印的“服务内容”样式：（下同）

 

4.12.2 生成请求返回结果

<?xml version="1.0" encoding="UTF-8"?>

<response_message>

<message>

<result_id>00</result_id>

<result_msg>success</result_msg>

<req_flowno>10000101</req_flowno>

<total>2</total>

<items>

<item>

<organ_id></organ_id>

<trade_id>10000101</trade_id>

<codedata>7021764460328234<codedata>

<epass><epass>

<file_url>http://www.ecode.com/pz/upload/7021764460328234.gif<file_url>

<rece_mobile>13612345678</rece_mobile>

</item>

<item>

<organ_id></organ_id>

<trade_id>10000102</trade_id>

<codedata>7021764460328212<codedata>

<epass><epass>

<file_url>http://www.ecode.com/pz/upload/7021764460328212.gif<file_url>

<rece_mobile>13612345679</rece_mobile>

</item>

</items>

</message>

</response_message>

 

请求结果消息字段意义：

字段	意义	类型	长度	备注
response_message	消息头：返回消息
message	消息体：消息内容
result_id	返回结果ID	数字	2
result_msg	返回结果说明	文本	32
req_flowno	请求流水号	数字	32	对应请求的流水号
total	列表总数	数字	4
items	列表标签	文本
item	条目标签	文本
trade_id	系统生成的交易流水号	数字	32	可作为凭证或账务查询
organ_id	机构号	数字	32
codedata	二维码	数字	16
epass	tcode码	文本(文本图形)	32
file_url	二维码文件	文本	250
rece_mobile	接收手机	数字	11

 

 

 

 

4.13 离线验证，凭证同步（软件商店专用）

将应用商店已经离线验证的验证码发送过来进行同步。

4.13.1请求消息

XML格式:

<?xml version="1.0" encoding="UTF-8"?>

<request_message>

<message>

<req_type>10</req_type>

<items>

<item>

<codedata>1234567890123456</codedata>

<organid>1234</organid>

<posno>1234</posno>

<validdate>2011-12-1 10:00:00</validdate>

<validtimes>1</validtimes>

</item>

<item>

<codedata>1234567890123456</codedata>

<organid>1234</organid>

<posno>1234</posno>

<validdate>2011-12-1 10:00:00</validdate>

<validtimes>1</validtimes>

</item>

</items>

<param1></param1>

<param2></param2>

<param3></param3>

<param4></param4>

<param5></param5>

</message>

</request_message>

JSON格式：

{"request_message":

   {"message":

    {

    "req_type":"10",

    "items":

    [

    {

    "organid":"", 

    "posno":"123456", 

    "codedata":"1234567890123456", 

    "validtimes":"1", 

    "validdate":"2011-11-30 00:00:00"

    }, 

    {

    "organid":"", 

    "posno":"123456", 

    "codedata":"1234567890123456", 

    "validtimes":"1", 

    "validdate":"2011-11-30 00:00:00"

    }

    ]

    }

    }

}

 

请求消息字段意义：

字段	意义	类型	长度	允许空
Request_message	消息头：请求消息			N
Message	消息体：消息内容			N
Req_type	请求类型: 10	文本	2	N
codedata	验证码	文本	16	N
Organ_id	下属机构ID（没有下属机构不用填写）	数字	6	Y
posno	终端号	数字	32	N
validdate	验证时间yyyy-mm-dd hh:mm:ss	文本	19	N
validtimes	验证次数	数字	1	N
Param1	可选参数1	文本	255	Y
Param2	可选参数2	文本	255	Y
Param3	可选参数3	文本	255	Y
Param4	可选参数4	文本	255	Y
Param5	可选参数5	文本	255	Y

4.13.2返回结果

<?xml version="1.0" encoding="UTF-8"?>

<response_message>

<message>

<result_id>00</result_id>

<result_msg>success</result_msg>

<req_flowno>10000101</req_flowno>

</message>

</response_message>

请求结果消息字段意义：

字段	意义	类型	长度	备注
response_message	消息头：返回消息
message	消息体：消息内容
result_id	返回结果ID	数字	2
result_msg	返回结果说明	文本	32
req_flowno	请求流水号	数字	32	对应请求的流水号

 

5. 结果提示定义

结果ID	意义	备注
00	成功	Success
01	签名失败	Sign error
02	请求超时	Time out
03	流水号错误	Flowno error
04	请求方法错误	Method error
05	查询字段错误	Fields error
06	查询超出限制数	Page out
07	系统数据错误	Data error
08	参数错误	Param error
09	余额不足	Insufficient funds
10	消息内容不合法：发送条数与手机数不相符	Message error
11	商品号对应商品不存在	Goods no exist
12	超出生成限制条数	Trade sum out
13	下属机构不存在	Organ no exist

posted on 2014-04-13 16:05 方维二次开发 阅读(…) 评论(…) 编辑 收藏

转载于:https://www.cnblogs.com/wangtongphp/p/3662357.html