优惠券相关接口

扩展接口只对部分客户开放，需要业务配合。对接前请和华住的商务沟通，签署补充协议

业务说明:

优惠券使用PKID标识不同类型的券，华住会按照券的类型给企业分配额度，企业发券给用户受额度限制（接口7.1.5）。这里说的优惠券只是一种类型，不是具体某一张券。接口7.1.1，7.1.3都是查询优惠券类型信息。

用户领取优惠券之后才可以使用，我们把用户领取优惠券的动作称为绑券（接口7.1.7）。具体的优惠券在用户绑券的时候生成，每张优惠券有一个券码couponNo，标识这一张券。

优惠券的开始日期beginDate、截至日期endDate标识该类型券的使用时间范围，在时间范围内下单才可以使用（只影响下单时间，与订单的入住时间无关）。这个时间范围一般设置的比较大，比如设置1年。具体某张优惠劵的可用时间，在用户绑券操作的时候计算得出，比如绑定之后7天之内可用。每张优惠券上用bindedTime标识用户绑定的时间。绑定后生效时间bindBeginDate，绑定后结束时间bindEndDate标识这张券的使用时间范围。如果这个时间范围超过优惠券的时间范围，则受到优惠券时间的限制。比如，活动在4/30日结束（endDate），客户4/25日绑定优惠券（bindedTime)，绑定后30天有效，优惠券截至日期是5/25（bindEndDate)，到4/30活动就结束了，5/25这个日期在这里无效。

有些类型的优惠券会设置绑定日期控制delayEffectDay，比如绑定之后3天才可以使用。绑定后生效时间就是绑定日期加3天。

用户预订具体酒店的时候，接口7.1.8会按照预订日期和酒店筛选出用户所有的优惠券中可以在当前当前订单中使用的券。

企业查询可以分配的优惠券列表

企业查询当前有哪些类型的优惠券可以分配给用户，以及每种类型券的额度信息

接口地址：coupon/getCouponList

请求方式：POST

请求参数说明：

参数名	参数类型	备注	是否必填	示例值
cardId	String	公司卡号	是	VCENTCRM0002220001
cardPassWord	String	公司卡密码	是	TestPassword

请求示例：

{
 "cardId": "VCENTCRM0002224829",
 "cardPassWord": "123321a"
}

返回参数说明：

参数名	参数类型	备注
code	code	状态码 200 成功! 500 应用程序繁忙，请稍后再试! 521 企业V卡号或者验证码错误!
message	String	响应消息
content	List<SendCouponDTO>	优惠券列表

SendCouponDTO

参数名	参数类型	备注
pkId	String	优惠券Id
balanceCount	Integer	剩余额度
totalCount	Integer	总额度
couponInfo	CouponInfoDTO	优惠券信息

CouponInfoDTO

参数名	参数类型	备注
pkId	String	优惠券Id
name	String	优惠券名称
type	String	优惠劵类型 AMOUNT:定额; VIP_AMOUNT:固定价; DISCOUNT:折扣
value	number	优惠券面额
startDate	Date	有效期开始时间
endDate	Date	有效期结束时间

返回示例：

{
  "code": "200",
  "message": "成功!",
  "content": [
    {
      "pkId": "3323",
      "totalCount": 100,
      "balanceCount": 1,
      "couponInfo": {
        "pkId": "3323",
        "name": "测试优惠券",
        "type": "AMOUNT",
        "value": 100,
        "startDate": "2021-07-01 00:00:00",
        "endDate": "2021-08-01 00:00:00"
      }
    }
  ]
} 

企业根据券码查询优惠券详情

接口地址：coupon/getCouponDetail

请求方式：POST

请求参数说明：

参数名	参数类型	备注	是否必填	示例值
cardId	String	公司卡号	是	VCENTCRM0002220001
cardPassWord	String	公司卡密码	是	TestPassword
couponNo	String	优惠券码。个人绑券接口会返回	是	E4815D54DD604D8BB392219DB604A63C

请求示例：

{
  "cardId": "VCENTCRM0002224829",
  "cardPassWord": "123321a",
  "couponNo": "E4815D54DD604D8BB392219DB604A63C"
}

返回参数说明：

参数名	参数类型	备注
code	code	状态码 200 成功! 500 应用程序繁忙，请稍后再试! 521 企业V卡号或者验证码错误!
message	String	响应消息
content	CouponDetailDTO	优惠券详情

CouponDetailDTO

