概述

• 线下票：依赖商家线下票机出票的订单
• 定制票：线下电子票，KTZ开头的车次以及动卧，可以按照用户指定的席位进行选座（24小时），GDC开头的车次以及非动卧，12306非售卖时间进行出票。

涉及接口

1.消息

• taobao_train_TradeNotify（出、退、改通用）

2.出票联调相关接口

• taobao.train.agent.order.get.vtwo 订单详情信息
• taobao.train.agent.handleticket.confirm.vtwo 锁单接口
• taobao.train.agent.bookticket.confirm.vtwo 出票结果接口
• taobao.train.agent.bookorders.get.vtwo 获取待出票的订单
• taobao.tmc.user.permit 注册商家消息

3.退票联调相关接口

• taobao.train.agent.returnorders.get.vtwo 获取待退票的订单
• taobao.train.agent.returnticket.confirm.vtwo 同意/拒绝退票
• taobao.train.agent.returnticketinfo.get.vtwo 获取线下票退票信息
• taobao.train.agent.handrefund.refundfee 代理商手动退款接口

4.改签联调相关接口

• taobao.train.agent.untreatedchange.query.vtwo 查询待处理改签单列表
• taobao.train.agent.changeorderdetail.query.vtwo 查询跑腿改签订单详情
• taobao.train.agent.changeissue.confirm.vtwo 跑腿改签出票回填

工具平台

• TMC消息相关资料

商家调用流程

1.出票流程图

2.退票流程图

3.改签流程图

商家接入流程

1. 商家入驻前置流程

• 代扣账号申请

• 用途：退款时代理商代扣账户，需要签署无密代扣协议

2. 商家入驻TOP平台

• 参考文档：https://open.alitrip.com/docs/doc.htmtreeId=113&articleId=104093&docType=1
• 重要参数：appkey、agentId、agentNick
• 预发API地址：http://pre-gw.api.taobao.com/top/router/rest
  预发消息地址：ws://premc.api.taobao.com

3. 商家对接火车票行业

• 提供必要参数，如：客服工作时间、官方联系方式等。

消息/接口工作原理说明

买家支付后，通过订阅接受tmc消息taobao_train_TradeNotify（TMC消息相关资料）获取到订单，然后通过订单详情接口获取订单信息，必须对接待出票列表接口，防止tmc消息丢失后无法查询到待出票信息，获取订单信息后
消息名称：taobao_train_TradeNotify

1.通知出票tmc消息

{

"time_stamp":1592219975110,

"user_id":2994085846,

"main_biz_order_id":1063056341145084658,

"extra":"10", ---10:线下票类型

"description":"book-xxx",

"msg_type":"1",

"sub_biz_order_id":0

}

2.通知退票tmc消息

• returnticket-agentId 消息
• 消息参数增加offline_refund_type字段：退票类型
• msg_type = 6

3.通知本人退tmc消息

• msg_type = 9

4.通知改签tmc消息

出票相关接口说明

1.代理商获取待出票订单列表

• 接口：taobao.train.agent.bookorders.get.vtwo
• 说明：代理商获取待出票订单列表

2.代理商获取订单信息

• 接口：taobao.train.agent.order.get.vtwo
• 说明：代理商获取订单信息
• 出参示例

