API回调-磐河旅行开放平台

在线接口文档中心

API说明: API调用说明订单状态推送通知说明

开放产品: 国内机票; 酒店; 火车票; 门票; 电影票; 保险接口; 汽车票

适用产品：国内机票、国际机票、火车票、酒店、门票、汽车票、保险

接口说明：当订单数据发生变化时，包括但不限于订单状态、订单金额等，开放平台将根据订单号回调相应的分销商，通知分销商该订单发生了变化。分销商收到通知后，需要自行调用【订单详情接口】，获取最新订单数据。如果回调请求失败(即HttpStatus!=200)，系统将会进行再次发送，最多将发送10次，且发送的时间间隔为梯次增加，目前通知频率为 15s/15s/30s/3m/10m/20m/30m/1h/3h/6h - 总计 11h4m；分销商需做好重复推送通知处理

接口地址：由分销商提供(分销商提交订单|退票|改签时候传入的通知地址)

返回格式：返回字符串：SUCCESS 即可（PS:其实不管返回内容是什么，只要请求成功(即HttpStatus==200)，系统都视为推送成功，将不再重复推送。）

请求方法： POST ( Content-type:application/x-www-form-urlencoded )

请求示例： orderNo=FO2020042123265292071192&status=4&refundNo=&chaNo=
(PS:参数放在请求体里的，不是放在URL后面的,如下图用Postman请求所示)

请求参数：

参数名称	类型	必填	说明
orderNo	string	是	订单号
refundNo	string	否	退票单号(机票、火车票的退票相关通知才有值，有值时表示退票单的通知。火车票的退票通知时该值是退票的票号，其他为退票单号)
chaNo	string	否	改签单号(机票、火车票的改签相关通知才有值，有值时表示改签单的通知)
status	int	是	订单状态(特殊情况：如果是机票的退票单/改签单回调此值则为机票退票单/改签单的状态(非原订单状态)、如果是火车票的改签单回调通知，此值就是火车票改签单的状态，火车票没有退票单，如果是火车票的退票结果回调此值就是乘客客票状态ticketStatus【退票成功=21,退票失败=22,已退票未退款 = 23】)
failMsg	string	否	预订\|出票\|退票\|改签等操作结果失败时给出的失败原因（例如：火车票占位失败时给出的原因：乘客手机号未核验；机票出票失败时给出的原因：该舱位已售罄，请选择其他舱位重新预订）
timestamp	string	是	系统参数：时间戳。格式：yyyy-MM-dd HH:mm:ss
sign	string	是	系统参数：签名，用来防止请求被伪造或篡改。,签名校验值：MD5_UTF8(orderNo+status+timestamp+secretKey)，secretKey为对应产品(机票、火车票、酒店等)请求密钥，开通账户时即可获得。加密结果转为32位小写(签名方法同各产品支付接口sign签名算法)

磐河各产品订单有回调订单状态说明及推送数据示例：

