预订引擎 API 错误处理:三种让你亏钱的故障

周四晚上,工单进来了。客户付了款,页面转了一圈,然后弹出一个笼统的错误。信用卡已经被扣款。你的日志里有一条发给供应商的 POST,却始终没有收到响应。航空公司到底有没有保留座位?没人说得清,而客户还在等。好的预订引擎 API 错误处理,大部分时候做的就是让你根本不会走到这一步,或者至少在走到这一步时,清楚地知道该做什么。
多数对接指南把错误当成一份状态码清单。可在预订场景里,状态码只是容易的那部分。真正让人亏钱的,是少数几种情形:请求看上去失败了,现实却已经变了;或者请求看上去成功了,现实里什么也没发生。其中有三种最重要。
故障一:搜索到下单之间,价格变了
搜索结果是报价,不是合同。运价会被缓存,库存在供应商的所有销售渠道之间共享,几分钟前展示的数字可能已经过期。供应商会在创建订单这一步告诉你:有时是一个明确的“运价已变更”响应,有时是在一个表面成功的响应里悄悄返回另一个总价。
第二种才是危险的。如果你的代码读到确认、保存订单,再按客户看到的金额扣款,差额就要从你的利润里出,或者之后以 ADM 的形式出。所以规则很简单:在扣款之前,每一次都用代码对比供应商确认的总价和客户接受的总价。
出现差异时怎么办,取决于差额大小和由谁承担。币种之间几分钱的舍入,是一次性设好的容差。再大的差额,就带着新价格和明确的“接受”按钮回到客户面前。绝不自动吸收,也绝不自动多扣。
故障二:已订座,但没有出票
有 PNR 不等于有机票。很多流程先创建订座,再在单独一步里出电子客票,两者之间有时限。付款成功而出票失败,你手里就握着客户的钱,以及一个按自己的时钟到期的订座。
这类故障很少有动静。出票调用返回错误或超时,订单停在你的数据库标成“已付款”、供应商却仍显示“已保留”的状态。与此同时出票时限在走,而航空公司不会像你的客服队列那样等你。
把它当作一个独立状态,而不是成功或失败的变体。订单至少需要这些状态:已创建、已保留、已扣款、出票中、已出票、失败且可退款。“已扣款、出票中”这个状态需要计时器:订单停留太久,就该由任务重新向供应商读取订座并做决定,而不是等人发现。知道供应商的时限时,这个决定很便宜,因为它告诉你在必须退款之前,可以安全地重试多久。
故障三:超时,结果未知
这就是周四晚上的那张工单。请求发出去了,没有响应回来,连接断了,或者网关放弃了。供应商可能完整处理了,可能只处理了一部分,也可能完全没处理。
人的本能是重试。不要盲目重试创建订单的调用,因为第二次尝试可能生成第二个订座,而重复订单是实打实的成本:占了两个座位,也许出了两张票,其中一张还要打退款官司。
安全的顺序是:先停,再查,后决定。用“我们正在确认您的预订”这样诚实的状态暂停面向客户的流程。用你在调用前生成的引用号去供应商那边查订单(所以要先生成自己的客户端引用号,并在供应商支持时随请求一起发送)。然后才决定:查到了,就从真实状态继续;超过供应商自己的处理窗口仍然没有,重试一次才是安全的。
如果供应商不支持按你的引用号查询,就在较窄的时间窗口内按旅客姓名、航线和日期搜索,把匹配当作已找到。不好看,但比重复订单便宜得多。
一张你可以反驳的决策表
| 你看到的 | 你知道的 | 该做的 | 不该做的 |
|---|---|---|---|
| 供应商返回“运价已变更” | 什么都没订成 | 展示新总价,征得同意,重新创建 | 用旧价格重发,指望能通过 |
| 成功,但总价与客户接受的不同 | 已按新价格生成订单 | 先冻结付款,询问客户,对方拒绝就作废订单 | 按旧金额扣款,自己吞下差额 |
| 已扣款,出票调用报错 | PNR 存在,机票状态未知 | 重读订座,在时限内重试出票,超时后退款 | 把订单标成失败,忘掉 PNR |
| 创建时超时 | 结果未知 | 按你的引用号查询,再继续或只重试一次 | 立刻盲目重试 |
| 取消时超时 | 你可能仍要为该航段负责 | 先重读状态,再对客户说话 | 因为点击发生过就显示“已取消” |
有一行你可能不同意:一些团队在第一次出票报错时就退款,以安抚客户。小额机票上说得过去,大额机票上是坏习惯,因为你可能丢掉一分钟后本可以保住的运价。
做错了,你要付出什么
每种故障的账单不同。漏掉价格变动,是每一笔受影响订单上损失的利润,往往要到对账时才发现。已订座未出票,是客户带着过期的订座和卡上的扣款到机场,既是拒付,也是口碑问题。超时后的盲目重试是重复订座,而航空公司会审查重复订座;形成规律,最终会落到一张 ADM 上。
这些都不稀奇。它们是不起眼的管道活,却决定了一个演示和一个能无人值守跑完周末的系统之间的差别。
在需要之前,先建好对账任务
三种故障的结局相同:你的数据库和供应商的记录对不上。所以请在第一次事故之前,而不是之后,写好比对两边的任务。每晚跑一次是底线;对处于中间状态的订单,每隔几分钟跑一次更好。它列出卡在“已保留”“出票中”或“未知”的订单,询问供应商的看法,然后修复记录,或开一张附带证据的工单。
保留预订调用的每一次请求和响应,包括超时,连同你发送的引用号。客户对扣款提出异议时,这份日志就是你的论据。它也让延迟的讨论保持诚实:请读API 延迟中你能修复和不能修复的部分,了解为什么超时是常态,而不是一个能被消灭的 bug。
如果你还在决定如何搭建与供应商的连接本身,机票预订 API 对接一文讲了本文所假设的调用顺序。想聊聊这些状态如何对应到我们的机票和酒店 API,接入从一次沟通开始:查看旅游 API 页面。