首页分销API途牛火车票余票查询

概述

途牛开放API将供应商频繁、重复、低效的操作抽象简化为一组公共服务，开放给供应商系统，供应商可以使用这些服务，推送产品、库存，接收订单信息，查询业务相关信息，从而实现效益最大化。目前已开放跟团API门票API

API调用说明

请求流程

数据格式

API调用参数分为系统参数和业务参数，请求时，系统参数是必传的，否则无法成功请求，业务参数由具体业务接口定义。

入参格式

系统参数
名称 类型 必填 描述
apiKey String 是 分配给供应商的唯一身份标识
sign String 是 请求签名，生成规则参见签名机制
timestamp String 是 时间戳，参见时间戳

API请求返回结果目前支持json和xml格式，具体返回格式由请求头中的Content-Type属性来决定。当Content-Type属性为application/xml时，返回xml格式，其余情况下统一返回json格式。返回结果包含以下字段

出参格式

系统参数
名称 类型 必填 描述
returnCode int 是 结果码，具体值参见API返回码
errorMsg String 否 异常时错误信息
data String 否 返回结果
success boolean 是 是否请求成功

注意事项

1. 所有的请求和响应数据编码皆为utf-8格式

2. 生成签名时，空值的参数不参与校验

3. 生成签名时，参数名称和值大小写敏感

4. 当部署新机器时，需要立刻将新机器IP提交给相关接口人，加入到IP白名单中，否则会导致请求失败。（我们将很快提供线上功能，直接在页面中添加IP即可）

5. 每个接口都需要单独申请访问权限，否则无法请求成功

应用环境

目前途牛API系统总共分2套环境，一套测试环境，一套线上环境。生产环境和测试环境的账号配置是相互独立的，需要分开申请

测试环境

途牛API测试环境的数据是完全独立的，目的是在供应商API开发结束后进行联调测试，解决API对接过程中产生的问题

跟团产品测试地址：http://sup.tuniu.org:9690/gentuan/product

门票测试地址：http://sup.tuniu.org:9790/menpiao

线上环境

相关说明

API两套环境的账号及相关配置都是独立开的，需要分开申请。如果有API对接意向，请提供对接供应商ID、对接应用服务器IP（用于IP白名单），并联系我们，我们将会给您提供对应的apiKey和secret_key

安全机制

访问频率频次限制

单位时间内，每个供应商每分钟只能访问固定次数，如果发现频率过高，则认为可能存在恶意攻击行为，频率过高的请求将会被拦截。

每个接口针对供应商每天请求次数是有限制的，如果请求次数超过该接口允许的上线，则请求失败。

具体限制次数和频率可以和相关接口人进行沟通了解。

时间戳

时间戳，格式为yyyy-MM-dd HH:mm:ss，例如：2015-07-30 12:34:56。请求时会校验时间戳，只允许时间误差在5分钟之内的请求访问。

签名机制

为了防止用户请求被劫持、篡改，我们通过签名手段来确保请求数据的完整性。用户在调用API 时需要对请求参数进行签名验证，请求到达服务器后也会对请求参数进行验证，当生成的签名不匹配时则表示数据被拦截篡改或丢失。由于这个机制，供应商需要保存好自己的密钥，一旦泄露，则表示请求可以被伪造。如发现密钥可能泄露，请联系相关接口人重置密钥。

所有类型的请求，签名生成规则都一样，我们将所有入参按照一定规则进行拼装，再加上密钥，经过加密最终生成一串不可逆的加密字符串。为了方便毕竟，我们将密钥统一转成大写字符。生成签名时，需要注意空值的参数不参与校验，且参数名称和值大小写敏感。签名具体步骤参考附录案例签名生成流程,业务参数中有加密数据的，签名按照加密之后的数据进行签名生成。

请求IP限制

供应商申请API接入时，需要提供自己的应用IP，作为和apiKey绑定的IP白名单。当请求发生时，如果请求IP不是该key值的IP白名单内，则请求失败。该限制的目的是为了防止供应商身份泄露导致的恶意访问。

消息加密

针对传输过程的敏感信息进行加密处理，包括3.2预定下单 请求和异步回调，3.5线上退票请求和异步回调，只对业务参数进行加密，业务参数密文格式：BASE64(DES (业务参数明文, apiKey))

详细说明：

业务参数在传输之前是明文的JSON对象，例如：

"data" :{
    "retailOrderId": "15538430T8393205",
    "cheCi": "K1237",
    "fromStationCode": "BZH",
     …
    "passengers": [
        {
            "passengerId": 33292562,
            "ticketNo": null,
            "passengerName": "张秀勤",
            "passportNo": "341222197608254405",
            "passportTypeId": "1",
            "passportTypeName": "二代身份证",
            "piaoType": "1",
            …
        }
    ]
}

加密之后整个消息结构如下：

{
  "apiKey": Ape2hqlBF0sFUUcjbj,
  "timestamp": 2015-07-3012: 34: 56,
  "sign": C81E00F2CCC228DD8C1D3EB6C69B4260,
  "data": "base64ResultTest"
}

返回结果码

返回结果码

