文档中心 > 酒店客栈

创建订单请求详解

更新时间:2023/12/04 访问次数:67015
  • 场景
  1. 预订页面,客人完成信息录入,提交订单
  • 要求
  1. 根据去啊订单号做幂等处理,即同一订单,多次调用返回相同结果,且在CRS不重复预订
  2. 不要求立即返回预订结果,反馈接收成功,然后异步处理
  3. 处理能力要有合理评估并告知,去啊会根据性能要求投放流量

第三方系统根据此接口定义实现预定订单方法,并暴露成服务。去啊系统在用户下单时调用第三方的预定订单服务来创建订单。

接收阿里旅行调用接口方式
1. 由第三方提供一个接收阿里请求的服务地址(注意:所有的接口请求均用这个相同的地址),以及用于验证的用户名和密码。
2. 第三方根据请求参数中的xml父节点区分业务请求类型,根据文档要求开发接收请求数据和返回相应的数据

下单基本业务流程图:

请求参数

名称

类型

是否必须

最大长度/取值范围

描述

示例值

Username

String

100

第三方系统接口调用需要校验时的用户名。

taobao

Password

String

100

第三方系统接口调用需要校验时的密码

taobao

CreateToken

String

255

单次请求token

taobao1387784033263-1387784033266

TaoBaoOrderId

long

 

淘宝订单id,第三方需根据此id判断订单是否已经存在,以实现幂等和避免重复下单。

1387784033263

TaoBaoHotelId

long

 

淘宝酒店id

123456789

HotelId

String

64

OTA酒店id,即第三方系统中的酒店id

80

TaoBaoRoomTypeId

long

 

淘宝房型id

123456978

RoomTypeId

String

64

OTA房型id,即第三方系统中的房型id

1205

TaoBaoRatePlanId

long

 

淘宝价格计划id

123000123

RatePlanCode

String

64

OTA价格计划id,即第三方系统中的价格计划id

VIP

Channel

String

64

酒店投放渠道

阿里员工协议价 : A 

飞猪商旅用户价 : O 

公开价: H

 A

TaoBaoGid

long

 

淘宝酒店商品id

1234567890

CheckIn

Timestamp

yyyy-MM-dd

HH:mm:ss

入住时间

2013-12-24

CheckOut

Timestamp

yyyy-MM-dd

HH:mm:ss

离店日期。

注:小时房默认离店日期等同于入住日

期,如有特殊需求请联系技术支持

2013-12-26

HourRent

String

5

小时房字段,客人实际入住时长

3.5

EarliestArriveTime

Timestamp

yyyy-MM-dd HH:mm:ss

最早到店时间

2013-12-24 20:00:00

LatestArriveTime

Timestamp

yyyy-MM-dd HH:mm:ss

最晚到店时间

2013-12-24 22:00:00

RoomNum

int

取值:1-9

房间数量(最大为9)

1

Occupancy

int

取值:1-15

入住人数,目前支持一笔订单最多入住人数15。例如别墅订单存在多人的情况。

2

PriceType

int

取值:0,1

下单使用的价格类型:0默认值;1变价订单价格标记

说明:如果是变价订单,则表示不需要做价格校验

0

IsMorningBuy

int

取值:0,1

是否为凌晨房,0不是,1是,默认0

0

InventoryType

int

取值:0,1,2,3,4

下单使用的库存类型:

0.未知;1限售库存;2保留房库存;3物理库存;4超预定库存

0

TotalPrice

long

 

订单总价(分)

63850

OtherFee

long

 

授权杂费金额(分)

50000

PaidPrice

long

 

已付金额(预付和在线预约场景下启用)

63850

TotalSellerPromotion

long

 

卖家优惠总金额

2000

GTPrice

long

 

订单担保金额(担保订单场景下启用)

63850

GTStartTime

Timestamp

HH:mm

担保生效时间(峰时担保场景下启用)

18:00

GTType

int

0,1,2

担保类型(0无担保、1首晚(峰时/全天)、2全额)

0

Currency

String

长度:30

取值: CNY

货币类型(现在只支持一种)

CNY

PaymentType

