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