Brand Partner API¶

一个小巧、可预测的 REST API，用于创建 mintbot 订单、轮询订单状态并接收生命周期事件。输入 JSON，输出 JSON。Bearer-token 认证。幂等写入。已签名的 webhooks。

概览¶


基础 URL	`https://mint.mintbot.ai/api/v1`
认证	`Authorization: Bearer ***
幂等性	每个 `POST` 都使用 `Idempotency-Key: <uuid>`
内容类型	`application/json`
速率限制	每个 partner 120 req / 60 s
Webhooks	使用 HMAC-SHA256 签名，最多重试 7 次

认证¶

每个请求都在 Authorization header 中发送 partner API key。可在控制台生成或轮换 key。

Authorization: Bearer mo_liv...xxxx
Content-Type: application/json

轮换没有宽限窗口

轮换 key 会以原子方式撤销前一个 key。请在点击 Rotate 之前，先计划好在配置中替换该值。

幂等性¶

每个 POST 都需要 Idempotency-Key header。每个不同请求使用任意 UUID 都可以。

我们会缓存响应 24 小时。使用同一 key 重试会通过 Idempotent-Replay: true 重放原始响应。
使用同一 key 但提交 不同 body 会返回 409 idempotency_key_mismatch。

订单¶

创建订单¶

POST /orders

创建一个订单并返回 Stripe Checkout URL。付款确认后，mintbot 会预配 agent，并自动记录 partner-cut 收入事件。

请求

{
  "tier": "s1",
  "duration_months": 1,
  "credit_usd": 10,
  "language": "en",
  "external_id": "your-side-id",
  "success_url": "https://your.app/thanks?id={ORDER_ID}",
  "cancel_url":  "https://your.app/cart",
  "webhook_url": "https://your.app/mintbot-webhook"
}

tier: trial、s1、s2、s4 之一。
duration_months: 服务器运行的日历月数。必须是 1、3 或 12 之一。
credit_usd: 可选。 随订单一起预充值的聊天额度。
language: 可选。 影响 Stripe Checkout 区域设置和欢迎邮件语言。
external_id: 可选。 会在每个 webhook 和订单响应中原样返回——可用它把 mintbot 订单关联到你自己系统中的记录行。
success_url · cancel_url: Stripe Checkout 返回 URL。{ORDER_ID} 会在服务端替换。
webhook_url: 可选。 针对此订单覆盖 partner 级 webhook URL。

响应 — 201 Created

{
  "id": 42,
  "tier": "s1",
  "duration_months": 1,
  "credit_usd": 10,
  "amount_cents": 1200,
  "currency": "usd",
  "status": "awaiting_payment",
  "checkout_url": "https://checkout.stripe.com/c/pay/cs_test_…",
  "panel_url": null,
  "expires_at": null,
  "language": "en",
  "external_id": "your-side-id",
  "created_at": "2026-05-16 09:58:00",
  "paid_at": null
}

示例

curlPython

curl -X POST https://mint.mintbot.ai/api/v1/orders \
  -H "Authorization: Bearer *** \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "tier": "s1",
    "duration_months": 1,
    "credit_usd": 10,
    "success_url": "https://your.app/thanks?id={ORDER_ID}",
    "cancel_url":  "https://your.app/cart"
  }'

import os, uuid, requests

r = requests.post(
    "https://mint.mintbot.ai/api/v1/orders",
    headers={
        "Authorization": f"Bearer {os.environ['MINTBOT_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "tier": "s1",
        "duration_months": 1,
        "credit_usd": 10,
        "success_url": "https://your.app/thanks?id={ORDER_ID}",
        "cancel_url":  "https://your.app/cart",
    },
    timeout=10,
)
r.raise_for_status()
order = r.json()
redirect_to = order["checkout_url"]

获取订单¶

GET /orders/{id}

通过 mintbot id 获取单个订单。返回形状与 POST /orders 相同。

curl https://mint.mintbot.ai/api/v1/orders/42 \
  -H "Authorization: Bearer ***

列出订单¶

GET /orders

游标分页列表，最新的在前。

查询参数

status: 可选。 按 awaiting_payment、completed、deployed、deploy_failed 或 expired 过滤。
cursor: 可选。 传入上一页的 next_cursor 以继续。

响应

{
  "items": [ /* OrderResponse … */ ],
  "next_cursor": "37"
}

当没有更多页面时，next_cursor 为 null。

续订订单¶

POST /orders/{id}/renew

将现有 agent 延长另一个 duration_months。仅基础设施——不附带新的聊天额度。返回新的 order id 和新的 Stripe Checkout URL。

请求

{
  "duration_months": 1,
  "external_id": "your-side-id",
  "success_url": "https://your.app/thanks?id={ORDER_ID}",
  "cancel_url":  "https://your.app/account"
}

收入¶

读取收入¶

GET /revenue

总计加上最新 200 个账本事件。

查询参数

include_paid: 可选，默认 true。 设为 false 时只查看尚未支付的事件。

响应

{
  "currency": "usd",
  "gross_cents": 12000,
  "partner_cut_cents": 2000,
  "mintbot_cut_cents": 10000,
  "unpaid_cents": 800,
  "events": [
    {
      "id": 7,
      "order_id": 42,
      "kind": "order_paid",
      "gross_cents": 1200,
      "partner_cut_cents": 200,
      "mintbot_cut_cents": 1000,
      "currency": "usd",
      "created_at": "2026-05-16 09:58:00",
      "payout_id": null,
      "payout_at": null
    }
  ]
}

合作伙伴资料¶

获取资料¶

GET /partner

返回你的 partner profile 以及未支付余额——适合在你自己的管理 UI 中展示收益，而无需自行存储。

响应

{
  "id": 12,
  "email": "you@kliendifirma.com",
  "pricing_currency": "usd",
  "balance_unpaid_cents": 800,
  "webhook_url": "https://your.app/mintbot-webhook",
  "api_key_prefix": "mo_live_a12b"
}

Webhooks¶

当订单发生变化时，我们会向你配置的 webhook URL POST 一个已签名的 JSON 事件。

事件类型¶

Event	触发时机
`order.created`	Stripe Checkout session 已创建，等待付款。
`order.paid`	Stripe 已确认付款。收入事件已记录。
`order.cancelled`	订单超时或被明确取消。
`agent.provisioning_started`	此订单的部署流水线已启动。
`agent.ready`	部署成功。Payload 包含 `panel_url` 和 `expires_at`。
`agent.failed`	部署流水线出错。查看 `error` field 了解失败步骤。
`agent.expired`	Agent TTL 已到期。partner 可通过 `POST /orders/{id}/renew` 续订。

投递与重试¶

按指数计划最多尝试 7 次：0s, 30s, 2m, 10m, 1h, 6h, 24h。
最后一次尝试后，投递会标记为 exhausted 并停止重试。
在 10 秒 内返回 2xx 状态以确认接收。

请求 headers¶

Content-Type: application/json
User-Agent: mintbot-webhook/1.0
X-Mintbot-Signature: t=<unix_ts>,v1=<hex_hmac_sha256>
X-Mintbot-Event-Id: evt_42_order.paid_1747371234567
X-Mintbot-Event-Type: order.paid

示例 payload — `order.paid`¶

{
  "id": 42,
  "tier": "s1",
  "duration_months": 1,
  "credit_usd": 10,
  "amount_cents": 1200,
  "currency": "usd",
  "status": "completed",
  "external_id": "your-side-id",
  "paid_at": "2026-05-16 10:02:14"
}

验证签名¶

签名为 HMAC-SHA256(secret, "{timestamp}.{raw_body}")。务必验证 raw request body——重新序列化已解析的 JSON 会导致比较失败。

PythonNode.js

import hmac, hashlib, time

def verify(secret: str, body: bytes, header: str, tolerance: int = 300) -> bool:
    try:
        ts_part, v1_part = header.split(",", 1)
        ts  = int(ts_part.split("=", 1)[1])
        sig = v1_part.split("=", 1)[1]
    except Exception:
        return False
    if abs(int(time.time()) - ts) > tolerance:
        return False
    expected = hmac.new(
        secret.encode(),
        f"{ts}.".encode() + body,
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(expected, sig)

const crypto = require("crypto");

function verify(secret, rawBody, header, toleranceSec = 300) {
  const [tsPart, v1Part] = header.split(",");
  const ts  = Number(tsPart.split("=")[1]);
  const sig = v1Part.split("=")[1];
  if (Math.abs(Date.now() / 1000 - ts) > toleranceSec) return false;
  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${ts}.`)
    .update(rawBody)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(expected, "hex"),
    Buffer.from(sig, "hex"),
  );
}