int

取值:1、5

订单实际支付方式1预付、5面付、6信用住(现在只有1、5、6)

5

ContactName

String

32

联系人姓名

公泰

ContactTel

String

32

联系人电话

138000000

ContactEmail

String

可选

255

联系人邮箱

123@taobao.com

DailyInfos

DailyInfos

 

每日价格

 

OriDailyInfos

List<DailyInfo>

 

每日原始价格

当存在卖家优惠的时候启用

DisDailyInfos

List<DailyInfo>

 

每日折扣价格

当存在卖家优惠的时候启动

Day

Date

yyyy-MM-dd

日期

2013-12-24

Price

long

 

价格(分)

12354

BreakFast

int

 

早餐数量

1

OrderType

int

取值0,1

订单类型0普通客户订单 1飞猪集团订单 2 代订订单

0

Company

String

 

公司名称

阿里巴巴集团

OrderGuests

OrderGuests

 

入住人信息

 

Name

String

32

姓名

张三

IdType

 int 取值:0-99 入住人证件号码类型 0:身份证 1:护照 2:学生证 3:军官证 4:回乡证 5:台胞证 6:港澳通行证 7:国际海员 8:外国人永久居留(身份)证 9:其他证件 10: 警官证 11:士兵证 12:台湾通行证 13:入台证 14:户口簿 15:出生证明 16:中国驾照 17:港澳居民居住证 18:台湾居民居住证 0

IdCode

 String 128 入住人证件号码,证件号码类型根据idType决定  123456789

RoomPos

int

取值:1-9

房间序号

1

PersonType
int  取值:1,2

1成人类型;2儿童类型

 
Age
int  

年龄

儿童必填,成人不需要关注年龄信息

 

Comment

String

255

备注、特殊需求

要安静的房间

CardCode String 32 信用卡类型:AX美国运通卡,MC(MASTERCARD),DC大莱,JC(JCB),VA(VISA) AX,MC,DC,JC,VA
CardHolderName String 256 持卡人姓名 张三
ExpirationDate String 10 客人选择的有效期 格式: 月/年,例如:07/19
CardNumber String 256 信用卡卡号 543546464545
CvvCode String 64 信用卡ccv号 768

NeedInvoice

int 取值:0,1

是否要开发票

0不需要,1需要

EarllyPrepare

int 取值:0,1

是否要提前开发票

0不需要,1需要
SubmitTime String 20 提交开发票请求时间 (格式yyyy-MM-dd HH:mm:ss)
WantTime String 20 需要发票时间 (格式yyyy-MM-dd HH:mm:ss)
PostType int 取值:0,1,2,3,4 发票领取方式 0:前台自取 1:邮寄 2:电子发票 3: 送至房间
InvoiceType int 取值:1,2 发票类型 1:增值税普通发票;2:增值税专用发票
Comment String 一段文本 开票项目 一段文本(例如:代订房费、住宿费、会议费、旅游费等)
InvoiceTitle String   发票抬头  
CompanyTel String   公司电话  
CompanyTax String   公司税号  
RegisterAddress String   公司注册地址  
Bank String  

开户行

 
BankAccount String  

银行账号

 
ReceiverAddress String   邮寄地址  
ReceiverName String   收件人姓名  
ReceiverMobile String   收件人手机号

MemberName

String

 

会员姓名

李雷

MemberFliggyNum

String

 

飞猪会员编号

123456

MemberOutNum

String

 

OTA会员编号

222222

MemberIdCard

String

 

会员证件号码

33100419670324121X

MemberPhone

String

 

会员电话

12548604178

MemberEmail

String

 

会员邮箱

taobao@test.com

MemberFliggyLevel

String

 

飞猪会员等级

 F1

MemberOutLevel

String

 

OTA会员等级

 V1

BookMemberName

 String    预订人会员名称  小李
BookMemberFliggyNum  String    预订人飞猪会员号  1122
BookMemberOutNum  String    预订人商家会员号  A123
BookMemberPhone  String    预订人会员电话  13434567856
BookMemberEmail  String    预订人会员邮箱  test@taobao.coom
BookMemberFliggyLevel  String    预订人飞猪会员等级  F1
BookMemberOutLevel  String    预订人飞猪商家等级  V1

