批量下单前通过 API 检查余额

为什么在启动队列前要查询余额

批量下单前不重新检查余额，会导致部分订单失败：前几笔订单创建成功，后面的订单却因资金不足而报错。在并行提交、涉及不同服务以及多个进程同时操作同一账户的情况下，处理这类问题最为棘手。

对于下单来说，重要的不是充值总额，也不是个人后台中的账面余额。真正需要的是服务在创建新订单时允许扣划的金额。用于活跃订单的资金可能已经处于预留状态，尽管最终扣款尚未反映在操作历史中。

请将队列预算与可用余额字段进行比较，而不是与账户总金额比较。

余额接口的响应是什么样的

字段名称由具体平台的文档决定，但一个设计良好的余额接口通常返回 total、available、reserved、currency 和 updated_at。下面是一个结构示例，可作为集成时的参考。这不是每个服务的通用响应，而是一个清晰数据结构的示例。

请求可能如下所示：

curl -X GET "https://api.example.com/v1/balance" \
-H "Authorization: Bearer API_TOKEN" \
-H "Accept: application/json"

响应：

{
"total": "125.80",
"available": "84.50",
"reserved": "41.30",
"currency": "USD",
"updated_at": "2025-01-15T10:42:18Z"
}

在此示例中，total 是账户的全部资金，available 是可用于新订单的资金，reserved 是已用于此前创建的操作的金额。校验结果吻合：125.80 减去 41.30 等于 84.50。currency 字段指定了结算单位，updated_at 有助于判断数据的时效性。

如何解读 available 和 reserved

available 字段用于决定是否下单。如果队列金额为 80.00，而 available 为 84.50，则只有在 API 不会额外收取手续费、也不会在创建订单时重新计算价格的情况下，资金才足够。reserved 字段不应加到可用余额中：这笔金额已经被占用。

reserved 可能包含处于 processing、pending 或 review 状态的订单费用——具体范围取决于平台规则。有时预留金额会在取消、部分完成或人工审核后释放。因此，仅根据订单列表自行计算预留金额只能作为额外的核对手段。

• total 适合与充值和扣款历史进行核对；
• available 适合用于判断新队列是否可以启动；
• reserved 显示已有多少资金被锁定用于活跃操作；
• 即使只操作一个账户，也不能忽略 currency；
• updated_at 可用于日志记录和诊断过期响应。

仅包含 balance 字段的响应处理起来更简单，但有一个缺点：无法判断这些资金是否可以立即使用，还是部分金额已被其他订单占用。

在 API 文档中确认金额格式

在示例中，金额以字符串形式传递："84.50"，而不是数字 84.5。这种格式保留了服务返回的精确值。如果 API 使用带小数点的字符串，不应立即将其转换为浮点数并通过 float 进行比较。

例如，你的计算结果可能得到 84.499999，而不是预期的 84.50。在预算边界上，这可能导致错误地放行队列，或者相反，错误地停止队列。对于字符串形式的十进制值，请使用支持固定小数位精度的十进制数据类型。

另一种常见的约定是使用整数最小单位。此时响应可能包含 "available_minor": 8450 和 "currency": "USD"，而订单价格则为 "price_minor": 1250。如果货币规则规定两位小数，那么在此类 API 中 8450 表示 84.50。只有在文档明确说明时，才能将值除以 100。

不要混用货币和价格格式

在计算队列之前，请将余额中的 currency 与价格接口或创建订单响应中的货币进行比较。如果余额返回一种货币，而服务目录使用另一种货币，则不能直接代入数字。需要使用平台自身提供的计算方式，或者使用单独确认过的换算方法。

在本地预先换算便于规划，但有一个缺点：服务在扣款时可能采用不同的汇率、手续费或舍入规则。更可靠的做法是使用 API 以余额货币返回最终价格的参数来提交订单，或者在创建订单前直接获取价格计算。

如果价格接口返回 "price": "12.345"，而余额存储的值保留两位小数，请确认舍入规则。不要自动向下舍入：实际扣款可能更高。判断队列是否放行时，应使用 API 给出的订单最终价格。

在首次请求前计算队列预算

下单前，收集所有订单，并根据数量、所选服务、地区、附加选项以及单独传递的手续费（如有）计算其费用。不要将 available 与界面中的基础价格进行比较：在 API 中，最终金额可能取决于具体订单的参数。

假设队列中有三个订单。价格计算 API 返回的金额分别为 18.40、27.15 和 31.60，货币与 balance.currency 中指定的相同。预算为 77.15。如果 balance.available 为 84.50，按计划下单后剩余 7.35。如果 available 为 76.90，则不能启动整个队列。

1. 根据每个订单的实际参数获取价格。
2. 将最终费用相加，不改变其格式和货币。
3. 将预算与最新余额响应中的 available 进行比较。
4. 余额充足时，将该金额记为本地启动预留。
5. 每创建一个订单后，从本地预留中减去已确认的费用。

余量可以降低额外扣款导致失败的风险，但有一个缺点：部分可用资金将不会被使用，尽管队列本可以全部通过。

在提交前进行第二次检查