{

   "train_agent_order_get_vtwo_response":{

       "ttp_order_id":1234,

       "is_success":true,

       "main_order_id":123456,

       "tickets":{

           "to_agent_ticket_info":[

               {

                   "student_info":{

                   },

                   "sub_order_id":"123456",

                   "from_station":"北京",

                   "from_time":"2013-08-08 08:08:00",

                   "to_station":"上海",

                   "seat":1,

                   "train_num":"G101",

                   "passenger_name":"亚里士多德",

                   "certificate_num":"123456",

                   "certificate_type":"0",

                   "insurance_price":1000,

                   "ticket_price":10000,

                   "birthday":"2013-08-08",

                   "to_time":"2013-08-08 08:08:00",

                   "tag":1,

                   "insurance_unit_price":1000,

                   "passenger_type":0,

                   "segment_index":1,

                   "nationality":"澳大利亚",

                   "nationality_code":"AU",

                   "valid_until":"2022-11-07",

                   "gender":"1",

                   "telephone":"13811111111",

                   "real_ticket_price":

                  "support_no_seat":fase      --是否支持无座

               }

           ]

       },

       "total_price":50000,

       "telephone":"12345678900",

       "mailing":false,

       "address":"",

       "relation_name":"姓名",

       "company_name":"淘宝网",

       "order_status":1,

       "latest_issue_time":"2000-01-01 00:00:00",

       "order_type":0,

       "paper_type":1,

       "paper_backup":0,

       "paper_low_seat_count":1,

       "transport_name":"张三",

       "transport_phone":"18098890900",

       "transport_address":"地址",

       "transport_price":2000,

       "service_price":2000,

       "extend_params":"备用",

       "online_book_seat":"用户在线选座的值",

       "interchange_station":"中转站",

       "is_multi_trip":"是否为连程",

       "need_receipt":false,              ---是否需要开发票 true：是 false：否

       "accept_no_vip_custom":0,         ---是否接受非定制票 1:是 0:否

       "vip_custom_min_seat_count":1,   ---至少接受定制票数量，

       "vip_custom_type":1               ---定制票类型 0:不指定坐席 1:下铺 2:下铺or中铺 3:过道 4:靠窗

       "vip_custom_list":{               --优先级大于定制类型，兼容之前的vip_custom_type、vip_custom_min_seat_count、accept_no_vip_custom 这里的信息，可以只使用此list

         "vip_custom_result_item":[{              

           "custom_type":"carriage",//定制车厢

           "count":1,//辅营份数，多少人选定制数字为几

           "carriage_custom":{

                       "string":[

                           "07",

                           "08",

                           "09"

                       ]

                   },//定制车厢号

           "accept_no_vip_custom":1//是否接受非定制,0不接受,1接受

     "segment_index":1//联程订单定制序号,1一程，2二程

         },

         {

           "custom_type":"adjacencySeat",//定制连坐

           "count":1,//辅营份数,多少人选定制数字为几

           "accept_no_vip_custom":1//是否接受非定制,0不接受,1接受

     "segment_index":1//联程订单定制序号,1一程，2二程

         },

         {

           "custom_type":"onlineBooking",//在线选座

           "count":4,//辅营份数

             "carriage_custom":{

                       "string":[

                       ]

                   },//定制车厢号

           "seat_custom":"1A1B2C2D#2A2B2C2D",//在线选座信息

           "accept_no_vip_custom":1//是否接受非定制,0不接受,1接受

          "segment_index":2//联程订单定制序号,1一程，2二程

         }]}

   }

}

• 重要参数解析

3.代理商锁单接口

• 名称：taobao.train.agent.handleticket.confirm.vtwo
• 说明：代理商出票中（锁定票）
• 下单付款成功后，用户可取消订单。商家出票时，应先调用锁单接口，调用成功后用户则不可取消订单

4.代理商出票接口

• 名称：taobao.train.agent.bookticket.confirm.vtwo
• 说明：火车票代理商接口——确认出票是否成功
• 出票规则：
  KTZ开头的车次和动卧：
  1、用户接受了其他坐席accept_no_vip_custom = 1,卧铺类型按下铺>中铺>上铺的规则出，硬座类型没有要求，随机即可
  2、如果用户没有接受其他坐席accept_no_vip_custom = 0，不能满足定制票出票要求，直接失败
  3、如果用户接受其他坐席accept_no_vip_custom = 1，按照定制票最大化原则，规则同上面第一条
  GDC开头的车次（除去动卧）
  由于12306本身支持以上车次选座，所以规则有所不同
  1、GDC开头的车次（除去动卧）accept_no_vip_custom字段只会为1，vip_custom_type 字段为0，online_book_seat如果没有值，单人：靠窗>过道>其他，多人：相邻>同一车厢>不同车厢
  2、如果有值（1A2F），优先按照用户选座信息进行购买，如果没有用户需要的席位，剩下的规则同上