GuaranteeType

String

 

担保类型

0 无担保 1 峰时首晚担保 2峰时全额担保 3全天首晚担保 4全天全额担保

AlipayTradeNo

String

64

支付宝交易号

支付宝交易号,只有预付的先付款后下单会有这个

VoucherInfos

VoucherInfos

 

订单优惠节点

当订单中含有优惠(房券/代金券/立减等)

VoucherPomotionAmt

String

 

卖家优惠金额

2000 单位:分

VoucherPomotionDesc

String

 

活动描述

双十一首晚优惠

VoucherRuleDesc

String

 

优惠规则描述

订单金额200以上

VoucherOutCode

String

 

商家活动编码

12345

VoucherTid

String

64

购买房券/代金券的订单id

123456789

VoucherId

String

64

房券/代金券ID

12345

VoucherNum

int

 

核销次数,房券时有效,默认0

1

PaidFee

long

 

用户购买一张在线预约房券/代金券真实付费金额(分),默认0

9000

PackageInfo

 

 

订单关联包对象

 

Desp

String

 

订单维度所有关联包描述,分号分隔

每间3张北京植物园门票;每晚2份酒店SPA

DimensionType

String

 

使用维度:每间 每晚 每入住人

每晚

Quantity

int

 

数量

1

Unit

String

 

单位

Name

String

 

产品名称

北京植物园

SubDesp

String

 

单个礼包描述

每间3张北京植物园门票

Code

String

 

酒+X的外部code

test001

Extensions

String

 

扩展字段json,用于处理特殊OTA个性需求添加的扩展字段

{"key":"value"}

一些优惠信息等在扩展字段中传递,也可根据商家需求做增添。如:

key: appoint_id  代表此订单中在线预约产品的订单号,具体值在对应的value中传输

TravelInfo

TravelInfo

   商旅订单信息节点 子节点OrderType不为0,表示企业统一支付订单

OriginPaymentType

int

  商品原始支付类型,1:预付,5: 面付,7: 预付在线预约 1

HourRoomArriveTime

Timestamp

 yyyy-MM-dd HH:mm:ss 小时房字段,客人实际选择到店时间 2020-05-18 14:00:00

HourRoomLeaveTime

Timestamp

 yyyy-MM-dd HH:mm:ss 小时房字段,客人实际选择离店时间 2020-05-18 18:00:00
OnlineBookingItemSellerPromotion  Long    在线预约宝贝(第一单)卖家优惠金额,单位分,可空  1000

 

:1.DailyInfosOrderGuests是两个复合类型,详见下面XML示例

2.Extensions 字段用于支持特殊OTA个性需求,普通的OTA不用关注