返回码 错误信息 备注
231000 success 请求成功
231001 user not exists 请求用户不存在
231002 No permission to do this operation 用户没有该接口访问权限
231003 Unauthorized client IP address IP未授权
231004 high frequency error 访问频率过高
231005 visit num limit 访问次数达到限制
231006 timestamp error 时间戳异常
231007 signature error 签名异常
231008 param error 入参异常
231009 inter not exist 接口不存在
231099 unknown error 未知异常

接口说明

此接口用于查询指定日期的出发站与到达站之间的剩余车票数量。

1、调用方法

Method：HTTP-POST

Url：{API_Url}/train/search

Data_Type:json

2、系统参数

请求入参格式

API调用参数分为系统参数和业务参数，请求时，系统参数是必传的，否则无法成功请求，业务参数由具体业务接口定义,所有请求需要指定Content-Type 为"application/json; charset=utf-8"。

所有火车票接口在传入 jsonStr 里都必需包括这几个属性

系统参数
名称 类型 必填 描述
apiKey String 是 分配给供应商的唯一身份标识
sign String 是 请求签名，生成规则参见签名机制
timestamp String 是 时间戳，参见时间戳
data Object 否 请求参数内容，接口消息体密文加密

异步回调请求格式

API请求返回结果目前支持json格式,且返回的消息体是经过BASE64编码过的字符串，解码之后的消息格式字段如下：

返回结果
名称 类型 必填 描述
apiKey String 是 分配给供应商的唯一身份标识
sign String 是 请求签名，生成规则参见签名机制
timestamp String 是 时间戳，参见时间戳
returnCode int 是 结果码，具体值参见API返回码
errorMsg String 否 异常时错误信息
data Object 否 返回结果

同步返回参数格式

返回结果
名称 类型 必填 描述
success Boolean 否 保留字段，固定为true
returnCode int 是 结果码，具体值参见API返回码
errorMsg String 否 异常时错误信息
data Object 否 返回结果

异步回调同步返回格式

返回结果
名称 类型 必填 描述
success boolean true 结果标示

3、业务参数

接口入参

名称 类型 必填 示例值 描述
trainDate string 是 乘车日期（yyyy-MM-dd）
fromStation string 是 出发站简码
toStation string 是 到达站简码
trainCode string 否 车次号(提供车次号时仅返回车次号对应的余票信息)

入参示例

{
    "apiKey": "testkey",
    "sign": "testsign",
    "timestamp": "2015-08-03",
    "data": {
        "trainDate": "2015-08-29",
        "fromStation": "NJH",
        "toStation": "SHH",
        "trainCode": ""
    }
}

接口出参

名称 类型 必填 示例值 描述
saleDateTime 车票开售时间
canBuyNow 当前是否可以接受预定（Y:可以，N:不可以）
arriveDays 列车从出发站到达目的站的运行天数 0：当日到达，1：次日到达，2：三日到达，3：四日到达，依此类推
trainStartDate 列车从始发站出发的日期
trainCode 车次
accessByIdcard 是否可凭二代身份证直接进出站
trainNo 列车号
trainType 列车类型（非必填，可能返回空字符串、汉子、字母）
fromStationName 出发车站名
fromStationCode 出发车站简码
toStationName 到达车站名
toStationCode 到达车站简码
startStationName 列车始发站名
endStationName 列车终到站名
startTime 出发时刻
arriveTime 到达时刻
runTime 历时（从出发站到目的站的列车运行时间）
runTimeMinute 历时分钟合计
gjrwNum 高级软卧余票数量
gjrwPrice 高级软卧票价（此返回中所有price字段值含义：空字符串表示无此坐等， 数字表示有此坐）
qtxbNum 其他席别余票数量
qtxbPrice 其他席别对应的票价
rwNum 软卧余票数量
rwPrice 软卧票价
rzNum 软座的余票数量
rzPrice 软座的票价
swzNum 商务座的余票数据
swzPrice 商务座票价
tdzNum 特等座的余票数量
tdzPrice 特等座票价
wzNum 无座的余票数量
wzPrice 无座票价
ywNum 硬卧的余票数量
ywPrice 硬卧票价
yzNum 硬座的余票数量
yzPrice 硬座票价
edzNum 二等座的余票数量
edzPrice 二等座票价
ydzNum 一等座的余票数量
ydzPrice 一等座票价

出参示例

{
    "success": true,
    "returnCode": 231000,
    "errorMsg": "",
    "data": [
        {
            "trainNo": "1100000K7507",
            "trainCode": "K75",
            "startStationName": "CCT",
            "endStationName": "NGH",
            "fromStationCode": "NJH",
            "fromStationName": "南京",
            "toStationCode": "SNH",
            "toStationName": "上海南",
            "startTime": "00:58",
            "arriveTime": "04:37",
            "arriveDays": "0",
            "runTime": "03:39",
            "canBuyNow": "Y",
            "runTimeMinute": "219",
            "trainStartDate": "20150827",
            "accessByIdcard": "Y",
            "saleDateTime": "1630",
            "gjrwNum": "--",
            "gjrwPrice": "--",
            "qtxbNum": "--",
            "qtxbPrice": "--",
            "rwNum": "0",
            "rwPrice": "140.5",
            "rzNum": "--",
            "rzPrice": "--",
            "tdzNum": "--",
            "tdzPrice": "--",
            "wzNum": "59",
            "wzPrice": "46.5",
            "ywNum": "16",
            "ywPrice": "92.5",
            "yzNum": "13",
            "yzPrice": "46.5",
            "edzNum": "--",
            "edzPrice": "--",
            "ydzNum": "--",
            "ydzPrice": "--",
            "swzNum": "--",
            "swzPrice": "--"
        }
    ]
}