参数名	参数类型	备注
pkId	integer	优惠券ID
couponNo	string	优惠劵码
effectDate	string	生效时间
projectName	string	活动名称
bindedTime	string,	绑定时间
beginDate	string	开始时间
endDate	string	截止时间
amount	number	优惠金额 具体金额参考优惠券类型 例：amount = 85 couponType = AMOUNT：订单金额减85元; couponType = DISCOUNT：订单金额85折； couponType = VIP_AMOUNT：订单金额85元
statusCode	string	优惠券活动状态码（B:已绑定；T:已使用；X:作废）
isOverLay	boolean	是否重叠使用
delayEffectDay	integer	绑定后多少天后生效
isMarketingPrice	boolean	是否门市价价（TRUE:门市价上打折;FALSE:会员价上打折）
bindOrgID	string	绑定酒店/使用酒店
usedRules	string	使用规则
areaLevel	string	使用范围等级(1:全国;4:酒店)
usedHotelIDs	string	可供使用的酒店（AreaLevel=1 时为空）
orderLimitsType	string	使用范围(1:用于订单;2:用于间夜)
couponType	string	优惠劵类型（C:定额; RF:固定价;DR:折扣）
isRentRoom	boolean	是否时租
isUsable	boolean	是否可用
notUsableReason	string	不可用原因
disableWeekdays	string	禁用周（多个以“,”分割）星期六是6，星期日是7，星期一是1，例如返回7,1，说明星期日，星期一不能用

返回示例：

{
  "code": "200",
  "message": "成功!",
  "content": {
    "pkId": "3323",
    "couponNo": "E4815D54DD604D8BB392219DB604A63C",
    "effectDate": null,
    "projectName": null,
    "bindedTime": "2021-07-10 17:15:39",
    "beginDate": "2021-07-10 00:00:00",
    "endDate": "2022-05-06 23:59:59",
    "amount": 10,
    "statusCode": "T",
    "isOverLay": false,
    "delayEffectDay": 0,
    "isMarketingPrice": false,
    "bindOrgID": "",
    "usedRules": "",
    "areaLevel": "4",
    "usedHotelIDs": "3500001,3500002,3500007,3500011,3500013,3500041,3500051.......",
    "orderLimitsType": "1",
    "couponType": "DR",
    "notUsableReason": false,
    "disableWeekdays": null,
    "rentRoom": false,
    "usable": false
  },
  "echoToken": "8e5c752c-95f7-4b02-87e3-c893572b98c8"
}

查询优惠券详情

接口地址：coupon/getCouponDetailByPkId

请求方式：POST

请求参数说明

参数名	参数类型	备注	是否必填	示例值
cardId	String	公司卡号	是	VCENTCRM0002220001
cardPassWord	String	公司卡密码	是	TestPassword
pkId	String	pkid	是	96531
hotelId	String	酒店id	否	2000014

请求示例

{
  "cardId": "VCENTCRM0002224829",
  "pkId": "3657",
  "cardPassWord": "123321a",
  "hotelId": "2000014"
}

返回参数说明

参数名	参数类型	备注
code	code	状态码 200 成功! 500 应用程序繁忙，请稍后再试! 521 企业V卡号或者验证码错误!
message	String	响应消息
content	CouponDetailByPkIdDTO	优惠券详情

CouponDetailByPkIdDTO

