综合交通-商家对接
定制巴士接口文档API说明
一、商家对接流程
整体流程
1.商家入驻奇门
接入流程
登录：qimen.taobao.com
入驻奇门 -> 选择官方场景 -> API实现 -> API自测 -> 发布上线 -> 配置授权 -> 对方调用
API发布并配置了授权后意味着接口可以给授权方调用该接口，对于某些场景，可能需要调用对方，那么需要对方也按着流程来发布接口。
配置授权的时候可以选择测试环境和线上环境，测试环境可以用来联调。具体参考下面的配置授权说明。
一、 商家接入奇门：
地址 ：奇门接入入口地址
如图，找到对应的奇门官方场景（新）并选择关联。如果列表为空或者找不到对应的官方场景，请对接群联系技术支持（玄虎/沈雨平）需要添加才可以正常显示出来。
添加成功后：
二、商家自测
这里的测试环境和正式环境分别对应前面填写的正式和测试的两个地址。
注意！API没有发布之前无法选择正式环境，请选择测试环境。因为API还没上线，选择线上环境会提示ApiName不合法
三、开发发布接口
验签示例代码:
四 、商家按接口开发完，发布到飞猪测试环境和线上环境，成功后通知我们联调测试，
待飞猪同学配置后，商家先做拉班次接口自测，登录商家后台点商品管理的车次测试，输入参数就可自测，失败、成功都会给提示
https://busagent.fliggy.com/busAgentNumberTest.htm
校验失败
校验成功：
校验成功后联系飞猪同学
二、文档说明
版本号 |
作者 |
日期 |
说明 |
0.1 |
王硕/雨平 |
2022.9.9 |
（班次接口）isOrderRefund 退票类型（单/票） |
0.2 |
王硕 |
2022.11.1 |
新增同步新增数据接口taobao.bus.item.notify |
0.3 |
|||
1.1概述
本文档主要描述定制客运接入飞猪销售端口的接口设计规范，以及进行订单数据交互操作的过程中遵循的规范和约束。为相关参与人员提供一份参考文档，方便快速了解两端对接的开发流程和注意事项，规范两端接口对接过程。
1.2术语
接入商：需要通过API接口将商品同步到飞猪网站售卖的商家
服务商：接入商提供API接口服务的系统
奇门：代表飞猪往外部调用，需要提供URL和访问账号及秘钥
TOP：代表系统商可以通过TOP平台进行消息回调
1.3报文约束
- 所有的HTTP请求操作要求必须?持POST请求类型。
- 所有请求HTTP-HEAD都包含Content-Type: application/json;charset=UTF-8。
- 所有的请求、响应报?都必须采?UTF-8字符编码。
- 所有请求请求、响应报?都是json格式。
- 所有返回的HTTP状态码必须是200。
- 所有请求报?格式：
{
“head”:{
“channel”:”xxx”,
“sign”:”xxxxxxxx”
},
“body”:{}
}
head和body节点不允许缺失。 - 所有返回报?格式：
{
“head”:{
“code”:1,
“message”:”错误消息”
},
“body”:Object
CTRIP_BUS_API_3.3 7
}
head和body节点不允许 缺失。
1.4安全约束
1.5其他
- 数据主要流向是客户端主动拉取接入商服务系统的数据。
- 飞猪客户端会在所有请求url后?添加.json后缀，?便服务端拓展不同请求资源。
- 需要提供测试环境?便联调测试。
三、接口详细说明
3.1定制巴士查询城市接口
https://open.taobao.com/api.htm?docId=63238&docType=2
（1）查询城市名称获得出发省份/城市信息（2）cityCode按照国家行政区域进行实别。
3.2定制巴士查询到达城市接口
https://open.taobao.com/api.htm?docId=63237&docType=2
说明：查询到达城市信息
3.3定制巴士查询班次接口
https://open.taobao.com/api.htm?docId=63236&docType=2
（1）注意点：segmentPrices 可支持分段计价，A->B-C-D-E 每个分站点可支持不同价格
（2） stationType 如果是一个固定点，需要传经纬度
（3）stationFeature 用户在搜索的时候C端会单独展示出不同类型的标签方便用户购买不同类型的汽车票，比如：机场专线，etc
注意：geofence 需要至少三个经纬度围成一个范围，并且三个经纬度需要按照顺时针/逆时针传递，不可交叉。
举例：经纬度按照 A-B-C-D-E顺时针传递经纬度，不可以A点和C点这样交叉
(4) 往返
backDays 仅支持3天内返程，0代表当天，1表示第二天，1表示第三天
（5）退票规则举例：1.发车前3小时，不可退票； 发车前3-6小时内退手续费25%。 2.发车6小时-24小时手续费10%。 3.发车24小时-48小时手续费5%。 4.发车48小时以外无退票手续费
（6）transferPoints 是数据集合，如果存在多个中转地点，按照集合方式返回
name换乘地点（必填）其他参数可以根据可根据业务需求提供
（7）流水班
fromtimetype=4 固定时间段发车
scheduleId 需要保证唯一
这个唯一标识一旦生成，以后每次同步都不能变，一旦变了就会认为是新车次。
查询余座、创建订单都传这个字段
（8）退票模式：ture：订单维度退 false：票维度退
3.4定制巴士查询到达余票接口
https://open.taobao.com/api.htm?docId=63235&docType=2
查询余票信息
leftTicketCnt 回传剩余票数
（注意点）ticketPrice 如果有价格变动需要把新的价格更新过来，前端进行拦截
3.5定制巴士创建订单接口
https://open.taobao.com/api.htm?docId=63228&docType=2
该接口是实时调用，请保证返回数据一致性
sucess 返回失败会进行重试，
startTime发车时间有变动会导致下单失败
3.6定制巴士查询订单详情接口
https://open.taobao.com/api.htm?docId=63227&docType=2
证件类型：1代表身份证
isRrefund 如果线下已经退票，请及接口同步，该接口实时更新
3.7定制巴士订单确认(出票)接口
https://open.taobao.com/api.htm?docId=63226&docType=2
检票口：可在订单详情进行展示（可配置出票短信）
ticketNo 用于订单详情展示（可配置出票短信）
ticketPwd 用户用于取票/乘车（可配置出票短信）
电子票二维码乘车
3.8定制巴士退票确认接口
https://open.taobao.com/api.htm?docId=63225&docType=2
用户在飞猪进行提交退票，会调用该接口和商家进行确认，
超时/失败返回错误原因
退票成功后详情页同步
3.9定制巴士查询退票手续费接口
https://open.taobao.com/api.htm?docId=63224&docType=2
refundSurcharge 手续费 （单位 分）
passengerId 非必传，如果要传，仅支持数字
3.10定制巴士查询停运班次接口
查询停运班次，可通过实际应用场景查看
https://open.taobao.com/api.htm?docId=63223&docType=2
3.11城际巴士关闭订单接口
关闭订单接口，可通过实际应用场景查看
https://open.taobao.com/api.htm?docId=64430&docType=2
四、错误码
1.订单状态
编码 |
说明 |
备注 |
1 |
等待付款(锁单，占座成功) |
创建订单成功后 |
2 |
等待出票(已经付款，出票中) |
调用出票接口后，接入商没有实时返回出票状态 |
3 |
出票成功 |
出票成功，但是没有给出具体的票码号 |
4 |
订单关闭 |
调用出票接口后，接入商非同步返回，超时未调用出票回填。 |
5 |
订单取消 |
创建订单后，用户超时未支付。调用接入商取消订单接口。 |
9 |
退票订单退票中 |
退票中 |
11 |
退票成功 |
全部退票成功 |
2.票状态码
编码 |
说明 |
备注 |
1 |
出票中 |
锁单、出票中场景 |
2 |
已出票 |
出票成功场景 |
3 |
无票 |
出票失败场景 |
4 |
退票中 |
申请退票中场景 |
5 |
已退票 |
退票成功 |
6 |
退票失败 |
退票失败 |
-1 |
未知 |
未知 |
FAQ
商家店铺经营信息相关入驻
商家中心缴纳保证金
汽车票城际巴士车次变更通知飞猪接口
taobao.bus.item.notify( 汽车票城际巴士车次变更通知飞猪接口 )
https://open.taobao.com/api.htm?docId=65541&docType=2
退票接口
场景1：只退款，（不管票状态，不管下线退/线上退）
taobao.bus.agent.multiple.refund.confirm( 综合交通多次退款接口 )
https://open.taobao.com/api.htm?docId=49134&docType=2
场景2：异步退票，线上提交退票，商家退票成功之后调用该接口通知我们进行退款
taobao.bus.agent.refund.confirm( 汽车票退票和退款二合一接口 )
https://open.taobao.com/api.htm?docId=42022&docType=2
出票回调接口/退票回调接口
taobao.bus.agent.bookticket.confirm
出票回调接口：
https://open.taobao.com/api.htm?docId=25473&docType=2
taobao.bus.agent.refund.confirm
退票回调接口：（找玄虎/沈雨平授权权限包）
https://open.taobao.com/api.htm?docId=42022&docType=2