4、通用输出参数增加可能出现的值

返回码 错误信息
201 没有符合条件的车次信息
202 查询失败

5、常见问题

接口说明

此接口用于申请分配座位席别信息

预定下单入参和异步返回需要进行数据加密参见消息加密。

1、调用方法

Method：HTTP-POST

Url：{API_Url}/train/book

Data_Type:json

2、系统参数

请求入参格式

API调用参数分为系统参数和业务参数，请求时，系统参数是必传的，否则无法成功请求，业务参数由具体业务接口定义,所有请求需要指定Content-Type 为"application/json; charset=utf-8"。

所有火车票接口在传入 jsonStr 里都必需包括这几个属性

系统参数
名称 类型 必填 描述
apiKey String 是 分配给供应商的唯一身份标识
sign String 是 请求签名，生成规则参见签名机制
timestamp String 是 时间戳，参见时间戳
data Object 否 请求参数内容，接口消息体密文加密

异步回调请求格式

API请求返回结果目前支持json格式,且返回的消息体是经过BASE64编码过的字符串，解码之后的消息格式字段如下：

返回结果
名称 类型 必填 描述
apiKey String 是 分配给供应商的唯一身份标识
sign String 是 请求签名，生成规则参见签名机制
timestamp String 是 时间戳，参见时间戳
returnCode int 是 结果码，具体值参见API返回码
errorMsg String 否 异常时错误信息
data Object 否 返回结果

同步返回参数格式

返回结果
名称 类型 必填 描述
success Boolean 否 保留字段，固定为true
returnCode int 是 结果码，具体值参见API返回码
errorMsg String 否 异常时错误信息
data Object 否 返回结果

异步回调同步返回格式

返回结果
名称 类型 必填 描述
success boolean true 结果标示

3、业务参数

接口入参

名称 类型 必填 示例值 描述
retailOrderId string 是 合作伙伴方订单号
cheCi string 是 车次
fromStationCode string 是 出发站简码
fromStationName string 是 出发站名称
toStationCode string 是 到达站简码
toStationName string 是 到达站名称
trainDate string 是 乘车日期
callBackUrl string 是 锁票异步回调地址[选填]
hasSeat boolean 是 是否出无座票
true:不出无座票
false:允许出无座票
passengers string 是 乘客信息的json字符串。可以是多个乘客信息，最多5个，如：[{乘客1信息},{乘客2信息},...]，也可以只有一个，[{乘客1信息}]。乘客参数见附注1。重要提示：不能只购买儿童票，如果购买儿童票，必须使用随行成人的成人票证件信息（包括姓名、证件号码）。
contact string 是 联系人姓名
phone string 是 联系人手机
userName string 否 12306用户名
userPassword string 否 12306密码
insureCode string 否 保险产品编号（有值，则表示此单购买保险）

入参示例

下单接口需要进行加密，请求为：

{
    "apiKey": "testkey",
    "sign": "testsign",
    "timestamp": "2015-08-03",
	"data": "Base64ResultTest"
}

为方便理解，此处给出解密后的参数样例如下：

{
    "apiKey": "testkey",
    "sign": "testsign",
    "timestamp": "2015-08-03",
    "data": {
        "retailOrderId": "15538430T8393205",
        "cheCi": "K1237",
        "fromStationCode": "BZH",
        "fromStationName": "亳州",
        "toStationCode": "RZH",
        "toStationName": "温州",
        "trainDate": "2015-08-29",
        "callBackUrl": "{商户URL}/train /bookOrderFeedback",
        "contact": "张三",
        "phone": "13728784623",
        "insureCode ": "123",
        "passengers": [
            {
                "passengerId": 33292562,
                "ticketNo": null,
                "passengerName": "张秀勤",
                "passportNo": "341222197608254405",
                "passportTypeId": "1",
                "passportTypeName": "二代身份证",
                "piaoType": "1",
                "piaoTypeName": "成人票",
                "zwCode": "1",
                "zwName": "硬座",
                "cxin": null,
                "price": "1234",
                "reason": 0,
                "provinceCode": null,
                "schoolCode": null,
                "schoolName": null,
                "studentNo": null,
                "schoolSystem": null,
                "enterYear": null,
                "preferenceFromStationName": null,
                "preferenceFromStationCode": null,
                "preferenceToStationName": null,
                "preferenceToStationCode": null
            }
        ]
    }
}

接口出参

同步接口出参

名称 类型 必填 示例值 描述
retailOrderId string 是 15538430T8393205 合作伙伴方订单号

异步接口出参

名称 类型 必填 示例值 描述
retailOrderId string 合作伙伴方订单号
orderId string 交易单号
orderSuccess string 订票是否成功
orderAmount string 订单总金额
cheCi string 车次
fromStationCode string 出发站简码
fromStationName string 出发站名称
toStationCode string 到达站简码
toStationName string 到达站名称
trainDate string 乘车日期
startTime string 从出发站开车时间
arriveTime string 抵达目的站的时间
orderNumber string E010400222
passengers string 与输入的一样，订票成功了里面的cxin和ticketid参数会有值。

