AI Agent / 开发者接入

程序化购买兑换码：注册后在用户中心一键获取 API Key（免审核；消费与充值累计等级分，自动升级 Lv1–Lv5 享等级专属定价）。余额下单自动处理；礼品卡可能先返回 paid，取码完成后交付。

方式一：MCP 一键接入（推荐给 AI Agent）

把下面的配置粘贴进任何支持 MCP 的客户端（Claude、Cursor 等）：

{
  "mcpServers": {
    "aibulk": {
      "url": "https://aibulk.uk/api/mcp",
      "headers": { "Authorization": "Bearer awk_your_key" }
    }
  }
}

Claude Code 用户可以直接执行：

claude mcp add --transport http aibulk https://aibulk.uk/api/mcp --header "Authorization: Bearer awk_your_key"

工具：list_products / check_availability / get_balance / create_topup / purchase_codes / get_order / list_orders / list_transactions。订单与充值都要求可复用的幂等 ID。代客兑换目前只有 REST 接口。

方式二：REST API

REST Base URL：https://aibulk.uk/api——所有接口路径都相对于它，例如 GET https://aibulk.uk/api/wholesale/v1/products。

完整接口文档 · llms.txt（给 agent 读的接入指南） · openapi.json · 变更日志（按日期记录接口变更）

余额模式下单示例（同步返回 code 列表）：

curl -X POST https://aibulk.uk/api/wholesale/v1/orders \
  -H "Authorization: Bearer awk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"externalOrderId":"your-unique-id","productId":"<product-id>","qty":1,"payment":"balance"}'

代客兑换（服务端兑换 API）

如果你自己收集终端用户资料并替他们完成兑换，不要用兑换站的公开接口（按出口 IP 限流），改用下面这组同 Key 鉴权的接口：

GET /wholesale/v1/products/:id → redeemFields 告诉你采购前要收集什么资料（如 prod_claude_pro 的 account_id = Claude Organization ID）；redeemInfo 的键名就是 redeemFields[].key。
POST /wholesale/v1/redemptions {code, redeemInfo} → {redemptionId, status: pending}。只接受你自己订单出的码（否则 404 invalid_code）；每个 Key 限 60 次提交/分钟。
GET /wholesale/v1/redemptions/:redemptionId（或 ?code=）→ status not_redeemed | pending | processing | fulfilled | failed，附 retryable / failureCode。failed 时用修正后的 redeemInfo 再 POST 同一个码。建议 30–60 秒轮询一次。
订阅 redemption.fulfilled / redemption.failed Webhook 可免轮询；重提后会产生新的 eventId。端到端联调用 prod_api_order_test：它的码经本接口提交会立即完成并推送 redemption.fulfilled。

curl -X POST https://aibulk.uk/api/wholesale/v1/redemptions \
  -H "Authorization: Bearer awk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"code":"XXXX-XXXX-XXXX-XXXX","redeemInfo":{"account_id":"<Claude Organization ID>"}}'
# -> {"redemptionId":"...","status":"pending","code":"...","orderId":"..."}
# then poll: curl -H "Authorization: Bearer awk_your_key" https://aibulk.uk/api/wholesale/v1/redemptions/<redemptionId>

错误码、payload 示例与重试规则见完整接口文档。

可选：出货 Webhook

让 order.delivered / topup.credited 主动推送到你的服务器，免轮询。先配置 URL（签名 secret 仅返回一次，重新配置即轮换），再用 POST /wholesale/v1/webhook/test 验证：

curl -X PUT https://aibulk.uk/api/wholesale/v1/webhook \
  -H "Authorization: Bearer awk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://your-server.example.com/aibulk-webhook"}'

收到推送后，先用原始请求体校验 HMAC 签名再信任内容：

// Node.js — verify an AIBulk webhook delivery
import { createHmac, timingSafeEqual } from "node:crypto";

function isValidAibulkWebhook(rawBody, signatureHeader, secret) {
  const expected = "sha256=" + createHmac("sha256", secret).update(rawBody).digest("hex");
  return !!signatureHeader && signatureHeader.length === expected.length &&
    timingSafeEqual(Buffer.from(signatureHeader), Buffer.from(expected));
}
// app.post("/aibulk-webhook", ...): verify X-AIBulk-Signature against the raw body,
// dedupe on X-AIBulk-Event-Id, then respond 2xx within 5 seconds.

事件：order.delivered {orderId, externalOrderId, productId, qty, codes[], redeemUrl} / topup.credited {orderId, externalTopupId, amount, currency} / redemption.fulfilled 与 redemption.failed {orderId, externalOrderId, productId, redemptionId, code, status, failureCode, retryable, fulfilledAt} / order.delivery_attention / webhook.test。信封字段 eventId / event / timestamp 平铺在同一层 JSON。非 2xx 或超 5 秒会指数退避重试（最多 10 次、间隔封顶 6 小时）；重投共享同一 X-AIBulk-Event-Id，请按它去重。完整 schema 见 openapi.json 的 webhooks 段。

约定与限制

金额一律十进制字符串（如 "12.5"），币种 USDT / USDC。
下单必须携带 externalOrderId；充值必须携带 externalTopupId（或 Idempotency-Key）。每次重试复用原值；需要锁定报价时传 expectedUnitPrice，价格变化会返回 price_changed。
大额下单前先检查可购性。payment=balance 即时扣款，direct_code 礼品卡可能先返回 paid、codes=[]，取码完成后交付；payment=intent 返回 checkoutUrl，只交给付款人，不要写进日志或公开；人工支付后每 10–30 秒轮询订单取 code（状态同步有 10 秒节流）。未支付的 intent 单约 15 分钟过期，但迟到的支付仍会被对账承认并照常发货。
全渠道单价按用户等级固定定价（Lv1–Lv5），网页与 API 同价；等级分 = 累计消费 + 余额，充值即可提升。
错误响应固定为 { error, message, requestId }，请按 error 码分支（unauthorized / insufficient_balance / rate_limited …）。
限流 300 次/分钟；请根据 X-RateLimit-* / Retry-After 退避，并保留 X-Request-Id 供问题追踪。
deliveryType=redemption 交付 code + redeemUrl；direct_code 直接交付礼品卡 code，redeemUrl 为 null。用 productGroupId、denomination、faceCurrency、region 展示面额，下单传所选 SKU 的 id。stockMode=limited 需检查数量；fulfillmentStatus=needs_attention 表示交付及退款待人工核对，请保留原单。
payment=intent 订单与充值单约 15 分钟未支付即过期，之后请用新的 externalOrderId 重新下单。USDC 充值按 1:1 记入 USDT 余额。
通过 API 出的兑换码不设有效期；首次提交即占用该码，兑换失败可换资料重提。
兼容性：变更只做加法，字段不改名不删除，不认识的字段请忽略。枚举值（status、stockMode、deliveryType、fulfillmentStatus、错误码、webhook 事件等）会增加——遇到未知值按「不支持」处理，不要让整个响应解析失败。redeemUrl 等可空字段可能为 null。每次变更都按日期记在变更日志。
字段命名：POST /wholesale/v1/orders 返回 camelCase（orderId、externalOrderId）；订单列表行和订单详情也带同名 camelCase 字段（orderId、externalOrderId、productId …），与原有 snake_case 字段（id、external_order_id、product_id …）并存、值相同。建议统一用 camelCase。