通过 API 自动采购：密钥、限额、退款

公开 API 覆盖的就是你手动在做的那些事：目录、库存、余额和订单。没有 api.boomly.ac 这样的独立子域名 — 基础路径是相对的，请求都发到同一个域名的 /api。带接口说明的文档放在站内的 API 页面，调试台也在那里。

调试台和格式转换器一样实在：请求直接从你的浏览器发出，密钥不会保存在商店的服务器上。这让你可以在动手写代码之前先把调用验证一遍。

下单之前也用同一套 API 查库存。这比先下单、再拿到一次失败的交付便宜，哪怕钱会自己退回余额也是如此：重新下一单花掉的时间，仍然是从 30 分钟窗口里扣的。

它的用处比看上去大。应答的形状用眼睛看一次，比照着文档去复原要省事：解析是按真实结构写的，不是按对结构的描述写的，调试也从一个能跑通的请求开始，而不是从猜测开始。

密钥和密文由买家自己在个人中心签发 — 不用去找客服要。密文只用来给请求签名，而签名并不总是必需的：只有启用了签名的密钥才需要它。这是一个有意留下的分叉 — 简单场景可以先不签名就开始，正式的自动采购再把它打开。

• 密钥在个人中心签发，也在那里吊销。
• 密文只在签名时用；如果这个密钥没有启用签名，它就不参与请求。
• 站内的调试台可以带着密钥发请求，而不把它保存到服务器上。

密钥和账号本身一样，也是登录凭据：它打开的是余额和订单。不该把它放进公共仓库；如果泄露了，去个人中心签发一个新的、把旧的吊销，比事后收拾后果省事。

所以接入的顺序自然是分步的：先从调试台发请求，再用自己的代码发同一个不带签名的请求，最后才在正式密钥上打开签名。每一步单独验证，出错的位置一眼可见。

目录应答里每个商品有两个编号，弄混的代价不小。商品编号是公开的商品号：它同时写在站内的商品卡片上，是你报给客服的那个，也是你据以重复采购的那个。内部标识符则是数据库里那条记录的服务性编号。

站内商品页的地址是按商品编号拼出来的。如果脚本要收集商品链接 — 为了附在工单里，或者存在自己这边 — 就该用商品编号来拼。用内部编号也能到同一个页面，但要经过一次跳转，在你的库里还会多留一个没用的环节。

• 商品编号是你连同订单号一起报给客服的那个值。
• 商品编号是稳定的：在商店机器人里订阅补货，靠的也是它。
• 内部编号在和客服沟通时毫无用处 — 它是记录的标识符，不是商品的标识符。

不用 API 也看得到商品编号：它写在商品卡片和订单里，客服要的也正是它。一张按商品编号建立的采购表，脚本读得懂，之后去写机器人的那个人也读得懂。

由此得出做监控的规则：你表格里的主键应该是商品编号。目录的构成随库存一起变动 — 商品会出现也会消失 — 而商品编号是唯一稳定的、能指向某个具体商品并把昨天的库存和今天的库存对起来的办法。

限制有两条，而且各自独立计算：每个接口每分钟 120 次请求，每个密钥每分钟 60 次请求。第二条比第一条更严，实际的上限也由它决定：不管你轮询多少个不同的接口，一个密钥合计每分钟只能过 60 次请求。

对写库存监控的人来说，实际的推论是：把目录轮询得比每秒一次还密没有意义 — 你会先撞上密钥限额，而不是先拿到更新的数据。更合理的做法是把轮询放稀，同时在商店机器人里订阅你需要的那些商品编号的补货，通知会自己找上门。

• 每分钟 120 次请求 — 针对一个地址。
• 每分钟 60 次请求 — 针对一个密钥，这就是整套方案的实际上限。
• 两个限额独立计算，所以起约束作用的永远是较小的那一个。

靠并发也绕不开：把请求分摊到几个接口上，撞到的还是同一个密钥限额。上限不是靠线程数抬起来的，而是靠轮询的设计 — 稀疏地做一次目录全量遍历，再对你真正需要的那几个商品编号做定点检查。

这是 API 和其他购买方式之间最主要的区别，值得在选采购渠道之前就知道。通过 API 用余额支付的订单，如果发货失败，款项会自动退回余额。网站和机器人上没有这种自动退款：那里的钱只是不会被扣，出故障时退款通过客服人工处理。

对一次性购买来说差别不大。对定期的自动采购来说这是原则性的：脚本无人值守地下单，就必须能在没有人工介入的情况下扛过一次失败的交付 — 而只有 API 提供这一点。

• 自动退款是在通过 API 用余额支付时触发的，不是任何一种付款都有。
• 余额是立即扣的，所以发货不必等转账确认。
• 余额充值可以用与支付订单相同的方式：七条网络的 USDT、CryptoBot，或者卢布 SBP。

渠道之间的差别归结为一个问题：故障由谁来处理。通过 API 购买时由商店自己处理并把钱退回余额，网站和机器人上则由客服人工处理。对成批的订单来说，这就是「脚本夜里照跑」和「早上人工收拾」之间的差别。

脚本里的验收看上去和手动做的不一样，但规则相同：拿到应答就立刻把交付的行数和下单数量对上，把字段构成和商品的配套标签对上。不管订单是谁下的，30 分钟都一样在走。

而且自动退款不能代替验收。它兜住的是交付根本没有发生的情形，不是商品到了却与描述不符的情形。后者仍然要在 30 分钟窗口里、通过客服解决 — 带上订单号和商品编号。