一单多人的情况：

如果一单多人，多人中只有一部分人定制了坐席，则剩余的用户应优先保证跟定制了坐席的用户座位相近（比如硬座高铁邻座、卧铺同包厢）；若用户可接受其它坐席，则出票时应优先保证能按照用户定制的需求出票，在无法保证或只能部分满足的情况，则应尽量保证同一单的用户座位相近。

• 出参示例

{

   "order_type":10,

   "agent_id":1231231321312312321,

   "main_order_id":2139262129924275458,

   "boarding_gates":"3",

   "from_station_name":"平凉",

   "dep_date":"2021-10-07 13:10:00",

   "extend_params":"{\"alipay_trade_no\":\"2021092822001198371452872199\",\"is_fliggy_multi_trip\":false,\"paper_low_passage_count\":0,\"need_receipt\":false,\"orderIdOn12306\":\"\",\"vip_settlement_mode\":\"CASH\"}",

   "can_change":false,

   "ticket_12306_id":"EDW333",

   "ticket_num":1,

   "tickets":[

       "4984170046;100;1;硬座_1车_2号;6074;小张;0;1231231231231;0;0"

   ],

   "alipay_trade_no":"商家电子票支付流水",

   "arrive_date":"2021-10-07 13:25:00",

   "ticket_info_list":[

       {

           "passenger_name":"小张",

           "cert_type":0,

           "ttp_sub_order_id":4984170046,

           "seat_num":"硬座_1车_2号",

           "ticket_no":"EDW333",

           "vip_custom_result":1,

          "vip_custom_result_list":[{

            "custom_type":"carriage",//定制车厢

           },{

      "custom_type":"vipTicketCorridorSeat",//定制过道

           }]

           "insurance_pay_price":0,

           "real_seat":1,

           "train_no":"6074",

           "certificate_num":"1231231231231",

           "real_ticket_price":100

       }

   ],

   "alipay_account":"商家电子票支付账号",

   "to_station_name":"平凉南",

   "fail_msg":"0",

   "status":true

}

• 重要参数：
  1、vip_custom_result字段，代理商需要标记出该票的是否是定制票出票，是打标1，否打标0，如果整票出票失败，该字段不用填写；这个标记的判断规则代理商内部吃掉，我们只关心打标的结果，规则如下：
  如果是卧铺，打标要保证100%正确，因为有下、中、上的中文标识
  如果是硬座（过道/靠窗），尽量保证正确，可以减少投诉
  如果GDC开头的车次（非卧铺），尽量保证按照用户所选坐席（1A2D）出票
  2、ticket_12306_id(12306取票号)，必须回填
  3、ticket_no（12306子票号）字段，扩展字段，目前看线下电子票12306是只返回了1个取票号的，这里暂时按这个票号填写；后续如果12306也返回了子票号的话，这里修改成新的
  4、vip_settlement_mode在出票成功时，需放到 extend_params 扩展字段中回传，通过订单详情接口拉取到此标识字段（在扩展字段中）

5.元数据说明

5.1出票失败错误码

退票相关接口说明

1.代理商获取待退票订单列表

• 接口： taobao.train.agent.returnorders.get.vtwo
• 说明：代理商获取待退票订单列表

2.同意/拒绝退票

• 接口： taobao.train.agent.returnticket.confirm.vtwo
• 说明：跑腿退：refund_fee = 真实退票价格 - 跑腿费
• 目前退票类型为三类：跑腿退；车站退；本人退
• 重要参数

3.获取线下票退票信息

• 接口： taobao.train.agent.returnticketinfo.get.vtwo
• 说明：代理商获取线下票退票信息

4.代理商手动退款接口

• 接口： taobao.train.agent.handrefund.refundfee
• 说明：当商家收到回款时，而用户未主动发起退款，可以调该接口进行退款处理
• 注：此接口会直接退款不关心票状态，请商家审计好后使用

5.元数据说明

5.1退票失败错误码

改签相关接口说明

1.代理商获取待改签订单列表

• 接口： taobao.train.agent.untreatedchange.query.vtwo
• 说明：查询待处理改签单列表
• 出参示例：

