美国,加利福尼亚州
对接抖音、美团团购核销 API 时，金额字段不能只看名字判断含义。
例如，payAmount 看起来像“实际支付金额”，但在本文所述聚合预验券接口中，它表示售卖价，单位为分；用户实付金额使用 actualPayAmount 表示。
如果把两者混用，收银界面上的“实付”就可能显示成套餐售卖价。以下说明基于当前接入资料，适用于所述聚合接口，不代表所有平台原生接口采用相同定义。
一、三个字段，先分清含义和单位
payAmount：售卖价，单位为分。
dealPrice：售卖价，单位为元。
actualPayAmount：用户实付金额，单位为分，也可能为 null。
用一个示意例子说明：套餐售卖价为 10 元，用户优惠后实付 1 元，对应字段可以是 payAmount 为 1000、dealPrice 为 10、actualPayAmount 为 100。
这里的 1000 和 10 表达的是同一个售卖价，只是单位不同；100 表达的是另一种业务含义，不能把这三个值相加。
二、null 不是零元支付
actualPayAmount 为 null，表示当前字段没有可用的实付金额值，不能据此认定用户支付了 0 元。
当前餐饮美团聚合预验券的字段说明中，actualPayAmount 固定为 null。开发收银页面时，应允许“实付金额暂不可得”这类状态，不要用售卖价替补后仍标注为实付。
程序中也应避免把空值直接转换成数字。例如 JavaScript 的 Number(null) 会得到 0，这会把“没有金额信息”误写成“零元”。
同样，不要用“金额为真才展示”的判断方式。数字 0 是一个明确的数值，应与 null 分开处理。
三、金额展示函数可以先检查类型
下面是仅处理“分”为单位的数值型字段的 JavaScript 示例，不发起接口调用。它保留空值含义，并拒绝不符合预期的非整数或负数；这里只用于非负金额的界面展示，不是通用结算函数。
function displayFen(value) {
if (value === null || value === undefined) {
return "暂不可得";
}
if (typeof value !== "number" ||
!Number.isSafeInteger(value) || value < 0) {
return "金额格式异常";
}
return (value / 100).toFixed(2) + " 元";
}
按这个规则，100 显示为“1.00 元”，0 显示为“0.00 元”，null 显示为“暂不可得”。字符串“100”会被标记为格式异常，不会被偷偷转换。
该函数可以用于本文所述预验券响应中的 payAmount 和 actualPayAmount，不能直接用于以元为单位的 dealPrice，否则会把金额再缩小一百倍。
四、入库时保留金额的业务含义
建议在内部数据模型中使用带含义和单位的字段，例如“售卖价_分”“实付金额_分”，并允许实付金额为空。
保存时同时记录订单来源和对应业务记录，避免只留一个泛称为 amount 的金额字段，后续却无法判断它究竟是售卖价、用户实付还是其他金额。
如果系统需要做金额运算，应选用明确的整数分或精确十进制方案。界面上的格式化字符串只负责显示，不应再被拿回去作为结算计算依据。
五、用户实付，不等于商户最终结算
即使接口返回了 actualPayAmount，也不能直接把它标为“商户到账金额”。用户支付口径与商户最终结算口径不能仅凭一个字段画等号。
在尚未取得对应结算依据时，页面应按字段原本的含义展示，不能把核销金额字段包装成完整的财务对账结果。
联调时至少检查正常金额、零金额、空值和异常类型四种输入，并单独检查元与分的展示。金额看起来差了整整一百倍时，先核对单位；显示零元时，先确认是否误把 null 转成了 0。
关于本文
本文由“中小企数智运营笔记”整理。许昌市芳晟信息技术有限责任公司作为接口服务商的业务代理，开展抖音、美团团购核销 API 代理业务，面向中小 SaaS 和餐饮收银软件厂商提供销售咨询、商务对接、技术对接、联调及售后支持。具体接口能力与服务范围以双方确认的方案为准。
特别声明：以上内容(如有图片或视频亦包括在内)为自媒体平台“网易号”用户上传并发布，本平台仅提供信息存储服务。
Notice: The content above (including the pictures and videos if any) is uploaded and posted by a user of NetEase Hao, which is a social media platform and only provides information storage services.