XML示例:

 

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<BookRQ>

    <AuthenticationToken>

        <Username>taobao</Username>

        <Password>taobao</Password>

        <CreateToken>taobao1387784033263-1387784033266</CreateToken>

    </AuthenticationToken>

    <TaoBaoOrderId>1387784033263</TaoBaoOrderId>

    <TaoBaoHotelId>123456789</TaoBaoHotelId>

    <HotelId>80</HotelId>

    <TaoBaoRoomTypeId>123456978</TaoBaoRoomTypeId>

    <RoomTypeId>ST</RoomTypeId>

    <TaoBaoRatePlanId >123000123</TaoBaoRatePlanId >

    <RatePlanCode>VIP</RatePlanCode>

    <Channel>A</Channel>

    <TaoBaoGid>1234567890</TaoBaoGid>

    <CheckIn>2013-12-24</CheckIn>

    <CheckOut>2013-12-26</CheckOut>

    <HourRent>3</HourRent>

    <EarliestArriveTime>2013-12-24 20:00:00</EarliestArriveTime>

    <LatestArriveTime>2013-12-24 22:00:00</LatestArriveTime>

    <RoomNum>1</RoomNum>

    <Occupancy>1</Occupancy>

    <PriceType>1</PriceType>

    <IsMorningBuy>0</IsMorningBuy>

    <InventoryType>1</InventoryType>

    <TotalPrice>63850</TotalPrice>

    <OtherFee>50000</OtherFee>

    <PaidPrice>63850</PaidPrice>

    <TotalSellerPromotion>2000</TotalSellerPromotion>

    <GTInfo>

        <GTPrice>1000</GTPrice>

        <GTStartTime>18:00</GTStartTime>

        <GTType>1</GTType>

    </GTInfo>

    <Currency>CNY</Currency>

    <PaymentType>5</PaymentType>

    <ContactName>测试联系人</ContactName>

    <ContactTel>13920682209</ContactTel>

    <ContactEmail >hello@taobao.com</ContactEmail >

    <DailyInfos>

        <DailyInfo>

            <Day>2013-12-24</Day>

            <Price>17800</Price>

            <BreakFast>2</BreakFast>

            <GiftInfo>送水果;接机一次</GiftInfo>

        </DailyInfo>

        <DailyInfo>

            <Day>2013-12-25</Day>

            <Price>46050</Price>

            <BreakFast>1</BreakFast>

        </DailyInfo>

    </DailyInfos>

    <OriDailyInfos>

        <DailyInfo>

            <Day>2013-12-24</Day>

            <Price>19800</Price>

        </DailyInfo>

        <DailyInfo>

            <Day>2013-12-25</Day>

            <Price>46050</Price>

        </DailyInfo>

    </OriDailyInfos>

    <DisDailyInfos>

        <DailyInfo>

            <Day>2013-12-24</Day>

            <Price>2000</Price>

        </DailyInfo>

        <DailyInfo>

            <Day>2013-12-25</Day>

            <Price>0</Price>

        </DailyInfo>

    </DisDailyInfos>

    <TravelInfo>

        <OrderType>0</OrderType>

        <Company>阿里巴巴去啊</Company>

    </TravelInfo>

    <OrderGuests>

        <OrderGuest>

            <Name>入住人1</Name>

            <RoomPos>1</RoomPos>

            <PersonType>1</PersonType>      //表示成人

            <IdType>1</IdType>

            <IdCode>123456789123456789</IdCode>

        </OrderGuest>

        <OrderGuest>

            <Name>入住人2</Name>

            <RoomPos>1</RoomPos>

            <PersonType>2</PersonType>      //表示儿童

            <Age>12</Age>

        </OrderGuest>

    </OrderGuests>

    <Comment>测试</Comment>

    <GuaranteeType> 0</GuaranteeType>

    <MemberInfo>

        <MemberName>李雷</MemberName>

        <MemberFliggyNum>1234555</MemberFliggyNum>

        <MemberOutNum>222222</MemberOutNum>

        <MemberPhone>13548604167</MemberPhone>

        <MemberEmail>taobao@test.com</MemberEmail>

        <MemberFliggyLevel>1</MemberFliggyLevel>

        <MemberOutLevel>1</MemberOutLevel>

        <MemberIdCard>33100419670324121X</MemberIdCard>

        <BookMemberName>韩梅梅</BookMemberName>

        <BookMemberFliggyNum>2234555</BookMemberFliggyNum>

        <BookMemberOutNum>322222</BookMemberOutNum>

        <BookMemberPhone>13548604168</BookMemberPhone>

        <BookMemberEmail>taobao@test.com</BookMemberEmail>

        <BookMemberFliggyLevel>1</BookMemberFliggyLevel>

        <BookMemberOutLevel>1</BookMemberOutLevel>

    </MemberInfo>

    <AlipayTradeNo>201603333333333333333330859999</AlipayTradeNo>

    <VoucherInfos>

        <VoucherInfo>

            <VoucherPomotionAmt>10000</VoucherPomotionAmt>

            <VoucherPomotionDesc>双十一首晚优惠</VoucherPomotionDesc>

            <VoucherRuleDesc>订单金额200以上</VoucherRuleDesc>

            <VoucherOutCode>12345</VoucherOutCode>

            <VoucherTid>123456789</VoucherTid>

            <VoucherId>12345</VoucherId>

            <VoucherNum>1</VoucherNum>

            <PaidFee>9000</PaidFee>

        </VoucherInfo>

    </VoucherInfos>

    <CreditCardInfo>

        <CardCode>VISA</CardCode>

        <CardHolderName>zhuran</CardHolderName>

        <ExpirationDate>07/19</ExpirationDate>

        <CardNumber>1223223</CardNumber>

        <CvvCode>768</CvvCode>

        <VccCreditCurrencyCode>USD</VccCreditCurrencyCode>

        <VccCreditAmount>10000</VccCreditAmount>

    </CreditCardInfo>

    <InvoiceInfo>

        <NeedInvoice>1</NeedInvoice>

        <EarllyPrepare>1</EarllyPrepare>

        <SubmitTime>2016-06-24 00:12:21</SubmitTime>

        <WantTime>2016-06-24 00:12:21</WantTime>

        <PostType>1</PostType>

        <InvoiceType>1</InvoiceType>

        <Comment>代订房费</Comment>

        <InvoiceTitle>淘宝(中国)软件有限公司</InvoiceTitle>

        <CompanyTel>13548604153</CompanyTel>

        <CompanyTax>12345567777</CompanyTax>

        <RegisterAddress>浙江省杭州市余杭区文一西路001</RegisterAddress>

        <Bank>中国工商银行</Bank>

        <BankAccount>123434353545353344</BankAccount>

        <ReceiverAddress>浙江省杭州市余杭区文一西路002</ReceiverAddress>

        <ReceiverName>小李子</ReceiverName>

        <ReceiverMobile>13548604154</ReceiverMobile>

    </InvoiceInfo>

    <PackageInfos>

        <Desp>每间3张北京植物园门票;每晚2份酒店SPA</Desp>

        <PackageInfo>

            <DimensionType>每间</DimensionType>

            <Quantity>3</Quantity>

            <Unit></Unit>

            <PackageType>1</PackageType>

            <Name>北京植物园</Name>

            <SubDesp>每间3张北京植物园门票</SubDesp>

            <Code>test001</Code>

        </PackageInfo>

        <PackageInfo>

            <DimensionType>每晚</DimensionType>

            <Quantity>2</Quantity>

            <Unit></Unit>

            <PackageType>6</PackageType>

            <Name>SPA</Name>

            <SubDesp>每晚2份酒店SPA</SubDesp>

            <Code>test002</Code>

        </PackageInfo>

    </PackageInfos>

    <OriginPaymentType>1</OriginPaymentType>

    <HourRoomArriveTime>2020-05-18 14:00:00</HourRoomArriveTime>

    <HourRoomLeaveTime>2020-05-18 20:00:00</HourRoomLeaveTime>

    <OnlineBookingItemSellerPromotion>1000</OnlineBookingItemSellerPromotion>

    <Extensions></Extensions>

