ecstore接口文档指导规则.doc

数据中心接口阐明
目录
数据中心接口阐明 1
目录 1
更新日记 3
1. 祈求参数阐明 3
1.1. 接口域名阐明 3
1.2. format 参数阐明 3
1.3. 接口访问权限 3
1.3.1. pid 参数阐明 3
1.3.2. 签名参数 3
2. 返回数据阐明 5
2.1. 返回数据分4某些 5
3. 异常(错误码)阐明 5
4. 门票列表接口 6
4.1. 接口地址 6
4.2. 祈求类型 6
4.3. 输入参数 6
4.4. 返回成果 6
4.5. 调用示例 8
4.6. 返回json格式示例 8
4.7. 返回xml格式示例 9
5. 订单列表 10
5.1. 接口地址 10
5.2. 祈求类型 10
5.3. 输入参数 11
5.4. 返回成果 11
5.5. 调用示例 12
5.6. 返回json格式示例 12
5.7. 返回xml格式示例 13
6. 下单发票接口 14
6.1. 接口地址 14
6.2. 输入参数 14
6.3. 返回成果 15
6.4. 返回json格式示例 16
6.5. 返回xml格式示例 16
7. 退票接口 17
7.1. 接口地址 17
7.2. 输入参数 17
7.3. 返回成果 18
7.4. 返回json格式示例 18
7.5. 返回xml格式示例 19
8. 验证告知 19
8.1. 告知参数 19
8.2. 返回成果 19
8.3. 返回json格式示例 20
8.4. 返回xml格式示例 20

更新日记
日期
版本
阐明
作者
-03-15
1.0
创立文档
莫灿宽
-03-22
1.0
添加退票接口
莫灿宽
-03-27
1.0
下单接口添加开始游玩日期和价格类型参数
莫灿宽
-05-08
1.0
下单接口返回信息中添加二维码参数qrcode
莫灿宽

1. 祈求参数阐明
1.1. 接口域名阐明
为了阐明以便我这里都假定接口域名是xxx.xxx.xxx。实际使用中如果是其她域名只需将相应域名代替xxx.xxx.xxx即可
1.2. format 参数阐明
指定接口返回格式。重要包括三种格式：xml、json、php。如果未显式调用format参数，默认返回json格式。详细返回格式可查看详细接口返回示例
获取xml格式
获取json格式

1.3. 接口访问权限
合伙伙伴如果要访问接口至少要提供_pid和签名（签名是由授权码和参数生成）
1.3.1. pid 参数阐明
每个接口都需要_pid参数，这是合伙伙伴编号，在此文档中有时叫合伙伙伴id.
1.3.2. 签名参数
还需要签名来验证祈求合法性。签名生成规则：
md5(md5('param1=value1&param2=value2&param3=value3').$authcode)
md5：加密算法，32位md5算法
$authcode：授权码
param1=value1&param2=value2&param3=value3：传递给接口参数。各种参数用&连接
注：
1，所有参数(除_sig参数)需要按照键名英文排好顺序。
2，参数规定：除_sig参数自身以外所有其她参加祈求接口参数。
3，其中‘.’号表达连接符号，即连接各种字符串。请勿理解成可见字符
4，$authcode是授权码，即账号密码。
5，什么参数被用来生产签名参数：如果使用GET方式祈求，则使用GET参数。如果使用POST方式祈求，则使用POST参数。两者只用其一
php中生成签名示例：
// 祈求参数
$params = array(
'cid' => 1,
'_pid' => 1,
'format' => 'xml',
);
$authCode = 123456；// 授权码

// 生成祈求参数 cid=1&format=xml&pid=10000
ksort($params)；// 参数排好序(多维数组时请自行递归)
$query = http_build_query($params);

// 生成签名 7523690af2ccdf3f3ef595de68e86829
// $sig = md5( md5( “_pid=1&cid=1&format=xml” ) . “123456” )
$sig = md5( md5( $query ) . $authCode )；
// 调用接口形式：