幂等接收方

使用 X-Mintbot-Event-Id 作为你的去重 key——重试会复用同一个 id，因此在该列上执行行级 INSERT … ON CONFLICT DO NOTHING 可以保证你的 handler 安全。

错误¶

每个错误响应都带有稳定的 code，便于你在程序中分支处理。message field 是给人看的提示，可能会在不同版本之间变化。request_id 会回显 X-Request-Id response header——提交支持工单时请附上它。

{
  "error": {
    "code": "invalid_api_key",
    "message": "API key is unknown or revoked.",
    "request_id": "f0c2d6c4-…"
  }
}

Code	含义
`unauthenticated`	缺少 `Authorization` header 或格式错误。
`invalid_api_key`	API key 未知或已被轮换失效。
`rate_limited`	超出每 partner 或每 IP 速率限制——请查看 `Retry-After`。
`missing_idempotency_key`	`POST` request 缺少 `Idempotency-Key`。
`idempotency_key_mismatch`	同一 key 被用于不同的 request body。
`validation_error`	Request body 未通过 schema validation。
`not_found`	资源不存在，或不属于你的 partner。
`payment_gateway_error`	Stripe 拒绝创建 Checkout session。

速率限制¶

每个 partner 120 请求 / 60 s 滚动窗口。突发和稳定流量共享同一个 bucket。
60 请求 / 60 s 的独立每 IP bucket，用于未认证和认证失败请求——避免 bearer 暴力破解消耗 partner 配额。
超额请求会返回 429 rate_limited，并带有 Retry-After header（需要退避的秒数）。

需要帮助？¶

这些文档是写给真正使用 API 的 partners 看的。如果有内容缺失、令人困惑或过时，请告诉你的 mintbot agent——他们会转发反馈，我们会更新页面。