先在官方Bot发送 /api 申请接入，审核通过后私聊发送 /api reset 获取密钥。

请求头 Authorization: Bearer 你的密钥。API共用本Bot TG账号余额。

GET /api/supply/v1/account · categories · products · inventory?product_id=43 · orders · balance-ledger

POST /api/supply/v1/orders

{"client_order_no":"your-unique-order-1","product_id":43,"usernames":["username"],"expected_total":"6.000"}

GET /api/supply/v1/orders/客户订单号
GET /api/supply/v1/orders/客户订单号/delivery

网络超时必须保留同一客户订单号重试；相同订单号只处理一次，变更内容会拒绝。先查询旧订单，禁止反复新建订单。

accepted 已受理；processing 处理中；completed 已完成；partial 部分完成；review 待核实；refunded 已退款；failed 未扣款失败。

review须继续查询原订单，不能重复购买。明确失败部分退回Bot余额。发货接口返回filename和content，请妥善保存，不要向日志输出内容。

商品、库存和账变分页上限分别为授权范围、100条、最近100条。每单最多20个用户名；实际价格以商品查询结果为准。

订单回调由管理员配置HTTPS地址，私聊Bot发送 /api callback 领取签名密钥。以HMAC-SHA256校验原始正文与X-Supply-Signature，并按X-Supply-Event去重。回调只包含状态和金额，不含账号凭据；失败最多重试5次，仍应通过查询接口核实订单。

IP白名单、商品权限由管理员设置。API密钥只在 /api reset 时展示一次，重置立即作废旧密钥。