祈求有4个参数，咱们排除_sig自身。使用cid,pid,format来生成签名。format不是必要。授权码（$authCode）是123456。如果不传递format,则签名是：md5( md5( “_pid=1&cid=1” ) . “123456” )。
2. 返回数据阐明
2.1. 返回数据分4某些
1） success：表成功和失败状态。true表成功，false表失败。
2） message：提示信息，当有错误发生时，此message包具有错误信息
3） errorn：错误码，当有错误发生时，此errorn包具有错误码号
4） 返回数据:
如果是获取多条信息类接口则:
list：多条信息列表
total：数据总数
如果是获取单条信息类接口则:
info：单条信息
3. 异常(错误码)阐明
1） 300500 => 没有数据
2） 300501 => 参数错误
3） 300502 => 顾客不存在
4） 300503 => 顾客未开通接口授权
5） 300504 => 授权码错误
6） 300505 => 票不存在
7） 300506 => 票已过期
8） 300507 => 票数局限性
9） 300508 => 获取分销商分组失败
10） 300509 => 获取景区失败
11） 300510 => 余额局限性
12） 300511 => 短信发送失败
13） 300512 => 余额更新失败
14） 300513 => 票数修改失败
15） 300514 => 订单添加失败
16） 300515 => 出票失败
17） 300516 => 顾客状态异常
18） 300517 => 获取代理商信息失败
19） 300518 => 订单不存在
20） 300519 => 门票数局限性
21） 300520 => 订单修改失败
22） 300521 => 不容许退票
23） 300522 => 退票类型无效
24） 300523 => 退票审核中,不容许重复申请
25） 300524 => 余额信息修改失败
26） 300525 => 余额记录添加失败
27） 300526 => 产品未定价，无法下单
28） 300527 => 管理员审核发送产品必要发送短信
29） 300528 => 导码产品不可以从淘宝下单
30） 300529 => 获取码号与二维码失败
31） 300530 => 导码状态更新失败
32） 300531 => 购买数错误
33） 300532 => 超过最晚下单时间
34） 300533 => 没有跨站祈求权限
35） 300534 => 补发次数超过限制次数
4. 门票列表接口
4.1. 接口地址

4.2. 祈求类型
POST 和 GET
4.3. 输入参数
名称
类型
与否必要
描述
method
string
必要
固定值 item_list
format
String
可选
返回文献格式，见format 参数阐明
_pid
Number
必要
合伙伙伴id
_sig
String
必要
签名。见签名参数
page
Number
可选
列表页码，缺省获取第1页
Size
Number
可选
每页获取数量，缺省每页获取发15条信息
cate_id
Number
可选
产品分类ID,缺省无，获取所有分类产品
zone
Number
可选
产品地区ID,缺省无，不作条件
4.4. 返回成果
名称
类型
描述
success
Boolean
返回成果值，见返回数据阐明
message
String
提示信息描述
errorn
Number
返回成果值，见异常阐明
list
List
门票列表
id
Number
门票ID
supplier_id
Number
景区ID
title
String
门票标题
type
Number
门票类型;1普通票，2套票，3线路
send_type
Number
短信发送类型;1二维码，2文字码
amount
Number
门票数量
original_price
Number
门票原价
market_price
Number
市场价
sort_order
Number
门票排序
refund_type
Number
退票类型;1可退票，2审核退票，3不可退票
validity_type
Number
有效期类型;1有效日期，2固定日期
start_time
Number
开始时间，validity_type=2时为Unix 时间戳,validity_type=1时为下单后到有效期开始间隔时间,以秒计算
expire_time
Number
结束时间，validity_type=2时为Unix 时间戳,validity_type=1时为下单后有效期开始时间,以天计算
sms_content
String
短信内容
mms_content
String
彩信内容
print_content
String
打印内容
description
String
描述信息
is_import
Number
与否是导入
nett_price
Number
实际价格(成人价)
nett_price2
Number
实际价格(小朋友价)
4.5. 调用示例

