跳转至

计费 API

Inklet 使用 Stripe 进行订阅管理。计费接口允许用户订阅、管理支付方式和查看发票。除非另有说明，所有接口均需要认证。

接口列表

GET /auth/subscription

:material-lock: 需要认证

获取当前认证用户的订阅信息。

请求头：

Authorization: Bearer {accessToken}

响应： 200 OK

{
  "status": "active",
  "plan": "pro",
  "interval": "monthly",
  "currentPeriodStart": "2026-01-15T10:30:00Z",
  "currentPeriodEnd": "2026-02-15T10:30:00Z",
  "cancelAtPeriodEnd": false,
  "stripeCustomerId": "cus_abc123",
  "stripeSubscriptionId": "sub_xyz789"
}

{
  "status": "none",
  "plan": null,
  "interval": null,
  "currentPeriodStart": null,
  "currentPeriodEnd": null,
  "cancelAtPeriodEnd": false,
  "stripeCustomerId": "cus_abc123",
  "stripeSubscriptionId": null
}
字段 类型 描述
status string none、active、past_due、canceled、trialing 之一
plan string 或 null 订阅计划名称
interval string 或 null monthly 或 yearly
currentPeriodStart timestamp 或 null 当前计费周期的开始时间
currentPeriodEnd timestamp 或 null 当前计费周期的结束时间
cancelAtPeriodEnd boolean 订阅是否在当前周期结束时取消
stripeCustomerId string Stripe Customer ID
stripeSubscriptionId string 或 null Stripe Subscription ID（无订阅时为 null）

错误：

状态码 原因
401 访问令牌缺失或无效

POST /auth/subscription/checkout

:material-lock: 需要认证

创建 Stripe Checkout 会话以开始新的订阅。返回一个 URL，用于将用户重定向到 Stripe 托管的结账页面。

请求头：

Authorization: Bearer {accessToken}

请求体：

{
  "interval": "monthly"
}
字段 类型 必填 描述
interval string 是 monthly 或 yearly

响应： 200 OK

{
  "url": "https://checkout.stripe.com/c/pay/cs_live_abc123..."
}

客户端集成

使用 window.location.href 将用户重定向到返回的 url，或在新标签页中打开。支付成功后，Stripe 会将用户重定向回你的门户。

错误：

状态码 原因
400 interval 值无效
401 访问令牌缺失或无效
409 用户已有有效订阅

POST /auth/subscription/portal

:material-lock: 需要认证

创建 Stripe Billing Portal 会话。账单门户允许用户管理支付方式、查看发票以及取消或修改订阅。

请求头：

Authorization: Bearer {accessToken}

响应： 200 OK

{
  "url": "https://billing.stripe.com/p/session/abc123..."
}

将用户重定向到返回的 url。该门户提供 Stripe 托管的自助账单管理界面。

错误：

状态码 原因
401 访问令牌缺失或无效

GET /auth/subscription/invoices

:material-lock: 需要认证

从 Stripe 获取当前认证用户的发票历史。

请求头：

Authorization: Bearer {accessToken}

响应： 200 OK

{
  "invoices": [
    {
      "id": "in_1abc2def3ghi",
      "date": "2026-01-15T10:30:00Z",
      "amount": 999,
      "currency": "usd",
      "status": "paid",
      "invoiceUrl": "https://invoice.stripe.com/i/acct_123/live_abc",
      "pdfUrl": "https://pay.stripe.com/invoice/acct_123/live_abc/pdf"
    },
    {
      "id": "in_4jkl5mno6pqr",
      "date": "2025-12-15T10:30:00Z",
      "amount": 999,
      "currency": "usd",
      "status": "paid",
      "invoiceUrl": "https://invoice.stripe.com/i/acct_123/live_def",
      "pdfUrl": "https://pay.stripe.com/invoice/acct_123/live_def/pdf"
    }
  ]
}
字段 类型 描述
id string Stripe Invoice ID
date timestamp 发票创建日期
amount integer 以最小货币单位表示的金额（例如 USD 的单位为美分）
currency string 三位 ISO 货币代码
status string draft、open、paid、void、uncollectible 之一
invoiceUrl string 托管发票页面的 URL
pdfUrl string 发票 PDF 下载链接

金额格式

amount 字段以最小货币单位表示。对于 USD，999 表示 $9.99。显示时需除以 100。

错误：

状态码 原因
401 访问令牌缺失或无效

POST /auth/webhook/stripe

Stripe Webhook 接口。由 Stripe 服务器在订阅事件发生时调用 --- 不由客户端调用。

无需认证

此接口不使用 Bearer 令牌认证。它通过 Stripe-Signature 请求头和后端配置的 Webhook 签名密钥来验证请求。

处理的事件：

事件 操作
checkout.session.completed 在数据库中激活订阅
invoice.paid 更新计费周期
invoice.payment_failed 将订阅标记为 past_due
customer.subscription.updated 同步计划、周期和取消状态
customer.subscription.deleted 将订阅标记为 canceled

响应： 200 OK

返回空的 200 响应以确认接收。Stripe 会在收到非 2xx 响应时重试。