在活动准备阶段获取的余额会很快过时。在计算和启动之间的时间里，其他操作员、自动化程序或活跃订单可能改变 available 和 reserved。在队列形成之后、第一笔订单提交之前，需要再次请求。

可行方案包括两个阶段：先获取价格并评估预算，然后再次请求 balance。如果 available 值减少并低于计算金额，则不应提交整个队列。在最终检查和启动之间，不应使用同一账户执行其他扣款操作。

整个启动只请求一次可以减轻 API 负载，但缺点是：当长队列仍在处理时，可用余额可能已经发生变化。

资金不足时如何启动队列

如果 available 小于预算，不要寄希望于部分请求能通过而提交所有请求。将队列分成若干批次，使每批费用不超过可用限额。在余额为 76.90 的示例中，可以提交前两个订单，费用为 45.55，然后停止：第三个订单费用为 31.60，需要重新检查。

分批时请明确指定订单顺序。可以先提交优先订单，也可以组成费用相近的批次。每种方案都有缺点：优先顺序会推迟较不重要的项目，而按价格排序可能打乱原始活动计划。

• 组成金额不超过当前 available 的批次。
• 创建批次中的订单并保存其标识符。
• 等待响应，或在超时后检查操作状态。
• 如果 API 限制或服务规则要求，请暂停。
• 在下一批之前再次请求 balance。

每批之后应以 API 的新响应为准，而不仅仅依赖从先前余额中进行的本地扣减。 本地计算有助于控制，但无法看到退款、外部扣款和预留金额的重新计算。

并行提交时保护预算

在顺序处理时，只需在订单确认后减少本地限额。在并行模式下，两个工作进程可能同时看到 available 为 84.50，并各自计划支出 60.00。两个决策单独来看都合理，但加在一起就超过了可用余额。

为此需要共享的本地预留计数器，或者以原子方式访问的队列。提交前，工作进程尝试在该计数器中占用订单金额。如果可用限额不足，订单将等待重新检查余额。

• 顺序队列更易于控制，但启动速度较慢。
• 并行提交可缩短启动时间，但需要锁定共享预算。
• 本地预留可减少冲突，但工作进程故障后可能卡住。
• API 侧的预留更可靠，但并非每个平台都提供。

如果进程在收到响应前结束，不能立即将本地预留视为已花费或可用。首先应通过外部标识符或操作查询方法确认订单是否已创建。

如果 API 提供预留功能，请加以利用

某些 API 允许为一组操作创建预留，或以两步方式处理订单：计算、锁定金额、确认。在这种方案中，检查和扣款之间的窗口更小，其他进程消耗账户资金的可能性更低。

如果存在此类方法，请保存预留标识符、金额、货币、有效期和状态。然后，如果 API 约定要求，在创建订单时传递该标识符。队列完成后，核对未使用部分以及锁定是否已解除。

API 预留并不能解决所有问题：它可能有效期很短，不覆盖手续费，或者在确认出错后释放。本地预留更易于实施，但缺点是它无法防止在你的应用之外产生的支出。

将余额错误与零余额区分开

错误代码响应、超时或请求频率限制并不意味着 available 等于零。如果大型启动依赖该值，不要自动代入最后一次已知值。无法获取最新余额时，应将队列暂停。

创建订单时的拒绝应单独处理。它可能与资金不足有关，但也可能与服务标识符错误、数量无效、渠道限制或同一操作重复有关。请将错误代码和文本与订单的外部标识符一起保存。

• 授权错误时，请更新访问权限，然后重试请求。
• 请求频率受限时，请按 API 规则暂停。
• 创建超时时，请先检查操作是否实际出现。
• 资金不足错误时，请停止该批次并重新请求 balance。

超时后不要创建重复订单

超时意味着你的客户端未收到响应，而不是服务器未处理请求。未经检查就重新提交可能创建第二个订单并再次占用资金。在配置了多次自动重试的队列中，这尤其危险。

如果 API 支持 client_order_id、external_id 或 idempotency_key 字段，请传递唯一的订单外部标识符。在发送请求前保存它。超时后，通过该值查找操作，或使用先前获得的标识符查询状态。

未经检查的重试速度更快，但缺点很直接：可能出现重复订单、双重预留，以及你的预算计算与实际扣款之间的差异。

启动日志中应保存哪些内容

日志有助于还原批量操作的进程，并解释特定批次为何停止。对于每次启动，请保存两次检查的时间、total、available、reserved、currency、计算出的预算、本地预留金额以及订单外部标识符列表。

对于每次创建尝试，记录费用、响应代码、操作技术标识符和最终状态。机密信息不应写入日志：授权令牌、API 密钥、完整请求头和个人数据必须在写入前进行掩码处理或排除。

完整日志便于调试，但有一个缺点：如果不加过滤，访问数据和客户信息可能会进入存储。

在小队列上验证方案

在大规模启动前，请执行一个简短场景：获取 balance、请求最终价格、创建有限批次、再次请求 balance，并将 available 和 reserved 的预期变化与实际响应进行比较。这样可以发现服务何时预留金额、何时最终扣款。

测试批次不能保证在高负载下行为相同：可能触发限制、并行进程或特定服务的约束。因此，在批量队列中，请继续将启动分成批次，在批次之间检查可用余额，并单独分析每次失败。