4.6. 返回json格式示例
{
"success"：true,
"message"："成功",
"list"：[
{
"id"："2",
"supplier_id"："7",
"title"："第二门票",
"status"："1",
"type"："1",
"send_type"："1",
"quantity"："91",
"original_price"："200",
"market_price"："123",
"sort_order"："0",
"refund_type"："1",
"validity_type"："1",
"start_time"："1800",
"expire_time"："2",
"sms_content"："尊敬[姓名]，凭此二维码电子票（门票码号[码号]）至[景区]扫描（或告知门票码号）验证成功即可进入，门票数[票数]张；有效期[有效期]",
"mms_content"：null,
"print_content"："打印内容",
"description"："描述信息",
"is_import"："0",
"nett_price"：“200”
},
{
"id"："2",
"supplier_id"："7",
"title"："第二门票",
"status"："1",
"type"："1",
"send_type"："1",
"quantity"："91",
"original_price"："200",
"market_price"："123",
"sort_order"："0",
"refund_type"："1",
"validity_type"："1",
"start_time"："1800",
"expire_time"："2",
"sms_content"："尊敬[姓名]，凭此二维码电子票（门票码号[码号]）至[景区]扫描（或告知门票码号）验证成功即可进入，门票数[票数]张；有效期[有效期]",
"mms_content"：null,
"print_content"："打印内容",
"description"："描述信息",
"is_import"："0",
"nett_price"：“200”
}
....
],
"total"：15， //记录总数
"errorn"：0,
"runtime"：0.367
}
4.7. 返回xml格式示例
<root>
<success>1</success>
<message>成功</message>
<list>
<item id="0">
<d>2</id>
<supplier_id>7</supplier_id>
<title>第二门票</title>
<status>1</status>
<type>1</type>
<send_type>1</send_type>
<quantity>91</quantity>
<original_price>200</original_price>
<market_price>123</market_price>
<sort_order>0</sort_order>
<refund_type>1</refund_type>
<validity_type>1</validity_type>
<start_time>1800</start_time>
<expire_time>2</expire_time>
<sms_content>
尊敬[姓名]，凭此二维码电子票（门票码号[码号]）至[景区]扫描（或告知门票码号）验证成功即可进入，门票数[票数]张；有效期[有效期]
</sms_content>
<mms_content/>
<print_content>打印内容</print_content>
<description>描述信息</description>
<is_import>0</is_import>
<nett_price>200</nett_price>
</item>
<item id="1">
<d>2</id>
<supplier_id>7</supplier_id>
<title>第二门票</title>
<status>1</status>
<type>1</type>
<send_type>1</send_type>
<quantity>91</quantity>
<original_price>200</original_price>
<market_price>123</market_price>
<sort_order>0</sort_order>
<refund_type>1</refund_type>
<validity_type>1</validity_type>
<start_time>1800</start_time>
<expire_time>2</expire_time>
<sms_content>
尊敬[姓名]，凭此二维码电子票（门票码号[码号]）至[景区]扫描（或告知门票码号）验证成功即可进入，门票数[票数]张；有效期[有效期]
</sms_content>
<mms_content/>
<print_content>打印内容</print_content>
<description>描述信息</description>
<is_import>0</is_import>
<nett_price>200</nett_price>
</item>
...
</list>
<total>15</total>
<errorn>0</errorn>
<runtime>0.0684</runtime></root>

5. 订单列表
5.1. 接口地址

