接口文档
上海天畅信息技术有限公司
2023年07月
版权所有 不得复制
1 、接口函数
1.1 、获取签约产品
1.1.1 函数概述
获取签约产品
1.1.2 、http 请求说明
http请求方式:POST
http请求地址:
http://SERVER_URL/ticketInterface/findContractedProducts
1.1.3 、Http header 参数说明
参数 |
参数类型 |
说明 |
username |
String |
接口用户名 |
timestamp |
String |
接口调用时间,格式 “yyyy-MM-dd HH:mm:ss” |
sign |
String |
签名 |
1.1.4 、body 参数示例
{
"scenicTicketNo": "1001"
}
Body参数说明:
参数 |
参数类型 |
必填 |
说明 |
scenicTicketNo |
Long |
是 |
产品编号 |
startDate |
String |
是 |
开始日期,格式:yyyy-MM-dd |
endDate |
String |
是 |
结束日期,格式:yyyy-MM-dd |
1.1.5 、正常返回值示例
{
"code": "200",
"message": "查询授权产品成功",
"data": {
"scenicTicketName": "成人票",
"scenicTicketNo": 100000053,
"priceStockList": [
{
"date": "2022-01-21",
"marketPrice": 55,
"salePrice": 52,
"settlementPrice": 51,
"stock": 99999
},
{
"date": "2022-01-22",
"marketPrice": 65,
"salePrice": 62,
"settlementPrice": 61,
"stock": 99999
},
{
"date": "2022-01-23",
"marketPrice": 75,
"salePrice": 72,
"settlementPrice": 71,
"stock": 99999
}
],
"bookByTimeFlag": "Y"
}
}
返回参数说明:
参数 |
参数类型 |
说明 |
code |
String |
状态码 |
message |
String |
消息文本 |
data |
Object |
Data参数 |
scenicTicketName |
String |
产品名称 |
scenicTicketNo |
Long |
产品编号 |
priceStockList |
List |
价格日历库存集合 |
date |
String |
执行日期,格式:yyyy-MM-dd |
marketPrice |
Long |
市场价,单位:分 |
salePrice |
Long |
建议零售价,单位:分 |
settlementPrice |
Long |
结算价格,单位:分 |
stock |
Integer |
剩余库存数量 |
bookByTimeFlag |
String |
产品分时预约标志,Y:是,N:否 |
1.1.6 、异常返回Code代码说明
异常返回值:
{
"code": "51002",
"message": "签名失败!"
}
返回参数说明:
参数 |
参数类型 |
说明 |
code |
String |
消息状态码 |
message |
String |
消息内容 |
1.2 、创建订单
1.2.1 函数概述
创建订单
1.2.2 、http 请求说明
http请求方式:POST
http请求地址:
http://SERVER_URL/ticketInterface/createOrder
1.2.3 、Http header 参数说明
参数 |
参数类型 |
说明 |
username |
String |
接口用户名 |
timestamp |
String |
接口调用时间,格式 “yyyy-MM-dd HH:mm:ss” |
sign |
String |
签名 |
1.2.4 、body 参数示例
{
"thirdOrderNo":"20220120110001-10004",
"tackUserName":"",
"phoneAreaNumber":"",
"tackPhoneNumber":"",
"tackCertificateTypeId":"",
"tackCertificateNo":"",
"remark":"",
"orderDetailList":[
{
"arriveDT":"2022-01-20",
"saleSum":2,
"scenicTicketNo":100000053,
"settlementPrice":1000,
"salePrice":1000,
"timeControlId": 10000000049161,
"controlStartTime": "14:30",
"orderCertificateList":[
{
"certificateName":"测试1",
"certificateTypeId":1,
"certificateNo":"110101199003073933",
"phoneNumber":"18654256889"
},
{
"certificateName":"测试2",
"certificateTypeId":1,
"certificateNo":"110101199003079577",
"phoneNumber":"18675845885"
}
]
}
]
}
Body参数说明:
参数 |
参数类型 |
必填 |
说明 |
thirdOrderNo |
String |
是 |
第三方订单号(唯一) |
tackUserName |
String |
是 |
取票人姓名 |
phoneAreaNumber |
String |
是 |
手机区号,中国:86 |
tackPhoneNumber |
String |
是 |
取票人手机号码 |
tackCertificateTypeId |
Long |
否 |
取票证件类型,详见参数说明 |
tackCertificateNo |
String |
否 |
取票人证件号码 |
remark |
String |
否 |
备注 |
orderDetailList |
List |
是 |
产品预定信息 |
scenicTicketNo |
Long |
是 |
产品编号 |
saleSum |
Integer |
是 |
购票数量 |
timeControlId |
Long |
否 |
分时预约时段id(产品为分时预约时必填,与controlStartTime 不能同时为空) |
controlStartTime |
String |
否 |
分时预约时段开始时间,例:08:00:00(产品为分时预约时必填,与timeControlId 不能同时为空) |
settlementPrice |
Integer |
是 |
结算价格,单位:分(用于验证价格传的是否正确) |
salePrice |
Integer |
否 |
售卖单价,单位:分(用于验证价格传的是否正确) |
arriveDT |
String |
是 |
游玩日期,格式:yyyy-MM-dd ,期票模式下可以为空 |
orderCertificateList |
List |
否 |
实名制信息,实名制时必填 |
certificateName |
String |
否 |
实名制姓名,实名制时必填 |
certificateTypeId |
Long |
否 |
实名制证件类型,实名制时必填,详见参数说明 |
certificateNo |
String |
否 |
实名制证件号码,实名制时必填 |
phoneNumber |
String |
否 |
实名制手机号码 |
1.2.5 、正常返回值示例
{
"code": "200",
"message": "创建订单成功",
"data": {
"orderNo": 114165804757001,
"thirdOrderNo": "20220120110001-10004",
"orderVoucherNo": "72547381"
}
}
返回参数说明:
参数 |
参数类型 |
说明 |
code |
String |
状态码 |
message |
String |
消息文本 |
data |
Object |
Data参数 |
thirdOrderNo |
String |
第三方订单号 |
orderNo |
String |
订单号 |
orderVoucherNo |
String |
订单凭证号 |
1.2.6 、异常返回Code代码说明
异常返回值:
{
"code": "51002",
"message": "签名失败!"
}
返回参数说明:
参数 |
参数类型 |
说明 |
code |
String |
消息状态码 |
message |
String |
消息内容 |
1.3 支付订单
1.3.1 函数概述
支付订单
1.3.2 、http 请求说明
http请求方式:POST
http请求地址:
http://SERVER_URL/ticketInterface/payOrder
1.3.3 、Http header 参数说明
参数 |
参数类型 |
说明 |
username |
String |
接口用户名 |
timestamp |
String |
接口调用时间,格式 “yyyy-MM-dd HH:mm:ss” |
sign |
String |
签名 |
1.3.4 、body 参数示例
{
"thirdOrderNo":"20220120110001-10004"
}
Body参数说明:
参数 |
参数类型 |
必填 |
说明 |
thirdOrderNo |
String |
是 |
第三方订单号 |
1.3.5 、正常返回值示例
{
"code":"200",
"message":"支付成功",
"data":{
"thirdOrderNo":"2020042110010181901",
"orderNo":"17776563271056",
"orderVoucherNo":"4578956",
"orderDetailList":[
{
"scenicTicketNo":"100001",
"saleSum":1,
"ticketOutMode":1,
"validStartDT":"2020-04-20 08:00:00",
"validEndDT":"2020-04-20 17:00:00",
"orderBarcodeList":[
{
"barcodeNo":"DZM27948EF1D9EFA6BA",
"barcodeNoPath": "http://img.com/ticketInterface/getBarcodeImg/DZM27948EF1D9EFA6BA",
"barcodeSum":1,
"orderCertificateList":[
{
"certificateName":"张三",
"certificateTypeId":1,
"certificateNo":"110101199001017698",
"phoneNumber":"15788886545"
}
]
}
]
}
]
}
}
返回参数说明:
参数 |
参数类型 |
说明 |
code |
String |
状态码 |
message |
String |
消息文本 |
data |
Object |
Data参数 |
thirdOrderNo |
String |
第三方订单号 |
orderNo |
String |
订单号 |
orderVoucherNo |
String |
订单凭证号 |
orderDetailList |
List |
订单详情集合 |
scenicTicketNo |
Long |
票种编号 |
saleSum |
Integer |
购票数量 |
ticketOutMode |
Integer |
出票方式(1:一票一客 2:一票多客) |
validStartDT |
String |
有效开始时间,格式:yyyy-MM-dd HH:mm:ss |
validEndDT |
String |
有效结束时间,格式:yyyy-MM-dd HH:mm:ss |
orderBarcodeList |
List |
入园二维码信息集合 |
barcodeNo |
String |
二维码编号 |
barcodeNoPath |
String |
二维码图片链接地址 |
barcodeSum |
Integer |
二维码对应数量 |
orderCertificateList |
List |
实名制信息集合 |
certificateName |
String |
实名制姓名 |
certificateTypeId |
Long |
实名制证件类型Id,详见参数说明 |
certificateNo |
String |
实名制证件号码 |
phoneNumber |
String |
实名制手机号码 |
1.3.6 、异常返回Code代码说明
异常返回值:
{
"code": "51002",
"message": "签名失败!"
}
返回参数说明:
参数 |
参数类型 |
说明 |
code |
String |
消息状态码 |
message |
String |
消息内容 |
1.4 、取消订单
1.4.1 函数概述
未支付的订单取消,释放订单库存及限购
1.4.2 、http 请求说明
http请求方式:POST
http请求地址:
http://SERVER_URL/ticketInterface/cancelOrder
1.4.3 、Http header 参数说明
参数 |
参数类型 |
说明 |
username |
String |
接口用户名 |
timestamp |
String |
接口调用时间,格式 “yyyy-MM-dd HH:mm:ss” |
sign |
String |
签名 |
1.4.4 、body 参数示例
{
"thirdOrderNo":"2023062110010182020"
}
Body参数说明:
参数 |
参数类型 |
必填 |
说明 |
thirdOrderNo |
String |
是 |
u第三方订单号 |
1.4.5 、正常返回值示例
{
"code": "200",
"message": "订单取消成功!"
}
返回参数说明:
参数 |
参数类型 |
说明 |
code |
String |
状态码 |
message |
String |
消息文本 |
1.4.6 、常返回Code代码说明
异常返回值:
{
"code": "51002",
"message": "签名失败!"
}
返回参数说明:
参数 |
参数类型 |
说明 |
code |
String |
消息状态码 |
message |
String |
消息内容 |
1.5 、订单查询
1.5.1 函数概述
订单查询
1.5.2 、http 请求说明
http请求方式:POST
http请求地址:
http://SERVER_URL/ticketInterface/queryOrder
1.5.3 、Http header 参数说明
参数 |
参数类型 |
说明 |
username |
String |
接口用户名 |
timestamp |
String |
接口调用时间,格式 “yyyy-MM-dd HH:mm:ss” |
sign |
String |
签名 |
1.5.4 、body 参数示例
{
"thirdOrderNo":"2023062110010182020"
}
Body参数说明:
参数 |
参数类型 |
必填 |
说明 |
thirdOrderNo |
String |
是 |
第三方订单号 |
1.5.5 、正常返回值示例
{
"code": "200",
"message": "订单查询成功",
"data": {
"orderNo": 114165804757001,
"thirdOrderNo": "20220120110001-10004",
"orderVoucherNo": "72547381",
"orderStatus": "3",
"orderStatusName": "待使用",
"orderDetailList": [
{
"scenicTicketName": "成人票",
"scenicTicketNo": 100000053,
"salePrice": 1000,
"settlementPrice": 1000,
"saleSum": 2,
"useSum": 0,
"notUseSum": 2,
"validStartDT": "2022-01-20 08:00:00",
"validEndDT": "2022-01-20 22:30:00",
"orderBarcodeList": [
{
"barcodeNo": "DZMBA7544F1ECFDE5D9",
"barcodeNoPath": "http://img.com/ticketInterface/getBarcodeImg/DZMBA7544F1ECFDE5D9",
"operateSum": 2,
"operateTime": "2022-01-20 08:08:00",
"status": 0,
"orderCertificateList": [
{
"certificateName": "测试1",
"certificateTypeId": 1,
"certificateNo": "110101199003073933",
"phoneNumber": "18654256889"
},
{
"certificateName": "测试2",
"certificateTypeId": 1,
"certificateNo": "110101199003079577",
"phoneNumber": "18675845885"
}
]
}
]
}
]
}
}
返回参数说明:
参数 |
参数类型 |
说明 |
code |
String |
状态码 |
message |
String |
消息文本 |
data |
Object |
Data参数 |
thirdOrderNo |
String |
第三方订单号 |
orderNo |
String |
订单号 |
orderVoucherNo |
String |
订单凭证号 |
orderStatus |
String |
订单状态 参数列表 |
orderStatusName |
String |
订单状态名称 |
orderDetailList |
List |
订单信息 |
scenicTicketName |
String |
票种名称 |
scenicTicketNo |
Long |
票种编号 |
salePrice |
Long |
零售价格,单位:分 |
settlementPrice |
Long |
结算价,单位:分 |
saleSum |
Integer |
购票数量 |
useSum |
Integer |
已使用门票总数量 |
returnSum |
Integer |
退订总数量 |
notUseSum |
Integer |
剩余未使用数量 |
validStartDT |
String |
有效开始时间,格式:yyyy-MM-dd HH:mm:ss |
validEndDT |
String |
有效结束时间,格式:yyyy-MM-dd HH:mm:ss |
orderBarcodeList |
List |
入园二维码信息 |
barcodeNo |
String |
二维码编号 |
barcodeNoPath |
String |
二维码图片链接地址 |
operateSum |
Integer |
操作数量(二维码状态下的数量) |
operateTime |
Date |
操作时间,格式:yyyy-MM-dd HH:mm:ss |
status |
Integer |
二维码状态,0:未使用,1:已使用,2:已退订 |
orderCertificateList |
List |
实名制信息 |
certificateName |
String |
实名制姓名 |
certificateTypeId |
String |
实名制证件类型,详见参数说明 |
certificateNo |
String |
实名制证件号码 |
phoneNumber |
String |
实名制手机号码 |
1.5.6 、异常返回Code代码说明
异常返回值:
{
"code": "51002",
"message": "签名失败!"
}
返回参数说明:
参数 |
参数类型 |
说明 |
code |
String |
消息状态码 |
message |
String |
消息内容 |
1.6 、订单退订
1.6.1 函数概述
已支付的订单退订
1.6.2 、http 请求说明
http请求方式:POST
http请求地址:
http://SERVER_URL+/ticketInterface/refundOrder
1.6.3 、Http header 参数说明
参数 |
参数类型 |
说明 |
username |
String |
接口用户名 |
timestamp |
String |
接口调用时间,格式 “yyyy-MM-dd HH:mm:ss” |
sign |
String |
签名 |
1.6.4 、body 参数示例
{
"thirdOrderNo":"20220120110001-10006",
"refundId":"td2022-012010002",
"returnBarcodeNoList":[
{
"barcodeNo":"DZMBEE6B13F9528FBC1",
"barcodeSum":"2",
"refundAmount":2000,
"refundFee":0,
"orderCertificateList":[
{
"certificateTypeId":"1",
"certificateNo":"110101199003073933"
},
{
"certificateTypeId":"1",
"certificateNo":"110101199003079577"
}
]
}
]
}
Body参数说明:
参数 |
参数类型 |
必填 |
说明 |
thirdOrderNo |
String |
是 |
第三方订单号 |
refundId |
String |
是 |
退款流水号(唯一) |
returnBarcodeNoList |
List |
是 |
退订信息集合 |
barcodeNo |
String |
是 |
退订二维码编号 |
barcodeSum |
Integer |
是 |
退订二维码数量(本次退订数量) |
refundAmount |
Integer |
否 |
结算价退订总金额,单位:分,如果传了值,会验证是否相同 |
refundFee |
Integer |
否 |
本次退款结算价手续费总金额,单位:分,如果传了值,会验证是否相同 |
orderCertificateList |
List |
否 |
实名制信息集合,创建订单时如果产品实名制则必填 |
certificateTypeId |
Long |
是 |
实名制证件类型Id,详见参数说明 |
certificateNo |
String |
是 |
实名制证件号码 |
1.6.5 、正常返回值示例
退订产品不需要审核且退订成功时,返回示例
{
"code": "200",
"message": "退订成功!"
}
退订产品需要审核时,返回示例,审核结果通过“订单退订通知”接口返回
{
"code": "53602",
"message": "退订需要审核,请等待审核结果!"
}
已退订的订单,再次退订时,返回示例
{
"code": "53601",
"message": "已退订!"
}
返回参数说明:
参数 |
参数类型 |
说明 |
code |
String |
状态码 |
message |
String |
消息文本 |
1.6.6 、常返回Code代码说明
异常返回值:
{
"code": "51002",
"message": "签名失败!"
}
返回参数说明:
参数 |
参数类型 |
说明 |
code |
String |
消息状态码 |
message |
String |
消息内容 |
1.7 订单退订通知
1.7.1 函数概述
1、退订需要审核的产品,审核之后,通过该接口通知分销商审核结果。
2、退订通知接收处理成功之后,请返回订单退订处理成功(code:"200"),未接收到退订通知处理成功的结果,会进行重试 3次,如果3次都没有接收处理成功,系统也不再发送该通知。
注意:
对于已处理的退订通知,重复接收时,请返回已处理成功(code:"200")
1.7.2 、http 请求说明
http请求方式:POST
http请求地址:通知地址由分销商提供
1.7.3 、Http header 参数说明
参数 |
参数类型 |
说明 |
username |
String |
接口用户名 |
timestamp |
String |
接口调用时间,格式 “yyyy-MM-dd HH:mm:ss” |
sign |
String |
签名 |
1.7.4 、body 参数示例
{
"orderNo":"114414004897001",
"refundId":"td2022-021410001",
"thirdOrderNo":"20221021410001-10001",
"verifyRemark":"审核通过!",
"verifyType":"1"
}
Body参数说明:
参数 |
参数类型 |
必填 |
说明 |
thirdOrderNo |
String |
是 |
第三方订单号 |
refundId |
String |
是 |
退款流水号(唯一),提交退订请求时的退款流水号 |
orderNo |
String |
是 |
订单号 |
verifyType |
String |
是 |
审核结果,1:审核通过,2:审核不通过 |
verifyRemark |
String |
否 |
审核原因 |
1.7.5 、正常返回值示例
{
"code": "200",
"message": "接收退订审核结果成功!"
}
返回参数说明:
参数 |
参数类型 |
说明 |
code |
String |
状态码 |
message |
String |
消息文本 |
1.7.6 、常返回Code代码说明
异常返回值:
{
"code": "51002",
"message": "签名失败!"
}
返回参数说明:
参数 |
参数类型 |
说明 |
code |
String |
消息状态码 |
message |
String |
消息内容 |
1.8 消费通知接口
1.8.1 函数概述
订单消费通知接收处理成功之后,请返回订单消费通知处理成功(code:"200"),未接收到消费通知处理成功的结果,会进行重试 3次,如果3次都没有接收处理成功,系统也不再发送该通知,可通过订单查询接口查询。
注意:
1、处理消费通知时,注意根据二维码状态(0:未使用,1:已使用,2:已退订)进行处理。
2、对于已处理的消费通知,重复接收时,请返回已处理成功(code:"200")
1.8.2 、http 请求说明
http请求方式:POST
http请求地址: 由分销商提供
1.8.3 、Http header 参数说明
参数 |
参数类型 |
说明 |
username |
String |
接口用户名 |
timestamp |
String |
接口调用时间,格式 “yyyy-MM-dd HH:mm:ss” |
sign |
String |
签名 |
1.8.4 、body 参数示例
{
"orderDetailList":[
{
"notUseSum":1,
"orderBarcodeList":[
{
"barcodeNo":"DZMEE1D7DE101A8A123",
"barcodeNoPath":"http://img.com/ticketInterface/getBarcodeImg/DZMEE1D7DE101A8A123",
"operateSum":1,
"operateTime":"2022-01-21 10:10:27",
"orderCertificateList":[
{
"certificateName":"测试1",
"certificateNo":"110101199003073933",
"certificateTypeId":1,
"phoneNumber":"18654256889"
}
],
"status":1
},
{
"barcodeNo":"DZMEE1D7DE101A8A123",
"barcodeNoPath":"http://img.com/ticketInterface/getBarcodeImg/DZMEE1D7DE101A8A123",
"operateSum":1,
"operateTime":"2022-01-21 08:08:00",
"orderCertificateList":[
{
"certificateName":"测试2",
"certificateNo":"110101199003079577",
"certificateTypeId":1,
"phoneNumber":"18675845885"
}
],
"status":0
}
],
"returnSum":0,
"salePrice":1000,
"saleSum":2,
"scenicTicketName":"成人票",
"scenicTicketNo":100000053,
"settlementPrice":1000,
"useSum":1,
"validEndDT":"2022-01-21 22:30:00",
"validStartDT":"2022-01-21 08:00:00"
}
],
"orderNo":114173745960001,
"orderStatus":"3",
"orderStatusName":"待使用",
"orderVoucherNo":"58040935",
"thirdOrderNo":"20221120110001-10001"
}
Body参数说明:
参数 |
参数类型 |
说明 |
thirdOrderNo |
String |
第三方订单号 |
orderNo |
String |
订单号 |
orderVoucherNo |
String |
订单凭证号 |
orderStatus |
String |
订单状态 详见参数说明 |
orderStatusName |
String |
订单状态名称 |
orderDetailList |
List |
订单信息 |
scenicTicketName |
String |
票种名称 |
scenicTicketNo |
Long |
票种编号 |
salePrice |
Long |
零售价格,单位:分 |
settlementPrice |
Long |
结算价,单位:分 |
saleSum |
Integer |
购票数量 |
useSum |
Integer |
已使用门票总数量 |
returnSum |
Integer |
退订总数量 |
notUseSum |
Integer |
剩余未使用数量 |
validStartDT |
String |
有效开始时间,格式:yyyy-MM-dd HH:mm:ss |
validEndDT |
String |
有效结束时间,格式:yyyy-MM-dd HH:mm:ss |
orderBarcodeList |
List |
入园二维码信息 |
barcodeNo |
String |
二维码编号 |
barcodeNoPath |
String |
二维码图片链接地址 |
operateSum |
Integer |
操作数量(二维码状态下的数量) |
operateTime |
Date |
操作时间,格式:yyyy-MM-dd HH:mm:ss |
status |
Integer |
二维码状态,0:未使用,1:已使用,2:已退订 |
orderCertificateList |
List |
实名制信息 |
certificateName |
String |
实名制姓名 |
certificateTypeId |
String |
实名制证件类型,详见参数说明 |
certificateNo |
String |
实名制证件号码 |
phoneNumber |
String |
实名制手机号码 |
1.8.5 、正常返回值示例
{
"code": "200",
"message": "消费通知接收处理成功!"
}
返回参数说明:
参数 |
参数类型 |
说明 |
code |
String |
状态码 |
message |
String |
消息文本 |
1.8.6 、常返回Code代码说明
异常返回值:
{
"code": "51002",
"message": "签名失败!"
}
返回参数说明:
参数 |
参数类型 |
说明 |
code |
String |
消息状态码 |
message |
String |
消息内容 |
2 、返回Code代码说明
Code代码 |
描述 |
备注 |
200 |
成功 |
|
500 |
接口调用失败 |
|
51001 |
接口参数错误 |
|
51002 |
签名失败 |
|
51003 |
余额不足 |
|
52007 |
订单已支付 |
|
52008 |
库存不足 |
|
3 、相关参数说明
3.1 、证件类型说明:
序号 |
参数值 |
参数说明 |
1 |
1 |
身份证 |
4 、订单状态说明
序号 |
参数值 |
参数说明 |
1 |
1 |
待支付 |
3 |
3 |
待使用 |
4 |
4 |
已使用 |
5 |
5 |
已过期 |
6 |
6 |
已取消 |
7 |
7 |
已退订 |
9 |
9 |
出票中 |
10 |
10 |
退订审核中 |
5 、接口签名规则
1、md5(username + 密钥key + timestamp+ body参数 ) ,然后转换为小写;
2、md5 采用 32 位;
签名示例:
用户名:demo
密钥key :SE4223SDSDD4SD
接口调用时间:2023-06-21 11:00:10
body参数:{"thirdOrderNo":"2023062110010182020"}
Md5加密内容为:
demoSE4223SDSDD4SD2023-06-21 11:00:10{"thirdOrderNo":"2023062110010182020"}
3、请求头:application/x-www-form-urlencoded