参数名	参数类型	备注
pkId	integer	优惠券ID
bindBeginDate	String	绑定后生效时间
bindEndDate	String	绑定后结束时间
todayCanUsed	boolean	调用接口时如果传hotelId就会检测此优惠券今日在hotelId对应的酒店是否可用。使用场景：用户绑券前可以先确认是否可用。 调用接口时如果没有传hotelId，此字段返回false
orderLimitsType	String	使用范围(1、用于订单 2、用于间夜)
activityCode	String	活动名称
beginDate	String	活动开始时间
endDate	String	活动结束时间
amount	number	优惠券金额
projectType	Integer	活动类型 (0 = All（全部） , 1 = Ecoupons（优惠券，包括3456权益券） , 2 = Activity（促销券） , 3 = LateCheckout（延时退房券） , 4 = QuotaPoint（定额积分券） , 5 = RoomDay（间夜券） , 6 = CancelNoShow（NOSHOW券） , 7 = BFM（早餐券） , 8 = OTA（美团券） ) = ['0', '1', '2', '3', '4', '5', '6', '7', '8'] ,
displayName	String	前端显示名称
ticketType	String	券类别 C=定额; RF=规定价 DR=折扣
ticketTypeName	String	券类别名字
bindedLimit	Integer	绑定数量限制
usedLimit	Integer	使用数量限制
usedRules	String	使用规则
inAdvanceDay	Integer	提前预订天数
bindExpiration	String	绑定后有效期 单位，值 D0 - 0天 W1 - 1周 M3 - 3月 Y1 - 1年 N1 - 1分钟
areaLevel	String	使用范围等级 (1:全国;4:酒店)
disableWeekdays	String	禁用周，星期六是7，星期日是1，星期一是2，例如返回71，说明星期六，星期日不能用
extendFunction	String	权益配置项
extendFunctionName	String	权益配置项名字
delayEffectDay	Integer	绑定后多久可以开始使用，单位（天）
remark	String	备注
rangeType	String	范围类型：1-通用券 2-单店券 3-多店券
isSupport	boolean	是否支持指定的酒店(请求参数hotelId有值才返回，否则为空）
isOverlay	boolean	是否重叠使用
orgId	List<String>	适用的酒店范围

返回示例

{
    "code": "200",
    "message": "成功!",
    "content": {
        "pkId": "3657",
        "bindBeginDate": "2022-06-27 10:15:15",
        "bindEndDate": null,
        "todayCanUsed": "false",
        "orderLimitsType": "1",
        "activityCode": "zkq测试券2",
        "beginDate": "2022-02-28T00:00:00",
        "endDate": "2023-02-28T00:00:00",
        "amount": "11",
        "projectType": "1",
        "displayName": "",
        "ticketType": "C",
        "ticketTypeName": "定额优惠券",
        "bindedLimit": "99",
        "usedLimit": "99",
        "usedRules": "",
        "inAdvanceDay": "0",
        "bindExpiration": "",
        "areaLevel": "4",
        "disableWeekdays": "",
        "extendFunction": null,
        "extendFunctionName": null,
        "delayEffectDay": "0",
        "remark": "",
        "rangeType": "1",
        "isSupport": null,
        "isYF": "false",
        "isGenBeforehand": "false",
        "isBd": "false",
        "isOverlay": "false",
        "orgId": [
            "2000014"
        ]
    },
    "echoToken": "f3be2c0e-3245-45b2-9d7b-9126fc12e0b2"
}

查询会员优惠券列表

接口地址：coupon/getMemberCouponList

请求方式：POST

请求参数说明：

参数名	参数类型	备注	是否必填	示例值
cardId	String	公司卡号	是	VCENTCRM0002220001
cardPassWord	String	公司卡密码	是	TestPassword
bookerId	String	预订公司卡号	是	VCENTCRM0002220001
mobile	String	绑卷会员手机号	是	15036222256

请求示例：

{
 "cardId": "VCENTCRM0002224829",
 "cardPassWord": "123321a",
 "bookerId": "VCENTCRM0002224829",
 "mobile": "15036222256"
}

返回参数说明：

参数名	参数类型	备注
code	code	状态码 200 成功! 500 应用程序繁忙，请稍后再试! 521 企业V卡号或者验证码错误!
message	String	响应消息
content	List<MemberCouponDTO>	会员优惠券列表

MemberCouponDTO

参数名	参数类型	备注
couponNo	String	优惠券码
couponStatus	String	优惠券状态 NONE：无 UNUSED：未使用 USED：已使用
couponInfo	CouponInfoDTO	优惠券信息

CouponInfoDTO

参数名	参数类型	备注
pkId	String	优惠券Id
name	String	优惠券名称
type	String	优惠劵类型。见 企业查询优惠券列表
value	number	优惠券面额
startDate	Date	有效期开始时间
endDate	Date	有效期结束时间

返回示例：

{
  "code": "200",
  "message": "成功!",
  "content": [
    {
      "couponNo": "65207838613D4EB5BAF725A462DFD1A6",
      "couponStatus": "UNUSED",
      "couponInfo": {
        "pkId": "3323",
        "name": "测试优惠券",
        "type": "1",
        "value": 100,
        "startDate": "2021-07-01 00:00:00",
        "endDate": "2021-08-01 00:00:00"
      }
    }
  ]
} 

TMC给企业设定发礼包额度

TMC发给其它挂靠公司（给的是额度）

接口地址：coupon/sendCoupon

请求方式：POST

请求参数说明：

参数名	参数类型	备注	是否必填	示例值
cardId	String	公司卡号	是	VCENTCRM0002220001
cardPassWord	String	公司卡密码	是	TestPassword
bookerId	String	分配公司卡号	是	R20005050001936627
pkId	String	券Id（废弃，请使用packId）	是	3323
packId	String	活动礼包Id	是	xp123
totalCount	Int	分配额度	是	100

请求示例：

{
 "cardId": "VCENTCRM0002224829",
 "cardPassWord": "123321a",
 "bookerId": "VCENTCRM1016431348",
 "pkId": "3323",
 "totalCount": 100
}

返回参数说明：

参数名	参数类型	备注
code	code	状态码 200 成功! 500 应用程序繁忙，请稍后再试! 521 企业V卡号或者验证码错误!
message	String	响应消息
content	Bool	是否成功

返回示例：

{
 "code": "200",
 "message": "string",
 "content": true
} 

优惠券额度回收

TMC公司发放优惠券额度给托管公司后，回收已发放额度

接口地址：coupon/recycleCoupon

请求方式：POST

请求参数说明：

参数名	参数类型	备注	是否必填	示例值
cardId	String	公司卡号	是	VCENTCRM1016433543
cardPassWord	String	公司卡密码	是	A7A5C7DF-A1B2-469B-8361-A1AF85289571
bookerId	String	分配公司卡号	是
pkId	String	优惠券ID（废弃，请使用packId）	是
packId	String	活动礼包Id	是	xp123
totalCount	Int	回收数量(额度)	是

请求示例：

{
 "cardId": "VCENTCRM0002224829",
 "cardPassWord": "123321a",
 "bookerId": "VCENTCRM1016431348",
 "pkId": "3323",
 "totalCount": 100
}

返回参数说明：

参数名	参数类型	备注
code	code	状态码 200 成功! 500 应用程序繁忙，请稍后再试! 1101 优惠券额度不足 1102 优惠券不存在 1107 无法发券给自己公司
message	String	响应消息
content	Bool	是否成功

返回示例：

{
 "code": "200",
 "message": "string",
 "content": true
} 

企业给个人绑券

将分配给其他企业的劵或者自己的劵跟个人做绑定，把劵发给个人

接口地址：coupon/bindCoupon

请求方式：POST

请求参数说明：

参数名	参数类型	备注	是否必填	示例值
cardId	String	公司卡号	是	VCENTCRM0002220001
cardPassWord	String	公司卡密码	是	TestPassword
bookerId	String	企业卡号	是	VCENTCRM1016431348
pkId	String	券Id	否	3323
mobile	String	个人手机号码	是	15036222256

请求示例：

{
 "cardId": "VCENTCRM0002224829",
 "cardPassWord": "123321a",
 "bookerId": "VCENTCRM1016431348",
 "pkId": "3323",
 "mobile": "15036222256"
}

返回参数说明：

参数名	参数类型	备注
code	code	状态码 200 成功! 500 应用程序繁忙，请稍后再试! 521 企业V卡号或者验证码错误!
message	String	响应消息
content	String	优惠券券码

返回示例：

{
 "code": "200",
 "message": "string",
 "content": "65207838613D4EB5BAF725A462DFD1A6"
} 

查询会员在酒店可以用的优惠券列表

接口地址：coupon/getHotelMemberCouponList

请求方式：POST

请求参数说明：

参数名	参数类型	备注	是否必填	示例值
cardId	String	公司卡号	是	VCENTCRM0002220001
cardPassWord	String	公司卡密码	是	TestPassword
hotelId	String	酒店id	是	2000014
checkInDate	Date	入住日期	是	2022-04-09
mobile	String	个人手机号码	是	15036222256
roomType	String	房型	否	DR1

请求示例：

{
  "cardId": "VCENTCRM0002224829",
  "cardPassWord": "123321a",
  "hotelId": "2000014",
  "mobile": "13728174397",
  "roomType": "DR1",
  "checkInDate": "2022-09-01"
}

返回参数说明：

参数名	参数类型	备注
code	code	状态码 200 成功! 500 应用程序繁忙，请稍后再试! 521 企业V卡号或者验证码错误!
message	String	响应消息
content	List<HotelMemberCouponDTO>	可用优惠券列表

HotelMemberCouponDTO

参数名	参数类型	备注
pkId	String	优惠券Id
hotelId	String	酒店id
name	String	总额度
ticketNo	String	优惠券信息
needMarketingPrice	Boolean	市场价预订才可以用这个券
amount	BigDecimal	优惠券金额
effectDate	String	优惠券可预订开始时间
ticketType	TicketType	优惠劵类型 C 立减优惠 DR 折扣优惠 RF 一口价优惠

返回示例：

{
    "code": "200",
    "message": "成功!",
    "content": [
        {
            "hotelId": "2000014",
            "name": "zkq测试券1",
            "pkId": "3656",
            "ticketNo": "201D3F86C40746639A48041982A27892",
            "needMarketingPrice": false,
            "amount": 10.00,
            "effectDate": "2022-02-28T15:45:07",
            "ticketType": "C"
        },
        {
            "hotelId": "2000014",
            "name": "zkq测试券2",
            "pkId": "3657",
            "ticketNo": "6EC34CA6644A4A0EAE38165B1688CD1E",
            "needMarketingPrice": false,
            "amount": 11.00,
            "effectDate": "2022-08-02T11:28:00",
            "ticketType": "C"
        }
    ],
    "echoToken": "f4a8d35d-dfa8-4655-a471-ece98f58b183"
}