5.2. 祈求类型
POST 和 GET
5.3. 输入参数
名称
类型
与否必要
描述
method
string
必要
固定值 orders_list
format
String
可选
返回文献格式，见format 参数阐明
_pid
Number
必要
合伙伙伴id
_sig
String
必要
签名。见签名参数
page
Number
可选
列表页码，缺省获取第1页
size
Number
可选
每页获取数量，缺省每页获取发15条信息
item_id
Number
可选
产品ID，缺省不做条件
begin
Number
可选
开始时间戳，与end连用，缺省30天前时间戳
end
Number
可选
结束时间戳，与begin连用，缺省当前时间戳
5.4. 返回成果
名称
类型
描述
success
Boolean
返回成果值，见返回数据阐明
message
String
提示信息描述
errorn
Number
返回成果值，见异常阐明
list
List
订单列表
id
Number
订单ID
user_id
Number
顾客ID
seller_id
Number
分销商ID
supplier_id
Number
景区ID
title
String
订单标题
name
String
订单人名字
mobile
Number
订单人手机号
payment_id
Number
付款方式;1余额支付，2支付宝
create_time
Number
下单时间
is_send
Number
发送状态;1已发送，0未发送
item_id
Number
票ID
send_price
Number
票发送价
total_price
Number
票总价
price
Number
票单价
amount
Number
票总数
valid_amount
Number
可用数
used_amount
Number
使用数
apply_amount
Number
申请退票数
cancel_amount
Number
已退票数

5.5. 调用示例

5.6. 返回json格式示例
{
"success"：true,
"message"："成功",
"list"：[
{
"id"："15",
"code"："00003",
"user_id"："1",
"seller_id"："1",
"supplier_id"："7",
"title"："北京故宫",
"name"："阿宝",
"mobile"："",
"payment_id"："1",
"item_id"："1",
"is_send"："1",
"amount"："3",
"valid_amount"："0",
"used_amount"："1",
"apply_amount"："1",
"cancel_amount"："1",
"price"："0.00",
"send_price"："1.00",
"total_price"："277.00",
"create_time"：""
}
],
"total"：28,
"errorn"：0,
"runtime"：0.0684
}
5.7. 返回xml格式示例
<root>
<success>1</success>
<message>成功</message>
<list>
<item id="0">
<id>15</id>
<code>00003</code>
<user_id>1</user_id>
<seller_id>1</seller_id>
<supplier_id>7</supplier_id>
<title>北京故宫</title>
<name>阿宝</name>
<mobile></mobile>
<payment_id>1</payment_id>
<item_id>1</item_id>
<is_send>1</is_send>
<amount>3</amount>
<valid_amount>0</valid_amount>
<used_amount>1</used_amount>
<apply_amount>1</apply_amount>
<cancel_amount>1</cancel_amount>
<price>0.00</price>
<send_price>1.00</send_price>
<total_price>277.00</total_price>
<create_time></create_time>
</item>
</list>
<total>28</total>
<errorn>0</errorn>
<runtime>0.0684</runtime>
</root>

6. 下单发票接口
6.1. 接口地址

6.2. 输入参数
名称
类型
与否必要
描述
method
string
必要
固定值 item_orders
format
String
可选
返回文献格式，见format 参数阐明
_pid
Number
必要
合伙伙伴id
_sig
String
必要
签名。见签名参数
orders_id
string
可选
第三方订单ID，可避免网络不好时重复下单
item_id
Number
必要
要购买票ID
size
Number
可选
购买票数,缺省1
name
String
必要
购票人名称
mobile
Number
必要
购票人手机号(成功后短信将发送门票码号到该手机号)
start_date
Date
可选
开始游玩时间，缺省当前时间
price_type
Number
可选
价格类型；1成人，2小朋友，缺省1
type
Number
可选
类型,1本系统订单，2淘宝系统订单,缺省1
sms_send
Number
可选
与否发送告知短信，0不发送，1发送，缺省1(求账号要有发送短信权限)