出参示例

同步出参示例

{
    "success": true,
    "returnCode": 301,
    "errorMsg": "",
    "data": {
        "retailOrderId": "15538430T8393205"
    }
}

异步出参示例

此返回需要加密，反馈请求为：

{
    "apiKey": "testkey",
    "sign": "testsign",
    "timestamp": "2015-08-03",
    "returnCode": 231000,
    "errorMsg": "",
    "data": "Base64ResultTest"
}

为方便理解，此处给出解密后的参数示例如下：

{
    "apiKey": "testkey",
    "sign": "testsign",
    "timestamp": "2015-08-03",
    "returnCode": 231000,
    "errorMsg": "",
    "data": {
        "retailOrderId": "15538430T8393205",
        "orderId": "AC9WSY4H1H00",
        "orderSuccess": true,
        "orderAmount": 305,
        "cheCi": "K1237",
        "fromStationCode": "BZH",
        "fromStationName": "亳州",
        "toStationCode": "RZH",
        "toStationName": "温州",
        "trainDate": "2015-08-29",
        "startTime": "15:57:00",
        "arriveTime": "11:40:00",
        "orderNumber": "E010400222",
        "passengers": [
            {
                "reason": 0,
                "price": "152.5",
                "passengerId": 33292562,
                "ticketNo": "E0104002221053148",
                "zwCode": "1",
                "cxin": "05车厢,无座",
                "passportTypeName": "二代身份证",
                "passportNo": "341222197608254405",
                "zwName": "硬座",
                "piaoType": "1",
                "passengerName": "张秀勤",
                "passportTypeId": "1",
                "piaoTypeName": "成人票"
            }
        ]
    }
}

4、通用输出参数增加可能出现的值

返回码 错误信息
301 没有余票
302 乘客信息有误
303 乘客已办理其他订单
304 已经超过未完成订单的授权的数量。此授权的数量在签约时确立。（未完成订单：已经确定席别但未确认出票的订单）
305 乘客已经预订过该车次
306 该车次已经没有此席别的车票了
307 当前提交订单用户过多（服务器繁忙）
308 乘客身份信息未通过验证
309 没有足够的票
310 本次购票与其它订单冲突
311 距离开车时间太近

5、常见问题

接口说明

此接口是指合作方得到订票成功（成功分配到了座位席别信息）的反馈后，在规定的时间（比如30分钟）内发出确认出票请求。途牛开放平台收到请求后从合作方账户里扣除相应的金额，同时将成取票单号反馈给合作方。(合作方的用户目前已经可以凭身份证在火车站或代售点自助出票，但如果其证件有问题（一代身份身份证或有损坏的证件），可以凭相关证件和取票单号到火车票售票窗口取票)。

1、调用方法

Method：HTTP-POST

Url：{API_Url}/train/confirm

Data_Type:json

2、系统参数

请求入参格式

API调用参数分为系统参数和业务参数，请求时，系统参数是必传的，否则无法成功请求，业务参数由具体业务接口定义,所有请求需要指定Content-Type 为"application/json; charset=utf-8"。

所有火车票接口在传入 jsonStr 里都必需包括这几个属性

系统参数
名称 类型 必填 描述
apiKey String 是 分配给供应商的唯一身份标识
sign String 是 请求签名，生成规则参见签名机制
timestamp String 是 时间戳，参见时间戳
data Object 否 请求参数内容，接口消息体密文加密

异步回调请求格式

API请求返回结果目前支持json格式,且返回的消息体是经过BASE64编码过的字符串，解码之后的消息格式字段如下：

返回结果
名称 类型 必填 描述
apiKey String 是 分配给供应商的唯一身份标识
sign String 是 请求签名，生成规则参见签名机制
timestamp String 是 时间戳，参见时间戳
returnCode int 是 结果码，具体值参见API返回码
errorMsg String 否 异常时错误信息
data Object 否 返回结果

同步返回参数格式

返回结果
名称 类型 必填 描述
success Boolean 否 保留字段，固定为true
returnCode int 是 结果码，具体值参见API返回码
errorMsg String 否 异常时错误信息
data Object 否 返回结果

异步回调同步返回格式

返回结果
名称 类型 必填 描述
success boolean true 结果标示

3、业务参数

接口入参

名称 类型 必填 示例值 描述
retailOrderId string 是 合作伙伴方订单号
orderId string 是 交易单号
callBackUrl string 是 回调URL地址

入参示例

{
    "apiKey": "testkey",
    "sign": "testsign",
    "timestamp": "2015-08-03",
    "data": {
        "retailOrderId": "15538430T8393205",
        "orderId": "AC9WSY4H1H00",
        "callBackUrl": "{商户URL}/train /confirmOrderFeedback"
    }
}

接口出参

同步接口出参

名称 类型 必填 示例值 描述
retailOrderId string 是 合作伙伴方订单号
orderId string 是 交易单号

异步接口出参

名称 类型 必填 示例值 描述
retailOrderId string 是 合作伙伴方订单号
orderId string 是 交易单号

出参示例

同步出参示例

