机票预订API对接:文档没告诉你的那些事

看板上的任务只写了一句:"接入机票"。你做过支付对接、运费计算,也许还有地图,脑子里的模型很自然:搜索、展示结果、扣卡、完成。然后第一笔真实预订返回的价格和结果页上的不一样,第二笔超时了,没人说得清客户到底有没有座位,运营那边还有人来问:为什么有订座记录却没有票。机票预订API对接从外面看像一个电商结账流程,底下却是一笔针对远早于REST时代设计的系统的分布式事务,大多数意外都出在这道缝隙里。
本文写给从没见过PNR的开发者。它不讲某一家供应商的接口;方法名在各家之间会变,结构不会变。
机票预订API对接的调用顺序
几乎所有机票API,不管方法叫什么,都走同样的四步。把这四步之间的边界划清楚,就是大部分工作。
| 步骤 | 返回什么 | 你必须保存什么 | 会出什么问题 |
|---|---|---|---|
| 搜索 | 带价格的行程,以及一个不透明的报价或运价键 | 不需要长期保存——结果很快就过时 | 把价格当成最终价;键在付款前就过期了 |
| 验价 | 确认后的价格、运价规则、行李额,有时还有必填的旅客字段 | 验证过的报价及其有效期 | 价格变了;舱位卖完了;规则和你展示的不一致 |
| 订座 | 一条订座记录——即PNR——带记录编号和出票时限 | 你自己的订单号、记录编号、出票时限、原样发送的旅客数据 | 超时无响应;重复PNR;姓名被拒 |
| 出票 | 已出的电子客票号;钱真正被锁定是在这一步 | 每一个票号,对应到所属的旅客和航段 | 部分出票;超过时限被航司取消订座 |
大家会争的是第三行,因为很多API允许一次调用同时订座和出票。想用就用。但在航司的世界里这仍是两件事:PNR可以没有票而存在,出票也可能在PNR建好之后失败。合并接口只是把"一个成功、另一个失败"的那一刻藏起来了,你的数据模型里依然要给这个状态留位置。
还要注意搜索不返回什么:承诺。搜索是广告,验价是报价,只有出票才是成交。
为什么搜到的价格不是订到的价格
网页开发者期待的是商品目录,航司库存不是。一个航班按订座舱位出售,每个舱位是一定运价下的一组座位,航司会随着上座率不断开关这些舱位。搜索结果是从本身就可能略有滞后的可售数据里快速拼出来的;等用户填完两本护照,那个航班上最便宜的舱位可能已经关闭。验价时会重新询问,诚实的答案有时更高。
税费也会漂移。验价时会按具体旅客和航线重新计算,儿童或婴儿的价格和搜索时假设的成人不同。如果你的前台显示的币种与供应商报价币种不同——比如网站显示人民币、供应商报美元——汇率换算又是一个数字会变的地方。
设计上的结论很简单,却常被跳过:永远不要按搜索价扣款。付款前先跑验价,做对比;金额变了,就展示新价格并让用户确认。你加的利润也要基于重新验价后的运价重算,而不是从结果页沿用——这和旅行社制定在线加价策略时的逻辑一样,底价一动,它也会以同样的方式出错。
幂等性,以及订座时超时意味着什么
这一节值得读两遍。
订座调用超时时,你并不知道发生了什么。请求可能根本没到;可能到了但失败了;也可能——最伤人的情况——到了,供应商已经在航司那边建好了PNR,响应却在回来的路上丢了。对你的代码来说,这三种情况一模一样;对航司来说,第三种是一条以你客户名义占着座位的有效订座。
从其他对接带来的本能是重试。在这里,盲目重试可能为同一批旅客在同一航班上再生成一条PNR。航司把重复订座视为违规;视承运人和旅行社协议而定,后果从自动取消其中一条或两条订座,到向出票方开出借记单——ADM——都有可能。收到它的旅行社会想知道你的系统为什么订了两次。
行之有效的做法,大致按这个顺序:
- 对外调用之前先生成你自己的订单号,落库,并在API接受客户端参考号的地方随请求一起发送。API支持幂等键就用;不支持,你的订单号依然是事后找回这笔订座的依据。
- 把"未知"状态显式建模。待处理、已确认、失败——以及未知。超时应把订单置为"未知",而不是"失败"。
- 用查询而不是重复来消解未知。在决定是否重试之前,先按你的订单号查询,或列出这些旅客最近的订座。
- 跑一个对账任务,扫描所有仍为未知的订单,与供应商返回的状态比对,自己判断不了的转入人工队列,而不是去猜。
出票超时是同一个问题,只是多了钱。出票前就扣款而出票卡住,你就有一个付了钱却可能没有票的客户;先出票后扣款而扣款失败,你就出了一张总得有人向航司付钱的票。常见做法是先预授权,再出票,成功后再请款——关键是有意识地做出这个决定,而不是在生产环境里才发现。
让网页开发者意外的旅行业概念
这些都不难。但每一个都曾让不知道它存在的人白白耗掉一周。
PNR不是机票
PNR是订座记录:旅客、航段、联系方式、一个时限。机票是已付款、赋予旅客乘机权利的凭证。未出票的PNR到出票时限就会失效,座位回到可售状态,而你这边有时毫无察觉。
姓名几乎不可更改
出票后,大多数运价只允许小幅更正,不允许改名,而什么算"小幅"各航司规定不同。姓名必须与旅行证件一致。姓和名分开采集,不要让手填的称谓混进姓名字段,并且在订座调用之前校验,而不是之后。
旅客类型决定价格,不是装饰
成人、儿童、婴儿是运价类型,决定适用哪种的通常是乘机当天的年龄,而不是预订当天。怀抱婴儿一般不占座,且只能随成人出行。类型填错,验价要么失败,要么报出错误的运价。
时间是当地时间,航段不等于航节
起飞和到达时间都按各机场当地时间给出。展示时不要换算成用户所在时区,计算时长也不能不考虑时差直接相减。一段行程包含若干航段;有技术经停的航段包含不止一个航节。界面和数据必须对"经停"指的是哪一个达成一致。
售出之后还会发生变化
航司会在出票后调整航班计划。出票时正确的订单,几周后可能变成新的时间、新的航班号或断开的衔接;视供应商而定,你会通过通知、队列或重新查询订单得知。要预期订单会在你不再关注它之后发生变化。
作废不等于退票
出票后不久通常有一个窗口期,可以把票作废(void),就像从未出过一样。过了窗口,只能按运价规则退票,可能要扣手续费,甚至一分不退。窗口期和规则属于供应商和出票协议;在做"取消"按钮之前先读清楚。
出错的代价
机票对接的故障贵在一个特定的地方:它们落在人身上,而不是日志里。重复订座会变成打给航司的电话,可能还有记到旅行社账上的借记单。扣了款却没出票的客户会变成退款、投诉和拒付风险。没有成功收款就出了的票会变成欠航司的钱,总得有人去结。没人处理的航班变更会变成一个站在机场、而航班已经提前起飞的旅客。
这些在"顺利路径"测试里都看不到。先写失败路径:订座超时、价格上涨、PNR之后出票失败、付款成功后作废。这些处理好了,顺利路径才是简单的部分。
针对机票API做测试
供应商的测试环境有用,但不完整。它们通常比生产环境安静,舱位售罄和价格变动更少见,有些根本不模拟超时。用它来确认调用格式和校验错误,然后在生产环境中安排一次受控演练:用真实订单,在窗口期内作废——并让运营团队知情。
要不要对接是另一个问题。如果你真正需要的是一个前台网站,而不是把原始库存接进自己的系统,取舍写在白标还是自建预订引擎里,同样的思路也适用于面向分销代理的B2B平台。如果你确实要把库存接进自己的代码,本平台提供机票和酒店API,接入从一次关于你使用场景的沟通开始,而不是自助申请密钥——那也正是把上面每个问题都问清楚的时候。