</BookRQ>



 

返回结果(成功/失败)

名称

类型

是否必须

限制

范围

描述

示例值

Message

String

100

处理结果

处理成功

ResultCode

String

0 参见ResultCode描述表

参见ResultCode描述表

0

OrderId

String

100

OTA订单id,即第三方系统中的订单id

21544874

PmsResID

String

100

PMS的确认单号

F15F190223

Comment

String

100

外部订单说明

渠道来源/其他标识信息

syncToHotel

String

2

是否把代理直签的订单同步到酒店,Y为同步,N不同步

Y

XML示例:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<Result>

       <Message>创建订单成功</Message>

       <ResultCode>0</ResultCode>

       <OrderId >21544874</OrderId >

       <PmsResID > F15F190223</PmsResID >

       <Comment> 渠道A订单</Comment>

       <syncToHotel>Y</syncToHotel>

</Result>

 

返回结果(异步)

名称

类型

是否必须

限制

范围

描述

示例值

Message

String

100

第三方系统异步创建订单

接收到去啊订单

ResultCode

String

取值:0

处理结果,resultCode为0并且Message和OrderId为空表示为异步下单,已经接受到阿里旅行下单请求,需要在后续的查询消息中返回第三方订单号. (如果查询多次没有第三方订单号订单会自动失败)

