易途吧开放平台使用说明 v2.1

目录

概述

易途吧开放平台提供了标准的境外用车业务包含询价、下单的全套接口。通过平台API,用户可实现自有业务系统和易途吧的境外用车服务进行对接。

主要功能

  1. 境外用车询价,及根据询价结果向易途吧下单
  2. 可于用车前更新乘客信息
  3. 可于用车前取消订单
  4. 机场/城市等基础数据支持

接口地址

生产环境:api.yitu8.com.cn

测试环境:api.yitu8.ltd

通讯方式

接口仅支持 HTTP 协议的 POST 方法,通过 BODY 传递 Json 格式的请求参数,接口 URL 区分大小写。请求以及返回都使用 UTF-8 字符集进行编码。接口返回的数据封装为统一的 Json 格式。文档中所列举的类型皆为 Java 语言的数据类型,其它编程语言的的数据类型请自行对应。格式详见:返回数据类型

建议在HTTP请求头中设置以下参数:

参数名参数值
Acceptapplication/json
Content-Typeapplication/json

所有接口的请求参数需要封装为统一的 Json 格式,属性名称区分大小写。数据类型如下:

类型属性是否必需属性说明
StringpartnerId必需4位分销商数字编号
Stringtimestamp必需接口调用时间,格式为:yyyy-MM-dd HH:mm:ss
Stringsign必需数据签名
Stringdata必需加密的请求参数

数据加密

接口请求参数请使用 secretKey 进行 3DES 加密后输出 hex 并转大写,作为 data 的属性值进行传递。

数据签名

数据签名使用 MD5 摘要算法,32位小写,具体的签名算法为:

MD5(partnerId + timestamp + data + secretKey)

  1. partnerIdsecretKey 为易途吧分配给接入用户的分销商编号和密钥
  2. timestamp 为接口调用时间(yyyy-MM-dd HH:mm:ss)
  3. data 为加密后的请求参数

返回数据类型

类型属性属性说明
Booleansuccess接口调用是否成功,成功:true;失败:false
Integercode错误代码,2xx代表成功,4xx或5xx代表失败
Stringmessage错误消息,描述了接口调用失败原因
Objectdata接口返回数据
Objectoption附加数据,如分页数据的总条数

回目录

基础数据接口

查询机场

根据条件查询易途吧机场基础信息,支持分页搜索。

接口URL:/car/common/getAirportList

查询机场参数如下:

类型属性是否必需属性说明
Stringkeyword非必需关键词,支持机场中文名,英文名,三字码模糊搜索
StringcityId非必需机场所属城市ID
StringfirstChars非必需机场所属城市首字母
IntegercountryType非必需搜索机场类型,0.境外;1.境内;2.全部
Integerpage非必需页码,默认为1
IntegerpageSize非必需单页数量,默认为20条数据

接口返回数据类型:

类型属性属性说明
Stringid机场ID
Stringname机场名称
StringenName机场英文名
StringfirstChar机场所属城市首字母
StringcountryId所属国家ID
Stringcountry所属国家名称
StringcityId所属城市ID
Stringcity所属城市名称
StringiataCode机场三字码
BigDecimallongitude机场经度
BigDecimallatitude机场纬度

请求参数示例:

返回结果示例:

回目录

查询城市

根据条件查询易途吧城市基础信息,不支持分页搜索

接口URL:/car/common/getCityList

查询城市参数如下:

类型属性是否必需属性说明
IntegercountryType必需搜索城市类型,0.境外;1.境内;2.全部
Stringkeyword必需关键词,支持城市中文名,英文名搜索

接口返回数据类型:

类型属性属性说明
Stringid城市ID
Stringname城市名称
StringenName城市英文名
StringfirstChar城市首字母
StringcountryId所属国家ID
Stringcountry所属国家名称
StringprovinceId所属州省ID
Stringprovince所属州省名称
StringcountryEnName所属国家英文名
BigDecimallongitude城市中心点经度(境内城市为空)
BigDecimallatitude城市中心点机场纬度(境内城市为空)

请求参数示例:

返回结果示例:

回目录

查询地址列表

查询地址列表及经纬度,不支持分页搜索

接口URL:/car/map/getAddressListByKeyword

查询经纬度参数如下:

类型属性是否必需属性说明
Stringkeyword必需地址关键词
BigDecimallongitude非必需目标城市的经度
BigDecimallatitude非必需目标城市的纬度

接口返回数据类型:

类型属性属性说明
Stringname地址名称
Stringaddress详细地址
Stringlongitude地址经度
Stringlatitude地址纬度

请求参数示例:

返回结果示例:

回目录

境外用车业务接口

询价

用户指定的用车时间(当地)、行程计划,即可通过询价接口获取相应的各种车型的报价, 多个行程时如果包括接机,则接机必须在第一个行程,如果包括送机,则送机必须在最后一个行程。

接口URL:/car/order/queryPrice

询价参数如下:

类型属性是否必需属性说明
StringuseTime必需用车时间(当地时间),格式为:yyyy-MM-dd HH:mm:ss
List<Schedule>schedules必需一个或多个行程计划

【Schedule】数据类型:

类型属性是否必需属性说明
IntegerproductType必需用车类型,详见用车类型说明
StringuseDate多日包车必需用车日期(当地时间),格式为:yyyy-MM-dd
StringuseTime详见说明当地用车时间,格式为:yyyy-MM-dd HH:mm:ss
StringairportCode接送机必需机场三字码
StringfromCityId必需出发城市ID
StringfromCity必需出发城市名称
StringfromAddressName详见说明出发地名
StringfromAddress详见说明出发地详细地址
StringfromLongitude详见说明出发地经度
StringfromLatitude详见说明出发地纬度
StringtoCityId详见说明目的地城市ID
StringtoCity详见说明目的地城市名称
StringtoAddressName详见说明目的地名
StringtoAddress详见说明目的地详细地址
StringtoLongitude详见说明目的地经度
StringtoLatitude详见说明目的地纬度

用车类型说明

0.不出车;1.接机;2.送机;3.单次接送;4.市内包车;5.周边包车;6.跨城包车;7.半日包车;8.线路包车;8.指定时长里程包车

询价参数说明

  1. 最后一天行程只有送机时 useTime 必需;
  2. 除多日包车的非首日行程外,fromAddressName、fromAddress、fromLongitude、fromLatitude等四个出发地参数皆为【必需】参数;
  3. 除接送机、单次接送、跨城包车外,toCityId、toCity、toAddress、toAddressName、toLongitude、toLatitude等六个目的地参数为【非必需】参数,出发城市=到达城市(到达城市不传默认出发城市);

接口返回数据类型:

类型属性属性说明
StringpriceMark价格标识
List<PriceAddition>additions附加服务
List<ServiceTag>serviceTags服务标签
List<CarType>carTypes车型列表
IntegerfreeChildSeat免费儿童座椅数量
Integerdistance预估里程,单位米
Integerduration预估时长,单位分钟

【PriceAddition】数据类型:

类型属性属性说明
Stringsid唯一标识
Stringcontent附加服务名称
BigDecimalprice单价

【ServiceTag】数据类型:

类型属性属性说明
Stringsid唯一标识
Stringcontent服务标签名称

【CarType】数据类型:

类型属性属性说明
StringcarTypeId车型编号
Stringname车型名称
Stringtypical代表车型
StringimageUrl车型图片
BigDecimalsetPrice价格
IntegermaxPassenger最大载客数
IntegermaxLuggage最大行李数
DateTimelatestTime车型报价有效时间

请求参数示例:

返回结果示例:

回目录

下单

用户根据询价返回的标识,选择对应车型进行下单。

接口URL:/car/order/addOrder

下单参数如下:

类型属性是否必需属性说明
StringthirdOrderNo必需第三方订单号
StringpriceMark必需询价返回的价格标识
StringcarTypeId必需所选车型ID
BigDecimaltotalAmount非必需订单总金额
Stringremark非必需订单备注
PassengerInfopassengerInfo必需乘客信息
List<PriceAddition>additions非必需附加服务
List<Flight>flightList非必需航班号集合,如有接送机的行程则为必需

【PassengerInfo】数据类型:

类型属性是否必需属性说明
StringcontactName必需联系人姓名
StringcontactPhone必需联系人号码,格式为:区号-号码,如86-18158117651
StringwechatNo非必需联系人微信号
Integeradults必需成人数
Integerchildren必需儿童数
Integerluggages必需行李数
StringbackupPhone非必需备用号码,格式为:区号-号码,如86-18158117651
StringhotelPhone非必需酒店/民宿电话

【PriceAddition】数据类型:

类型属性是否必需属性说明
Stringsid必需唯一标识
Stringcount必需附加服务个数
Detaildetail非必需附加服务详细信息

【Detail】数据类型:

类型属性是否必需属性说明
StringpickupName非必需举牌姓名
List<String>pickupImages非必需举牌图片外网链接

【Flight】数据类型:

类型属性是否必需属性说明
IntegerproductType必需套餐类型:1.接机;2.送机
StringflightNo必需航班号

接口返回数据类型:

类型属性属性说明
StringorderNo易途吧订单号

请求参数示例:

返回结果示例:

回目录

更新乘客信息

根据易途吧订单号或第三方订单号(用户系统订单号)更新乘客信息,只需要传修改过的属性。

接口URL:/car/order/updateOrder

更新订单参数如下:

类型属性是否必需属性说明
StringorderNo必需易途吧订单号
StringthirdOrderNo非必需第三方订单号
PassengerInfopassengerInfo必需乘客信息

【PassengerInfo】数据类型:

类型属性是否必需属性说明
StringcontactName非必需联系人姓名
StringcontactPhone非必需联系人号码,格式为:区号-号码,如86-18158117651
Integeradults非必需成人数
Integerchildren非必需儿童数
Integerluggages非必需行李数
StringbackupPhone非必需备用号码,格式为:区号-号码,如86-18158117651
StringwechatNo非必需联系人微信号
StringhotelPhone非必需酒店/民宿电话

请求参数示例:

返回结果示例:

回目录

取消订单

根据易途吧订单号或第三方订单号(用户系统订单号)取消订单。

接口URL:/car/order/cancelOrder

取消订单参数如下:

类型属性是否必需属性说明
StringorderNo必需易途吧订单号
StringthirdOrderNo非必需第三方订单号
StringcancelReason非必需取消原因

请求参数示例:

返回结果示例:

回目录

查询退款政策

根据易途吧订单号查询取消订单可退款金额及相应的退款政策。

接口URL:/car/common/getCancelOrderInfo

查询退款政策参数如下:

类型属性是否必需属性说明
StringorderNo必需易途吧订单号

接口返回数据类型:

类型属性属性说明
BigDecimalrefundAmount应退款金额
BigDecimaldeductAmount违约金金额
List<String>remark退款文案信息

请求参数示例:

返回结果示例:

申请发票

根据易途吧订单号申请开票。

接口URL:/car/finance/applyInvoice

申请发票参数如下:

类型属性是否必需属性说明
StringorderNo必需易途吧订单号
DecimalapplyAmount必需申请开票金额
IntegertitleType必需抬头类型 1:个人 2:公司
Stringemail必需电子邮箱(收取发票)
Stringtitle必需发票抬头
StringregNumber公司必需公司注册税号
Stringaddress选填公司营业地址
Stringphone选填公司营业电话
Stringbank选填公司开户行
Stringaccount选填公司银行帐号

接口返回数据类型:

类型属性属性说明
StringinvoiceId易途吧发票申请单号

请求参数示例:

返回结果示例:

回目录

取消发票

根据易途吧订单号取消发票。

接口URL:/car/finance/cancelInvoice

取消发票参数如下:

类型属性是否必需属性说明
StringorderNo必需易途吧订单号

请求参数示例:

返回结果示例:

回目录

查询发票

根据易途吧订单号查询开票状态。

接口URL:/car/finance/queryInvoice

取消订单参数如下:

类型属性是否必需属性说明
StringorderNo必需易途吧订单号

接口返回数据类型:

类型属性属性说明
Integerstatus开票状态:1:待开票 2:已开票 3:已取消
Stringremark取消原因
请求参数示例:  

返回结果示例:

回目录

境外用车回调接口

易途吧需要平台接入方提供三个回调接口来实现:确认订单、推送司机信息和推送订单服务完成功能。平台接入方必须向易途吧注册一个固定的 DOMAIN/URL 参数,该参数若发生变化,需提前通知易途吧进行修改。

回调接口仅支持 HTTP 协议的 POST 方法,通过 BODY 传递 Json 格式的请求参数。请求以及返回都使用 UTF-8 字符集进行编码。URL格式为:http://{DOMAIN/URL}/{API},如:http://api.yitu8.cn/order/confirmOrder

回调接口的请求参数的封装、数据签名、加密方法以及返回的数据类型同易途吧提供的数据接口。如调用成功,应返回以下数据:

如调用失败,应于 message 中返回错误的原因,同时 successfalsecode400。例如:

确认订单

调用易途吧下单接口成功后,易途吧需要回调第三方的确认接口以确认订单。

回调API:confirmOrder

确认订单参数如下:

类型属性属性说明
StringorderNo易途吧订单号
StringthirdOrderNo第三方订单号

请求参数示例:

返回结果示例:

回目录

推送司机信息

调用易途吧下单接口成功后,司机接单后向第三方推送司机信息。

回调API:pushDriverInfo

推送司机信息参数如下:

类型属性属性说明
Integertype类型:1.已派司机;2.改派司机
StringorderNo易途吧订单号
StringthirdOrderNo第三方订单号
StringdriverName司机姓名
StringdriverMobile司机手机号
StringdriverWechat司机微信
StringcarNumber服务车辆车牌号
StringcarBrandName车辆品牌
StringcarColor车辆颜色

请求参数示例:

返回结果示例:

回目录

完成订单

调用易途吧下单接口成功后,司机接单完成服务后向第三方推送订单完成信息。

回调API:orderFinished

完成订单参数如下:

类型属性属性说明
StringorderNo易途吧订单号
StringthirdOrderNo第三方订单号

请求参数示例:

返回结果示例:

回目录

无忧行需求单接口

列表接口

无忧行需求单列表

URL:/ota/manage/jego/list

列表接口参数如下:

类型属性属性说明
intstatus需求单状态:1待录单 2已录单 3待取消 4已取消
stringorderIdyt8订单号
stringthirdOrderId无忧行订单号
intpage页数
intpageSize每页条数

请求参数示例:

返回结果示例:

返回参数说明

参数名类型说明
successBoolean是否成功 true Or false
codeInteger状态码
messageString错误信息
optionObject条数
dataobj对象返回值
  recordCountint待录单数量
  cancelCountint待取消数量
  listobj数组该状态订单的对象数组
    order_idstringyt8订单号
    third_order_idstring无忧行订单号
    use_typeint用车类型:1接机 2送机
    pricebigdecimal售卖价
    created_timedate下单时间
    local_timedate用车时间(当地)
    car_modelstring所需车型
    statusint状态 0 已关闭 1待录单 2已录单 3待取消 4已取消

获取详情

无忧行需求单详情

URL:/ota/manage/jego/get

列表接口参数如下:

类型属性属性说明
Stringid需求单uuid

请求参数示例:

返回结果示例:

返回参数说明

参数名类型说明
successBoolean是否成功 true Or false
codeInteger状态码
messageString错误信息
optionObject条数
dataobj对象返回值
  recordCountint已录单数量
  cancelCountint已取消数量
  listobj数组该状态订单的对象数组
    order_idstringyt8订单号
    third_order_idstring无忧行订单号
    use_typeint用车类型:1接机 2送机
    pricebigdecimal售卖价
    created_timedate下单时间
    local_timedate用车时间(当地)
    car_modelstring所需车型
    statusint状态 0 已关闭 1待录单 2已录单 3待取消 4已取消

能否确认需求单

无忧行能否确认需求单

URL:/ota/manage/jego/would/confirm

列表接口参数如下:

类型属性属性说明
Stringid需求单uuid

请求参数示例:

返回结果示例:

返回参数说明

参数名类型说明
successBoolean是否成功 true Or false
codeInteger状态码
messageString错误信息
optionObject条数
dataobj对象返回值
  orderIdstringyt8订单号(成功状态返回)
  thirdOrderIdstring无忧行订单号(成功状态返回)

确认需求单

无忧行确认需求单

URL:/ota/manage/jego/confirm

列表接口参数如下:

类型属性属性说明
Stringid需求单uuid
StringorderIdyt8订单号
StringthirdOrderId无忧行订单号

请求参数示例:

返回结果示例:

返回参数说明

参数名类型说明
successBoolean是否成功 true Or false
codeInteger状态码
messageString错误信息
optionObject条数,
dataobj对象返回值

取消需求单

无忧行取消需求单

URL:/ota/manage/jego/cancel

列表接口参数如下:

类型属性属性说明
Stringid需求单uuid

请求参数示例:

返回结果示例:

返回参数说明

参数名类型说明
successBoolean是否成功 true Or false
codeInteger状态码
messageString错误信息
optionObject条数,
dataobj对象返回值

无法取消需求单

无忧行取消需求单

URL:/ota/manage/jego/cannot/cancel

列表接口参数如下:

类型属性属性说明
Stringid需求单uuid
Stringreason不能取消的原因

请求参数示例:

返回结果示例:

返回参数说明

参数名类型说明
successBoolean是否成功 true Or false
codeInteger状态码
messageString错误信息
optionObject条数,
dataobj对象返回值

获取日志

获取日志

URL:/ota/log/jego/getById

列表接口参数如下:

类型属性属性说明
Stringid需求单uuid

请求参数示例:

返回结果示例:

返回参数说明

参数名类型说明
successBoolean是否成功 true Or false
codeInteger状态码
messageString错误信息
optionObject条数,
dataobj对象返回值
  idStringuuid
  jegoDemandIdstring需求单uuid
  creatorstring操作人
  createdTimedate创建时间
  contentstring内容