核心概念

金额

API 中的每个金额都是以货币最小单位表示的整数。没有浮点数，没有舍入意外。

Developer API 中的每个货币值都是以货币最小单位表示的整数 — 美元为美分。API 中任何地方都没有小数，也没有浮点金额。

450  =  $4.50      (USD, 2 minor-unit digits)

这是有意为之：用整数表示金额可避免浮点运算带来的舍入误差，因此您读取到的总额与顾客被扣除的总额完全一致。

订单中

在订单资源上，每个金额都是以美分表示的整数，totals.currency 告诉您货币：

"totals": {
  "currency": "USD",
  "subtotal": 525,
  "tax": 42,
  "surcharge": 0,
  "tip": 0,
  "delivery_fee": 0,
  "delivery_tip": 0,
  "total": 567
}

行项目遵循同样的规则：base_price（每件单价，不含加料选项）、tax 以及每个加料选项的 price 变动，都是整数美分。

菜单中

发布菜单时，价格是一个 amount 对象，将整数与其货币配对：

{ "amount": { "amountMinor": 450, "currency": "USD" } }

amountMinor 是以货币最小单位表示的整数，currency 是大写的 ISO‑4217 代码（USD）。对于美元，就是美分 — 发送整数美分即可。

供参考，不同货币的最小单位位数各不相同 — 多币种上线后，模型即可处理这种差异：

货币	最小单位位数	5 个单位的 `amountMinor`
USD	2	`500` ($5.00)
JPY	0	`5` (¥5)
KWD	3	`5000` (KD 5.000)

舍入

由于每个金额都是整数，传输过程中不存在舍入 — 您读取的数字是精确的。只有当 Maple 推导出新金额时才会发生舍入，例如百分比折扣或税费行。默认采用银行家舍入（四舍六入五成双），避免总是将 .5 进位带来的向上偏差。

您可以通过货币配置的舍入模式按币种覆盖，但默认是 half-even — 在您这一侧核对总额时请以此为准。

格式化显示

要显示金额，请除以 10 的“货币最小单位位数”次方：

function format(amountMinor: number, currency: string, digits = 2): string {
  return new Intl.NumberFormat('en-US', { style: 'currency', currency }).format(amountMinor / 10 ** digits);
}

format(567, 'USD'); // "$5.67"

如果您处理的货币指数不同，请不要硬编码除以 100 — 应根据货币来决定。