0

 

OrderId

String

100

OTA订单id,即第三方系统中的订单id

21544874

syncToHotel

String

2

是否把代理直签的订单同步到酒店,Y为同步,N不同步

Y

XML示例:

 

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<Result>

       <Message></Message>

       <ResultCode>0</ResultCode>

       <OrderId ></OrderId >

      <syncToHotel>Y</syncToHotel>

</Result>

返回结果(失败)

名称

类型

是否必须

限制范围

描述

示例值

Message

String

300

错误原因

生成订单错误

ResultCode

String

取值:-100,-101,-102,-103,-104,-105

错误码,参见ResultCode描述表

-100

XML示例:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<Result>

       <Message>满房</Message>

       <ResultCode>-101</ResultCode>

</Result>

返回结果定义表

以下是第三方接到创建订单请求后,处理成功或失败时应该返回的结果。此表已定义结果类型不会修改,但可能会根据业务情况进行增补。返回的错误码为-100,-102,去啊系统将会将下单对应的item下架。

特别说明:返回码为0并且Message和OrderId为空,表示第三系统收到去啊订单,第三方系统将会异步执行创建订单。

ResultCode

Message

备注

0

第三方订单id

resultCode为0并且Message和OrderId为空表示为异步下单

-100

生成订单失败:{具体原因}

请尽量用其他的更详细的失败错误码

-101

{

    "reason": "满房",

    "dailyInventory": [{"date":"2015-04-03","inventory":0},{"date":"2015-04-04","inventory":0},{"date":"2015-04-05","inventory":1}]

}

Json格式。预定的房型在用户选择的入离店日期内已经满房或者不接受预定。

dailyInventory是客户下单日期间的库存,date是格式yyyy-MM-dd的日期,inventory表示库存,0表示无库存。示例表示4月3日、4月4日无房,4月5日有1间房。去啊旅行将根据返回的库存信息将去啊系统里的库存更新。

-102

自定义原因

message填入详细信息。请尽量使用其他的更详细的错误码。

-103

{

    "reason": "价格校验失败",

    "precisDailyPrice": [{"date":"2015-04-03","price":"18000"},{"date":"2015-04-04","price":"19000"}]

}

淘宝酒店下单请求里的每日价格、总价与第三方系统的每日价格、总价不匹配。precisDailyPrice表示正确的第三方价格。去啊旅行将根据precisDailyPrice更新去啊系统里的价格。

-104

第三方系统异常

第三方系统接到请求后,系统异常不能创建订单,请返回此错误码。第三方系统返回此错误码,去啊系统将自动将卖家从搜索中屏蔽。

-105

不符合预订政策:{具体不符合的政策}

订单不符合第三方的预订政策。例如,预订政策要求提前3天预订,但订单预订的是第二天的房间,不符合预订政策。

“不符合预订政策”为必须的,具体原因可选。

示例1:不符合预订政策:{需提前三天预订}

示例2:不符合预订政策:{}

-106

重复预定

重复预定

-107

预定房间数超过限制

预定房间数超过限制

-108

最早到店时间不合法:{具体不合法原因说明}

最早到店时间不合法:{具体不合法原因说明}

-109

最晚到店时间不合法:{具体不合法原因说明}

最晚到店时间不合法:{具体不合法原因说明}

-110

联系人姓名不合法:{具体不合法原因说明}

联系人姓名不合法:{具体不合法原因说明}

-111

联系电话不合法:{具体不合法原因说明}

联系电话不合法:{具体不合法原因说明}

-112

超过入住人数限制

超过入住人数限制

-113

酒店id不存在

酒店id不存在。去啊将把此酒店关闭,设置为不可卖。

-114

房型不存在

房型不存在。去啊将把此房型关闭,设置为不可卖。

-115

价格政策不存在

价格政策不存在。去啊将把此rp关闭,设置为不可卖。

-116

参数错误:{具体参数不合法说明}

参数错误:{具体参数不合法说明}

 

注:此文档会根据业务需要进行适当增删除。

FAQ

关于此文档暂时还没有FAQ
返回
顶部