{
    "success": true,
    "returnCode": 231000,
    "errorMsg": "",
    "data": {
        "retailOrderId": "15274218T7650055"
    }
}

异步出参示例

{
    "apiKey": "testkey",
    "sign": "testsign",
    "timestamp": "2015-08-03",
    "returnCode": 231000,
    "errorMsg": "",
    "data": {
        "retailOrderId": "15802713T9155536",
        "orderId": "AEME3TJS1H00"
    }
}

4、通用输出参数增加可能出现的值

返回码 错误信息
401 请求时间已超时，出票失败
402 订单不存在
403 账户余额不足
406 确认出票失败
407 当前订单状态不符合出票要求

注：请求时间已超时是指没有在我方规定的时间内发出此出票请求。

5、常见问题

接口说明

此接口是指合作方得到订票成功的反馈后发出请求，我方收到请求将此火车票订单取消。

1、调用方法

Method：HTTP-POST

Url：{API_Url}/train/cancel

Data_Type:json

2、系统参数

请求入参格式

API调用参数分为系统参数和业务参数，请求时，系统参数是必传的，否则无法成功请求，业务参数由具体业务接口定义,所有请求需要指定Content-Type 为"application/json; charset=utf-8"。

所有火车票接口在传入 jsonStr 里都必需包括这几个属性

系统参数
名称 类型 必填 描述
apiKey String 是 分配给供应商的唯一身份标识
sign String 是 请求签名，生成规则参见签名机制
timestamp String 是 时间戳，参见时间戳
data Object 否 请求参数内容，接口消息体密文加密

异步回调请求格式

API请求返回结果目前支持json格式,且返回的消息体是经过BASE64编码过的字符串，解码之后的消息格式字段如下：

返回结果
名称 类型 必填 描述
apiKey String 是 分配给供应商的唯一身份标识
sign String 是 请求签名，生成规则参见签名机制
timestamp String 是 时间戳，参见时间戳
returnCode int 是 结果码，具体值参见API返回码
errorMsg String 否 异常时错误信息
data Object 否 返回结果

同步返回参数格式

返回结果
名称 类型 必填 描述
success Boolean 否 保留字段，固定为true
returnCode int 是 结果码，具体值参见API返回码
errorMsg String 否 异常时错误信息
data Object 否 返回结果

异步回调同步返回格式

返回结果
名称 类型 必填 描述
success boolean true 结果标示

3、业务参数

接口入参

名称 类型 必填 示例值 描述
retailOrderId string 是 合作伙伴方订单号
orderId string 是 交易单号
callBackUrl string 是 回调URL地址

入参示例

{
    "apiKey": "testkey",
    "sign": "testsign",
    "timestamp": "2015-08-03",
    "data": {
        "retailOrderId": "15538430T8393205",
        "orderId": "AC9WSY4H1H00",
        "callBackUrl": "{商户URL}/train /cancelOrderFeedback"
    }
}

接口出参

同步接口出参

名称 类型 必填 示例值 描述
retailOrderId string 是 合作伙伴方订单号

异步接口出参

名称 类型 必填 示例值 描述
retailOrderId string 是 合作伙伴方订单号

出参示例

同步出参示例

{
    "success": true,
    "returnCode": 231000,
    "errorMsg": "",
    "data": {
        "retailOrderId": "15274218T7650055"
    }
}

异步出参示例

{
    "apiKey": "testkey",
    "sign": "testsign",
    "timestamp": "2015-08-03",
    "returnCode": 231000,
    "errorMsg": "",
    "data": {
        "retailOrderId": "15274218T7650055"
    }
}

4、通用输出参数增加可能出现的值

返回码 错误信息
501 订单已出票，不能取消
502 订单不存在
503 系统异常，合作方伙伴订单号没有入库
504 合作方伙伴订单号和交易订单号不一致
505 系统异常，订单状态未知
506 订单状态非法，只有占位成功的订单才能取消
511 订单正在取消中
520 订单状态更新版本失败
521 车票状态更新失败，无法更新订单关联的车票信息
556 取消失败

5、常见问题

接口说明

我方每次可对同一订单的多张车票进行退票处理。即只要所退车票是同一订单内，就可以一次性进行退票处理。根据相关规定，我方只能在不晚于开车前3小时对尚未取票的车票办理网上退票。另外，依据规定，将对每张车票按梯次收取退票手续费：开车前49小时以上，且在15天内，手续费5%；开车前25-49小时之间，手续费10%；开车前25小时内，手续费20%。手续费低2元，按2元计算。最终退票手续费以铁路局实际收取为准。我方将从合作方账户余额中扣除相应的退票手续费，退票款项将会退到合作方的账户余额当中。

线上退票入参和异步返回需要进行数据加密参见消息加密。

1、调用方法

Method：HTTP-POST

Url：{API_Url}/train/return

Data_Type:json

2、系统参数

请求入参格式

API调用参数分为系统参数和业务参数，请求时，系统参数是必传的，否则无法成功请求，业务参数由具体业务接口定义,所有请求需要指定Content-Type 为"application/json; charset=utf-8"。

所有火车票接口在传入 jsonStr 里都必需包括这几个属性

系统参数
名称 类型 必填 描述
apiKey String 是 分配给供应商的唯一身份标识
sign String 是 请求签名，生成规则参见签名机制
timestamp String 是 时间戳，参见时间戳
data Object 否 请求参数内容，接口消息体密文加密

