取消预约

接口说明

取消预售券的预约。orderNo 传销售订单号（游客购买预售券的订单，「查询订单」返回 businessType=PRESALES 的订单）：

• 只传 orderNo：取消这张预售券订单下全部当前有效的预约。
• 同时传 orderNo 和 reservationOrderNo：只取消这一笔预约子订单，且它必须属于 orderNo 对应的销售订单。

本接口只取消预约，不退预售券本身，取消后预售券可以重新预约。要退预售券，请对预售券订单调用「申请退单」。

接口编码：operator.order.reservation.cancel

请求的加密、签名和响应解密规则见「接入说明与返回码」。

请求业务字段

以下为加密前的业务参数，序列化为 JSON 字符串并加密后填入外层 body。

字段	类型	必填	说明
orderNo	string	是	销售订单号，即预售券订单的平台订单号
reservationOrderNo	string	否	预约子订单号，即「查询订单」返回 saleType=PRESALE 的订单号。不传表示取消该销售订单下的全部预约
cancelReason	string	否	取消原因
callerPhone	string	否	来电号码。传了就校验它是否为预售券订单的预留手机号（联系人手机号或任意一位出行人手机号）；指定了预约子订单时，与预售券订单或这笔预约子订单的预留手机号一致即可，不一致时拒绝办理；不传或传空不校验。比较时忽略空格、短横线和开头的 +86 / 0086 / 86；平台不会在响应或错误提示里返回订单的预留手机号
outCancelNo	string	否	商家取消单号，最长 128 个字符。同一个应用实例在本接口下用相同的单号重复请求，只会办理一次，见下方「幂等」

请求业务示例

{
  "orderNo": "261111154829061002",
  "cancelReason": "游客行程变更",
  "callerPhone": "13800000000",
  "outCancelNo": "IVR-20261111-000123-cancel"
}

响应业务字段

响应体解密后为统一结构 {code, msg, data, ok}。data 为取消结果：

字段	类型	说明
orderNo	string	销售订单号（请求传入的 orderNo）
reservationOrderNo	string	本次取消的预约子订单号；取消全部预约时为 null
cancelStatus	string	整体取消状态：SUCCESS 本次处理的预约全部取消成功；PROCESSING 存在取消中的预约，稍后用「查询订单」确认；FAILED 没有任何预约取消成功；PARTIAL 部分成功、部分失败（只在取消全部预约时出现）
detailList	array	本次处理的每一次预约的结果，字段见下表

detailList 数组元素（一次预约一条。一次预约可能同时预约了多个产品，对应多个预约子订单）：

字段	类型	说明
reservationNo	string	预约单号，一次预约一个
reservationOrderNoList	array	这次预约下本次处理的预约子订单号
cancelStatus	string	这次预约的取消状态：SUCCESS 取消成功；PROCESSING 取消中；FAILED 取消失败；PARTIAL 这次预约下的预约子订单部分取消成功
failReason	string	失败原因，cancelStatus 为 FAILED 或 PARTIAL 时有值

响应示例（解密后）

{
  "code": 0,
  "msg": null,
  "data": {
    "orderNo": "261111154829061002",
    "reservationOrderNo": null,
    "cancelStatus": "PARTIAL",
    "detailList": [
      {
        "reservationNo": "20261111155012345",
        "reservationOrderNoList": [
          "2611111548290610020101"
        ],
        "cancelStatus": "SUCCESS",
        "failReason": null
      },
      {
        "reservationNo": "20261111160235678",
        "reservationOrderNoList": [
          "2611111548290610020201"
        ],
        "cancelStatus": "FAILED",
        "failReason": "子订单存在预约待确认，不允许预约退单"
      }
    ]
  },
  "ok": true
}

说明

• 取消全部预约时，只处理当前有效的预约：预约中、预约待确认、预约成功。已取消、已退、已使用、已过期的预约不处理，也不出现在 detailList 里。
• 取消全部预约时逐个预约处理，互不影响：某个预约取消失败不会回滚其他预约，接口仍返回 code=0，请以 cancelStatus 和 detailList 判断结果。失败的预约可以稍后重试，或指定 reservationOrderNo 单独取消。
• 处于「预约待确认」（供应商尚未确认）的预约暂时不能取消，该条 cancelStatus=FAILED，failReason 为「子订单存在预约待确认，不允许预约退单」。
• 已使用（已核销）的预约不能取消。
• 指定 reservationOrderNo 取消一笔预约时，校验不通过直接返回错误码和原因，不返回 detailList。
• 已预约成功的预约取消成功后，对应预约子订单的 orderStatus 变为 REFUNDED，可用「查询订单」确认。
• 预约时如有加价 / 差价，退款由平台在取消后按规则处理，本接口不返回退款结果。
• 取消全部预约耗时与预约数量成正比，读超时建议设为 30 秒以上。超时不代表失败：带了 outCancelNo 时用同一个单号重试即可；没带时请先用「查询订单」（subOrderFlag=1）确认各预约子订单的状态，再决定是否重试。
• 来电号码校验在任何取消动作之前进行，校验不通过不会取消任何预约。