6.3. 返回成果
名称
类型
描述
success
Boolean
返回成果值，见返回数据阐明
message
String
提示信息描述
errorn
Number
返回成果值，见异常阐明
info
info
订单信息
id
Number
订单ID
user_id
Number
顾客ID
seller_id
Number
分销商ID
supplier_id
Number
景区ID
title
String
订单标题
name
String
订单人名字
mobile
Number
订单人手机号
payment_id
Number
付款方式;1余额支付，2支付宝
create_time
Number
下单时间
is_send
Number
发送状态;1已发送，0未发送
item_id
Number
票ID
send_price
Number
票发送价
total_price
Number
票总价
price
Number
票单价
amount
Number
票总数
valid_amount
Number
可用数
used_amount
Number
使用数
apply_amount
Number
申请退票数
qrcode
string
二维码数据
code
string
文字码(码号)
6.4. 返回json格式示例
{
"success"：true,
"message"："成功",
"info"：{
"code"："",
"user_id"："3",
"seller_id"："1",
"supplier_id"："9",
"title"："金钉子远古世界",
"name"："akuan",
"mobile"："",
"payment_id"：1,
"create_time"：,
"is_send"：1,
"item_id"："11",
"amount"："3",
"price"："116.00",
"total_price"：348,
"send_price"：1,
"start_time"：,
"expire_time"：,
"qrcode"：“JBVYRctFfiZDMwOGRKRlZmRml0QnRSRkI=”,
"id"："23"
},
"errorn"：0,
"runtime"：0.33
}
6.5. 返回xml格式示例
<root>
<success>1</success>
<message>成功</message>
<info>
<code></code>
<user_id>3</user_id>
<seller_id>1</seller_id>
<supplier_id>9</supplier_id>
<title>金钉子远古世界</title>
<name>akuan</name>
<mobile></mobile>
<payment_id>1</payment_id>
<create_time></create_time>
<is_send>1</is_send>
<item_id>11</item_id>
<amount>20</amount>
<price>116.00</price>
<total_price>2320</total_price>
<send_price>1</send_price>
<start_time></start_time>
<expire_time></expire_time>
<qrcode>JBVYRctFfiZDMwOGRKRlZmRml0QnRSRkI=</qrcode>
<id>25</id>
</info>
<errorn>0</errorn>
<runtime>0.95</runtime>
</root>

7. 退票接口
7.1. 接口地址

7.2. 输入参数
名称
类型
与否必要
描述
method
string
必要
固定值 item_refund
format
String
可选
返回文献格式，见format 参数阐明
_pid
Number
必要
合伙伙伴id
_sig
String
必要
签名。见签名参数
orders_id
number
必要
要退票订单号
size
Number
可选
退票数,缺省退票所有未使用票数

7.3. 返回成果
名称
类型
描述
success
Boolean
返回成果值，见返回数据阐明
message
String
提示信息描述
errorn
Number
返回成果值，见异常阐明
info
info
订单信息
id
Number
退票记录ID
user_id
Number
顾客ID
seller_id
Number
分销商ID
create_time
Number
记录时间
item_id
Number
票ID
price
Number
票总价
amount
Number
票总数
fee
Number
手续费
Status
Number
状态：1已使用，2申请退票，3退票成功，4退票不通过
7.4. 返回json格式示例
{
"success"：true,
"message"："成功",
"info"：{
"orders_id"："22",
"status"：3,
"amount"："3",
"price"：240,
"fee"：0,
"create_time"：,
"user_id"："1",
"seller_id"："1",
"item_id"："11"
},
"errorn"：0,
"runtime"：0.67
}
7.5. 返回xml格式示例
<root>
<success>1</success>
<message>成功</message>
<info>
<orders_id>22</orders_id>
<status>3</status>
<amount>2</amount>
<price>160</price>
<fee>0</fee>
<create_time></create_time>
<user_id>1</user_id>
<seller_id>1</seller_id>
<item_id>11</item_id>
</info>
<errorn>0</errorn>
<runtime>0.209</runtime>
</root>
8. 验证推送告知(暂未使用)
8.1. 告知参数
名称
类型
与否必要
描述
method
string
必要
固定值 validate
sign
string
必要
签名
code
string
必要
验证码号
amo