异步回调请求格式

API请求返回结果目前支持json格式,且返回的消息体是经过BASE64编码过的字符串，解码之后的消息格式字段如下：

返回结果
名称 类型 必填 描述
apiKey String 是 分配给供应商的唯一身份标识
sign String 是 请求签名，生成规则参见签名机制
timestamp String 是 时间戳，参见时间戳
returnCode int 是 结果码，具体值参见API返回码
errorMsg String 否 异常时错误信息
data Object 否 返回结果

同步返回参数格式

返回结果
名称 类型 必填 描述
success Boolean 否 保留字段，固定为true
returnCode int 是 结果码，具体值参见API返回码
errorMsg String 否 异常时错误信息
data Object 否 返回结果

异步回调同步返回格式

返回结果
名称 类型 必填 描述
success boolean true 结果标示

3、业务参数

接口入参

名称 类型 必填 示例值 描述
retailOrderId string 是 合作伙伴方订单号
orderId string 是 交易单号
orderNumber string 是 取票单号
callBackUrl string 否 回调URL地址
tickets string 是 车票信息（json字符串数组形式，主要包含车票的乘车人信息，乘车人姓名、乘车人证件类型ID和乘车人证件号码，如：[{“ticketNo”:“E2610890401070051”,“passengerName”:“王二”,“ passportTypeId”:1,“passportNo”:“421116198907143795” }]

Ticket

名称 类型 必填 示例值 描述
ticketNo string 是 车票编号
passengerName string 是 乘客姓名
passportTypeId string 是 乘客证件类型
passportNo string 是 乘客证件号码

入参示例

此接口需要加密，请求为：

{
    "apiKey": "testkey",
    "sign": "testsign",
    "timestamp": "2015-08-03",
    "data": "Base64ResultTest"
}

为方便理解，此处给出解密后的参数示例如下：

{
    "apiKey": "testkey",
    "sign": "testsign",
    "timestamp": "2015-08-03",
    "data": {
        "retailOrderId": "15538430T8393205",
        "orderId": "AC9WSY4H1H00",
        "orderNumber": "E010400222",
        "callBackUrl": "{商户URL}/train/returnTicketFeedback",
        "tickets": [
            {
                "ticketNo": "E0104002221053148",
                "passengerName": "张秀勤",
                "passportTypeId": "1",
                "passportNo": "341222197608254405"
            }
        ]
    }
}

接口出参

同步接口出参

名称 类型 必填 示例值 描述
retailOrderId string 合作伙伴方订单号
orderNumber string 取票单号

异步接口出参

名称 类型 必填 示例值 描述
retailOrderId 合作伙伴方订单号
orderNumber 火车票取票单号
returnTickets
车票退票信息(json字符串数组形式，每张车票包含乘车人信息和退票相关信息，如：["ticketNo":"E2610890401070051","passengerName":"王二","passportTypeId":1,"passportNo":"421116198907143795","returnSuccess":true,"returnMoney":"20.05","returnTime":"2015-02-13 15:00:05","returnFailId":"","returnFailMsg":""}]
returnState 退票状态 true:表示成功 false:表示退票失败
returnMoney 退款金额（成功才有值）线上退票时，此值为退款总额
returnMsg 退票后消息描述（一般当returnState=false时，会显示退票失败原因等）

其中的returnTickets中每张票的退票信息如下：

名称 类型 必填 示例值 描述
ticketNo string 票号
passengerName string 乘客姓名
passportTypeId Int(修正为String) 证件类别编号
passportNo string 证件号码
returnSuccess bool 是否退票成功（true:成功，false:失败）
returnMoney string 退款金额（成功才有值）
insureReturnMoney string 保险退款金额（如果购买了保险）
returnTime string 退票成功的时间（成功才有值）
returnFailId string 退票失败原因编号（失败才有值）
returnFailMsg string 退票失败原因信息（失败才有值）

失败码号及提示信息

returnFailId returnFailMsg
0 退票操作成功[成功时，此值为空]
1 退票操作成功[成功时，此值为空]
2 退票操作异常，请与客服联系
3 已改签
4 已退票
5 已出票，只能在窗口办理退票
6 不可退票

在提供的回调URL中不要发生任何跳转，收到请求后同步返回结果，表明收到我们的通知。

出参示例

同步出参示例

{
    "success": true,
    "returnCode": 231000,
    "errorMsg": "",
    "data": {
        "retailOrderId": "15538430T8393205",
        "orderNumber": "E010400222"
    }
}

异步出参示例

此反馈参数需要加密，请求为：

{
    "apiKey": "testkey",
    "sign": "testsign",
    "timestamp": "2015-08-03",
    "returnCode": 231000,
    "errorMsg": "",
    "data": "Base64ResultTest"
}

为方便理解，此处给出解密后的参数示例如下：

{
    "apiKey": "testkey",
    "sign": "testsign",
    "timestamp": "2015-08-03",
    "returnCode": 231000,
    "errorMsg": "",
    "data": {
        "retailOrderId": "15538430T8393205",
        "orderNumber": "E010400222",
        "returnTickets": [
            {
                "ticketNo": "E0104002221053148",
                "passengerName": "张秀勤",
                "passportTypeId": 1,
                "passportNo": "341222197608254405",
                "returnSuccess": "True",
                "returnFailId": "0",
                "returnTime": "2015-08-29 10:05:54",
                "returnMoney": "122.00"
            }
        ],
        "returnState": true,
        "returnMoney": "122.00",
        "returnMsg": ""
    }
}