{

"train_agent_untreatedchange_query_vtwo_response": {

"request_id": "x2deg4el5c1e",

"untreated_change_apply_ids": "520744121553,520744129999,52033221553,52078889999",

"untreated_change_order_num": 4

}

}

2.同意/拒绝改签

• 接口： taobao.train.agent.changeissue.confirm.vtwo
• 说明：跑腿改签出票回填
• 出参示例：

{

"change_to_station": "北京北",

"alipay_trade_no": "1111111111111111",

"ttp_order_id": 43333222111,

"agent_id": 222333444,

"change_to_date_time": "2023-01-01 12:00:00",

"change_from_date_time": "2023-01-01 12:00:00",

"issue_fail_code": 8,

"issue_status": 1,

"change_settlement_mode": 1,

"change_tickets": [

{

"change_seat_type_code": "o",

"e_ticket_no": "e1212121212122",

"change_fee": 100,

"change_seat_type_name": "二等座",

"change_ticket_price": "1000",

"sub_order_id": 5342332323,

"handing_fee": 100,

"change_seat_no": "001",

"change_coach_no": "01",

"ticket_type_name": "成人票",

"ticket_type_code": "1",

"change_coach_name": "01",

"change_apply_id": 53232323234

}

],

"alipay_account": "123@alipay.com",

"tp_order_id": 43333222111,

"change_train_date": "20230101",

"change_apply_id": 53333111,

"change_train_code": "G1",

"change_from_station": "北京",

"sequence_no": "E1W123456"

}

3.获取线下票改签信息

• 接口： taobao.train.agent.changeorderdetail.query.vtwo
• 说明：查询跑腿改签订详情信息
• 出参示例：

{

"train_agent_changeorderdetail_query_vtwo_response": {

"change_apply_order": {

"agent_id": 222333444,

"change_apply_id": 520744121553,

"change_from_date_time": "2023-01-05 12:00:00",

"change_from_station": "重庆西",

"change_from_station_code": "CXW",

"change_issue_timeout": "2023-01-05 12:00:00",

"change_ticket_type": 0,

"change_to_date_time": "2023-01-05 12:00:00",

"change_to_station": "成都东",

"change_to_station_code": "ICW",

"change_train_code": "G102",

"change_train_date": "20230105",

"change_type": 0,

"original_from_date_time": "2023-01-05 12:00:00",

"original_from_station": "重庆西",

"original_from_station_code": "CXW",

"original_sequence_no": "EJ123456789",

"original_to_date_time": "2023-01-05 12:00:00",

"original_to_station": "成都东",

"original_to_station_code": "ICW",

"original_train_code": "G101",

"original_train_date": "20230105",

"settlement_mode": 1,

"status": 0,

"ticket_price_all": 100,

"ticket_total_num": 2,

"tp_id": 1779715812572607883,

"ttp_id": 4812850813378

},

"change_apply_sub_orders": {

"change_apply_sub_order_d_t_o": [

{

"agent_id": 333444555,

"certificate_no": "11012312345678001",

"certificate_type_code": "二代身份证",

"certificate_type_name": "1",

"original_coach_name": "01",

"original_coach_no": "01",

"original_seat_no": "003A",

"original_seat_type_code": "o",

"original_seat_type_name": "二等座",

"original_ticket_price": "400",

"passenger_name": "张三",

"sub_order_id": 330744121553,

"ticket_type_code": 1,

"ticket_type_name": "成人票"

},

{

"agent_id": 333444555,

"certificate_no": "11012312345678002",

"certificate_type_code": "二代身份证",

"certificate_type_name": "1",

"original_coach_name": "01",

"original_coach_no": "01",

"original_seat_no": "003B",

"original_seat_type_code": "o",

"original_seat_type_name": "二等座",

"original_ticket_price": "400",

"passenger_name": "李四",

"sub_order_id": 33074499993,

"ticket_type_code": 1,

"ticket_type_name": "成人票"

}

]

},

"request_id": "x2dehcls6f8s"

}

}

4.元数据说明

4.1改签失败错误码