联调阶段看到返回数据「不对劲」,第一反应往往是接口有问题。下面四类是官方文档里点名过的正常设计,不是故障。

一、couponEndTime 返回 1970-01-01

在一键买单核销场景下,couponEndTime 字段平台侧没有赋值,默认返回 1970-01-01。这是 Unix 时间戳的零点,属于「空值」的常见表现。

处理建议:把这个值当作「无有效期信息」处理,不要展示给用户,也不要用它做任何有效性判断。「券已过期」的判断应该来自核销接口返回的明确状态,而不是自己比较时间。

二、couponCodes 字段没有返回

同样是一键买单场景:验券接口在该场景下不返回 couponCodes 字段。

如果你的代码里直接取这个字段做后续逻辑,会拿到 undefined 然后抛错。正确做法是先判断字段是否存在,缺失时改用核销凭证或订单号做后续串联。

三、验券返回成功,但商家后台没有核销记录

这个现象最让人慌,但其实排查路径很明确:

  1. 先确认券码字符串是否正确 —— 如果是 77 前缀的 14 位券码,试着去掉 77 前缀再查一次
  2. 改用购券订单号查询,这比券码更可靠
  3. 确认查的是同一个门店 —— 多门店场景下常见是查到别的门店去了

背后还有一个机制:券码撤销后会换成新券码。如果你手上是撤销前的旧码,自然查不到。

四、查询结算明细报「券码不存在」

官方给的解释有两种情况:

  • 券码尚未核销 —— 结算明细只对已核销的券有意义
  • 券刚核销完立刻查询 —— 数据同步有延迟,建议等约 1 分钟后重试

所以对账任务不要设计成「核销成功后立即查结算」。加一个短延迟或放到定时任务里跑,能避免大量假的失败告警。

五、其他限制类问题

问题说明
一次能核几张单次最高验券张数不超过 99 张,且同一订单下券的类型必须一致
能否批量撤销不能,只能每次撤销一张
能查未核销的券吗不能。「已验券码查询」只查已验证的券
券码能反推平台吗不能,官方明确没有该规则

这几条在需求评审阶段就该确认。比如「批量撤销」如果写进了产品方案,到开发阶段才发现平台不支持,返工成本很高。

六、排查该类问题的通用顺序

  1. 先看是不是场景性差异(一键买单 / 自助核销 / 收银台,返回字段不同)
  2. 再看参数是否与准备阶段完全一致
  3. 再确认券状态(已核销 / 过期 / 已退款 / 条件不满足)
  4. 最后才怀疑接口或网络

绝大多数「接口异常」实际是前三类。把排查顺序固定下来,比每次凭直觉试要快得多。