4、通用输出参数增加可能出现的值

返回码 错误信息
601 账户余额不足或者被冻结
602 距离开车时间太近无法退票
603 操作请求已接受
604 请求特征参数长度不符合要求
605 该请求已存在请勿重复提交
606 车票不存在或车票状态不正确
607 与退票系统通讯异常
608 处理失败

5、常见问题

接口说明

本接口的应用场景是：合作方的购票人到车站已经取票，然后拿票到窗口去退票，退票的工作人员会和他说这个票款会退到他们的网银里面。退票信息我们会通过此接口返回给合作方，由合作方退款给客户。

1、调用方法

Method：HTTP-POST

Url:商户指定

Data_Type:json

2、系统参数

请求入参格式

API调用参数分为系统参数和业务参数，请求时，系统参数是必传的，否则无法成功请求，业务参数由具体业务接口定义,所有请求需要指定Content-Type 为"application/json; charset=utf-8"。

所有火车票接口在传入 jsonStr 里都必需包括这几个属性

系统参数
名称 类型 必填 描述
apiKey String 是 分配给供应商的唯一身份标识
sign String 是 请求签名，生成规则参见签名机制
timestamp String 是 时间戳，参见时间戳
data Object 否 请求参数内容，接口消息体密文加密

异步回调请求格式

API请求返回结果目前支持json格式,且返回的消息体是经过BASE64编码过的字符串，解码之后的消息格式字段如下：

返回结果
名称 类型 必填 描述
apiKey String 是 分配给供应商的唯一身份标识
sign String 是 请求签名，生成规则参见签名机制
timestamp String 是 时间戳，参见时间戳
returnCode int 是 结果码，具体值参见API返回码
errorMsg String 否 异常时错误信息
data Object 否 返回结果

同步返回参数格式

返回结果
名称 类型 必填 描述
success Boolean 否 保留字段，固定为true
returnCode int 是 结果码，具体值参见API返回码
errorMsg String 否 异常时错误信息
data Object 否 返回结果

异步回调同步返回格式

返回结果
名称 类型 必填 描述
success boolean true 结果标示

3、业务参数

接口入参

名称 类型 必填 示例值 描述
returnState boolean 退票状态 true:表示成功 false:表示退票失败
retailOrderId string 合作伙伴方订单号
orderId string 交易单号
orderNumber string 取票单号
tickets string
车票退票信息(json字符串数组形式，每张车票包含乘车人信息和退票相关信息，如：["ticketNo":"E2610890401070051","passengerName":"王二","passportTypeId":1,"passportseNo":"421116198907143795","returnSuccess":true,"returnMoney":"20.05","returnTime":"2014-02-13 15:00:05","returnFailId":"","returnFailMsg":""}] 注：保留字段，当为线下退票时，此值为空
returnMoney string 退款总额
returnMsg string 退票后消息描述

入参示例

{
    "apiKey": "testkey",
    "sign": "testsign",
    "timestamp": "2015-08-03",
    "returnCode": 231000,
    "errorMsg": "",
    "data": {
        "returnState ": true,
        "retailOrderId": "4HEE0TS42400",
        "orderId": "5ECE0TS42401",
        "orderNumber": "E262577575",
        "tickets": [
            {
                "ticketNo": "E967421083110004D",
                "passengerName": null,
                "passportTypeseId": 0,
                "passportNo": null,
                "returnSuccess": null,
                "returnMoney": null,
                "returnTime": null,
                "returnFailId": null,
                "returnFailMsg": null
            }
        ],
        "returnMoney": " 20.05",
        "returnMsg": "线下退款"
    }
}

接口出参

名称 类型 必填 示例值 描述
success string 是 是否成功

出参示例

{
  "success": true
}

4、通用输出参数增加可能出现的值

返回码 错误信息
701 收到报告信息。

5、常见问题

接口说明

查询某车次的经停站信息

1、调用方法

Method：HTTP-POST

Url：{API_Url}/train/queryStations

Data_Type:json

2、系统参数

请求入参格式

API调用参数分为系统参数和业务参数，请求时，系统参数是必传的，否则无法成功请求，业务参数由具体业务接口定义,所有请求需要指定Content-Type 为"application/json; charset=utf-8"。

所有火车票接口在传入 jsonStr 里都必需包括这几个属性

系统参数
名称 类型 必填 描述
apiKey String 是 分配给供应商的唯一身份标识
sign String 是 请求签名，生成规则参见签名机制
timestamp String 是 时间戳，参见时间戳
data Object 否 请求参数内容，接口消息体密文加密

异步回调请求格式

API请求返回结果目前支持json格式,且返回的消息体是经过BASE64编码过的字符串，解码之后的消息格式字段如下：

返回结果
名称 类型 必填 描述
apiKey String 是 分配给供应商的唯一身份标识
sign String 是 请求签名，生成规则参见签名机制
timestamp String 是 时间戳，参见时间戳
returnCode int 是 结果码，具体值参见API返回码
errorMsg String 否 异常时错误信息
data Object 否 返回结果