订单类型	有回调的订单状态值（其他订单状态值要么不回调要么无需关注）	回调推送数据示例(业务参数部分)	其他说明
机票主订单	已出票=4,不能出票待退款=5 ,不能出票已退款 = 7,已取消=99(仅限超时未支付系统自动取消的情况)	orderNo=FO2204268464655967&status=7&failMsg=旅客1为失信被执行人	当出票失败时，failMsg为失败原因
机票退票单	审核不通过交易结束 = 13,已退款交易结束 = 16	orderNo=FO220524195&refundNo=FO220524195T7424&status=16&failMsg=	因为是退票单的回调，这里status是机票退票单的状态(详见机票‘获取退票详情接口’refundOrderStatus字段值)，不是主订单的状态哦，当退票失败时，failMsg为失败原因
机票改签单	审核不通过交易结束 = 22, 需补款待支付 = 23,无法改签已退款交易结束 = 26,改签成功交易结束 = 27,改签已取消交易结束 = 28, 改签处理中 = 29	orderNo=FO220524195&chaNo=FO220524195C7424&status=16&failMsg=只能改同一航司,至少提前2小时的航班	因为是改签单的回调，这里status是机票改签单的状态(详见机票‘获取改签详情接口’refundOrderStatus字段值)，不是主订单的状态哦，当改签失败时，failMsg为失败原因
火车票主订单	占位成功=2,占位失败=3,已取消=5 (仅限超时未支付系统自动取消的情况),出票成功=8,出票失败=9	orderNo=TO22052519261262&status=3&failMsg=没有余票	当出票失败时，failMsg为失败原因
火车票改签单	改签占位成功=31,改签占位失败=32,改签确认出票成功=34,改签确认出票失败=35,改签已取消=37(仅限超时未支付系统自动取消的情况)	orderNo=TO22058456483434&chaNo=TO22058456483434C9110&status=34&failMsg=	因为是改签单的回调，这里status是火车票改签单的状态(详见火车票‘获取订单详情接口’中trainChaOrder改签单数组中chaOrderStatus字段值)，不是主订单的状态哦
火车票退票结果	退票成功=21,退票失败=22,已退票未退款 = 23	orderNo=TO22058456483434&refundNo=E569329908103005B&status=22&failMsg=已进站/已出站	因为火车票申请退票时不会生成退票单(也就不存在退票单号)，refundNo字段的值就是退票旅客的票号(如果是改签后新票的退票，则是改签后新票的票号)，status为乘客客票状态(‘获取订单详情接口’响应参数中ticketStatus字段)的值，不是主订单的状态哦。当退票失败时，failMsg为失败原因
酒店订单	已确认=3，确认失败=4，已完成=5，取消失败=7，已取消=8(订单未支付时用户主动取消的没有回调，因为同步返回取消结果的；订单超时未支付系统自动取消的和预订成功后申请取消成功的都有回调)	orderNo=HO220525459875563&status=4&failMsg=该房型已售罄	当确认或退订失败时，failMsg为失败原因
门票订单	已出票 = 3 ,出票失败 = 4 ,退订失败 = 6 ,已退订 = 7 , 已取消 = 99(仅限超时未支付系统自动取消的情况)	orderNo=SO2205251484646&status=4&failMsg=证件有误	当出票或退订失败时，failMsg为失败原因
保险订单	已出保=3 ,出保失败=4 ,部分出保=5	orderNo=PO22052320256459&status=3	orderNo为保险订单号，status为保险订单状态
电影票订单	已出票=4,出票失败=5,已取消=6,已退票=8,退票失败=9	orderNo=M23072122435365554&status=5&failMsg=您选择的座位已经被抢先购买	status为电影票订单状态值，当出票或退票失败时，failMsg为失败原因

返回示例 :

                                        SUCCESS

遇到收不到订单回调问题时，排查方法步骤:

                                        1、检查下单请求参数日志中是否传了回调地址(callBackUrl),回调地址漏传了，肯定不会有回调;

                                        2、检查下传的回调地址callBackUrl，外网是否能正确访问，如果提供的是内网地址（如：localhost:或127.0.0.1等）或错误地址（地址不存在），肯定接收不到回调；
                                        
                                        3、不是所有订单状态值都会推送回调的，（一般一些无关紧要的状态和商户无需关注的中间态是没有回调的）具体哪些订单状态会发送回调，上面【有回调的订单状态值】已经全部枚举出来了，如果你正在看的订单当前订单状态不在【有回调的订单状态值】中，肯定也不会有回调的；

                                        4、如果以上3步都没有回调，此时大概率是你的回调接收方法报异常了。快速的测试方法就是按照上面请求示例截图方法用postman模拟推送下自己的回调地址，看能否接受到；

                                       （ps: 根据以往商户对接经验，99%商户收不到回调的问题都是以上4步骤的其中一步出了问题；如果以上4步排查完后问题仍然没有解决，请再联系平台技术协助解决；）