幂等（outCancelNo）

outCancelNo 选填，最长 128 个字符。传了以后，同一个应用实例在本接口下使用相同 outCancelNo 的请求只会办理一次，记录保留 24 小时：

首次请求的结果	用同一个 outCancelNo 再次请求
成功（code=0）	不再办理，直接返回首次请求的响应
还在处理中	返回 code=405「请求正在处理中，请勿重复提交」，稍后再试
业务校验不通过（code 非 0，如订单不存在、来电号码不一致、没有可退数量）	首次请求没有办理，不会被记录，可以修正后用同一个 outCancelNo 重试
结果未知（平台内部调用超时或系统异常，调用方收到的是 code=400 / 500 这类错误，或者请求直接超时）	返回 code=405「该 outCancelNo 对应的请求结果未知…」，不会再办理。请先用「查询订单」（subOrderFlag=1）确认结果，确实需要重新办理时换一个新的 outCancelNo

• 建议每一次取消预约意图生成一个单号（如通话流水号 + 动作），超时或网络错误后用同一个单号重试。
• 单号只能用于同一笔请求：相同的 outCancelNo 配上不同的订单号或来电号码，返回 code=1020「outCancelNo 已被其他请求使用，请更换 outCancelNo」。
• 超过 128 个字符返回 code=1020「outCancelNo 长度不能超过 128」。
• 24 小时后记录失效，同一个单号会被当作新请求。
• 本接口 code=0 即视为已办理并被记录，包括 cancelStatus 为 FAILED、PARTIAL 的结果：用同一个单号重试只会拿回这份结果，不会再取消一次。要对失败的预约重新发起取消，请换一个新的单号。

业务错误

业务校验不通过时 code 非 0，msg 为具体原因。返回码含义见「接入说明与返回码」第 9.2 节，下游业态服务给出的返回码原样透出：

code	msg	说明
2010	订单不存在	orderNo 不存在
1021	订单号不能为空	未传 orderNo
1020	orderNo 请传预售券订单号；只取消一笔预约时，把预约子订单号传在 reservationOrderNo	orderNo 传成了预约子订单号
2310	该订单没有预约，不能取消预约	orderNo 不是预售券订单
2310	该订单没有可取消的预约	预售券订单下没有当前有效的预约（未预约，或预约都已取消 / 已使用）
2010	预约订单不存在	reservationOrderNo 不存在
1020	预约订单号不是预约生成的子订单，不能取消预约	reservationOrderNo 对应的订单不是预约子订单
1020	预约订单与销售订单不匹配	reservationOrderNo 不属于 orderNo 对应的销售订单
2010	未找到该订单对应的预约记录	预约子订单没有对应的预约记录
2310	该订单对应的预约已取消或已重新预约，不能取消预约	取消后又重新预约，产生了新的预约子订单，请改用最新的预约子订单号
405	预约记录状态有误	指定的预约已取消，或不处于可取消的状态
405	子品已使用，不允许退单	指定的预约已使用（已核销）
1020	来电号码格式有误	callerPhone 超过 32 个字符
2313	来电号码与订单预留手机号不一致，不能办理	传了 callerPhone，但它不是订单的预留手机号。未取消任何预约
405	请求正在处理中，请勿重复提交	相同 outCancelNo 的首次请求还没有处理完
405	该 outCancelNo 对应的请求结果未知，请先查询确认办理结果，如需重新办理请更换 outCancelNo	相同 outCancelNo 的首次请求中途出现超时或系统异常，平台无法确定是否已办理
1020	outCancelNo 已被其他请求使用，请更换 outCancelNo	相同的 outCancelNo 之前用于另一笔请求（订单号或来电号码不同）
1020	outCancelNo 长度不能超过 128	outCancelNo 超过 128 个字符
405	幂等校验暂不可用，请稍后重试	平台的幂等存储暂时不可用，本次请求没有办理，可稍后用同一个单号重试
1031	该接口仅支持运营平台操作员调用	应用实例绑定的不是运营平台操作员
1020	业务参数格式有误，必须为JSON对象	业务参数不是 JSON 对象，或字段类型不对

{
  "code": 2010,
  "msg": "订单不存在",
  "data": null,
  "ok": false
}