同步返回参数格式

返回结果
名称 类型 必填 描述
success Boolean 否 保留字段，固定为true
returnCode int 是 结果码，具体值参见API返回码
errorMsg String 否 异常时错误信息
data Object 否 返回结果

异步回调同步返回格式

返回结果
名称 类型 必填 描述
success boolean true 结果标示

3、业务参数

接口入参

名称 类型 必填 示例值 描述
trainDate string Y 乘车日期（yyyy-MM-dd）
trainCode string Y 车次号

入参示例

{
    "apiKey": "testkey",
    "sign": "testsign",
    "timestamp": "2015-08-03",
    "data": {
        "trainDate": "2015-10-08",
        "trainCode": "G11"
    }
}

接口出参

名称 类型 必填 示例值 描述
trainDate string Y 乘车日期（yyyy-MM-dd）
trainCode string Y 车次号
stations list Y

stations:

名称 类型 必填 示例值 描述
stationId int Y 220 站点ID
stationName string Y 南京南 站点名称
stationNum int Y 1 车站序号
departTime string Y 19:30 出站时间
arriveTime string Y 19:20 到站时间
stayTime string Y 10分钟 停留时间

出参示例

{
    "success": true,
    "returnCode": 231000,
    "errorMsg": "",
    "data": {
        "trainDate": "2015-10-08",
        "trainCode": "G11",
        "stations": [
            {
                "stationId": "220",
                "stationName": "南京南",
                "stationNum": "1",
                "departTime": "19:30",
                "arriveTime": "----",
                "stayTime": "始发站"
            },
            {
                "stationId": "221",
                "stationName": "镇江",
                "stationNum": "2",
                "departTime": "19:50",
                "arriveTime": "19:40",
                "stayTime": "10分钟"
            },
            {
                "stationId": "222",
                "stationName": "上海虹桥",
                "stationNum": "3",
                "departTime": "20:00",
                "arriveTime": "20:00",
                "stayTime": "终点站"
            }
        ]
    }
}

4、通用输出参数增加可能出现的值

返回码 错误信息
801 查询失败
802 无此车次

5、常见问题

接口说明

身份证验证接口

1、调用方法

Method：HTTP-POST

Url：{API_Url}/train/validate

Data_Type:json

2、系统参数

请求入参格式

API调用参数分为系统参数和业务参数，请求时，系统参数是必传的，否则无法成功请求，业务参数由具体业务接口定义,所有请求需要指定Content-Type 为"application/json; charset=utf-8"。

所有火车票接口在传入 jsonStr 里都必需包括这几个属性

系统参数
名称 类型 必填 描述
apiKey String 是 分配给供应商的唯一身份标识
sign String 是 请求签名，生成规则参见签名机制
timestamp String 是 时间戳，参见时间戳
data Object 否 请求参数内容，接口消息体密文加密

异步回调请求格式

API请求返回结果目前支持json格式,且返回的消息体是经过BASE64编码过的字符串，解码之后的消息格式字段如下：

返回结果
名称 类型 必填 描述
apiKey String 是 分配给供应商的唯一身份标识
sign String 是 请求签名，生成规则参见签名机制
timestamp String 是 时间戳，参见时间戳
returnCode int 是 结果码，具体值参见API返回码
errorMsg String 否 异常时错误信息
data Object 否 返回结果

同步返回参数格式

返回结果
名称 类型 必填 描述
success Boolean 否 保留字段，固定为true
returnCode int 是 结果码，具体值参见API返回码
errorMsg String 否 异常时错误信息
data Object 否 返回结果

异步回调同步返回格式

返回结果
名称 类型 必填 描述
success boolean true 结果标示

3、业务参数

接口入参

名称 类型 必填 示例值 描述
name string Y 张三 姓名
identityType int Y 1 证件类型 1、身份证
identityCard string Y 365521000254456642 证件号码

入参示例

{
    "apiKey": "testkey",
    "sign": "testsign",
    "timestamp": "2015-08-03",
    "data": [
        {
            "name": "张三",
            "identityType": 1,
            "identityCard": "365521000254456642"
        }
    ]
}

接口出参

名称 类型 必填 示例值 描述
identityCard string Y 证件号码
identityType int Y 证件类型
isPass int Y 是否通过 0 、通过 1、不通过
error string N 原因,通过时此值为空字符

出参示例

{
    "success": true,
    "returnCode": 231000,
    "errorMsg": "",
    "data": [
        {
            "identityCard": "365521000254456642",
            "identityType": 1,
            "isPass": 1,
            "error ": "身份证未通过核验"
        }
    ]
}

4、通用输出参数增加可能出现的值

返回码 错误信息
901 系统异常

5、常见问题

火车票M站分销对接准备表

基本信息

对接信息

支付对接需填写

支付对接需填写

支付对接需填写

文件体积不超过 2M

支付对接需填写

支付对接需填写, 文件体积不超过 2M

支付对接需填写

Copyright © 2006-2016 南京途牛科技有限公司 Tuniu.cn | 营业执照 | 苏 ICP证 B2-20070191 旅游网
联系人： openapi@tuniu.com 联系号码：02586853969-61247