> ## Documentation Index
> Fetch the complete documentation index at: https://docs.llmgenerator.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 创建账单门户会话

> 创建 Stripe 客户门户会话，用于管理订阅与支付方式。

## 概述

创建 Stripe Customer Portal 会话，用户可在此：

* 更新支付方式
* 查看账单历史
* 更换订阅套餐
* 下载发票
* 取消订阅

需要 JWT 访问令牌（会话鉴权）。

<Note>
  \*\*第三方集成：\*\*请改用 `POST /subscriptions/portal/api` 并以 API Key 鉴权。
</Note>

## 认证

<ParamField header="Authorization" type="string" required>
  JWT 访问令牌。格式：`Bearer YOUR_ACCESS_TOKEN`
</ParamField>

## 请求体

<ParamField body="returnUrl" type="string">
  用户退出门户后的跳转 URL，默认返回应用控制台。
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api.llmgenerator.com/api/v1/subscriptions/portal \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "returnUrl": "https://yourapp.com/settings/billing"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.llmgenerator.com/api/v1/subscriptions/portal', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      returnUrl: 'https://yourapp.com/settings/billing'
    })
  });

  const data = await response.json();
  // Redirect user to Stripe portal
  window.location.href = data.url;
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://api.llmgenerator.com/api/v1/subscriptions/portal',
      headers={
          'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
          'Content-Type': 'application/json'
      },
      json={
          'returnUrl': 'https://yourapp.com/settings/billing'
      }
  )
  data = response.json()
  print(f"Redirect to: {data['url']}")
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "url": "https://billing.stripe.com/p/session/test_a1b2c3d4..."
  }
  ```
</ResponseExample>

## 响应字段

<ResponseField name="url" type="string">
  用户需跳转到的 Stripe 托管账单门户 URL。
</ResponseField>

## 门户能力

Stripe Customer Portal 支持用户：

| 功能       | 说明          |
| -------- | ----------- |
| **支付方式** | 添加、更新或移除银行卡 |
| **发票**   | 查看并下载历史发票   |
| **套餐变更** | 升级或降级订阅     |
| **取消订阅** | 取消订阅        |
| **账单历史** | 查看历史交易      |

## 错误响应

<ResponseField name="400">
  错误请求——未找到账单账户，用户需先完成购买。
</ResponseField>

<ResponseField name="401">
  未授权——令牌无效或缺失。
</ResponseField>

<Note>
  账单门户仅对已发生过购买或拥有活跃订阅的用户可用；新用户请使用结账接口。
</Note>

***

## POST /subscriptions/portal/api

使用 API Key 创建 Stripe Customer Portal 会话，适合第三方集成。

### 认证

需要 API Key：

```
Authorization: Bearer llmgen_your_api_key_here
```

### 请求体

与 `/subscriptions/portal` 相同。

### 响应

与 `/subscriptions/portal` 相同。

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api.llmgenerator.com/api/v1/subscriptions/portal/api \
    -H "Authorization: Bearer llmgen_your_api_key_here" \
    -H "Content-Type: application/json" \
    -d '{
      "returnUrl": "https://yourapp.com/settings/billing"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.llmgenerator.com/api/v1/subscriptions/portal/api', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer llmgen_your_api_key_here',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      returnUrl: 'https://yourapp.com/settings/billing'
    })
  });

  const data = await response.json();
  // Redirect user to Stripe portal
  window.location.href = data.url;
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://api.llmgenerator.com/api/v1/subscriptions/portal/api',
      headers={
          'Authorization': 'Bearer llmgen_your_api_key_here',
          'Content-Type': 'application/json'
      },
      json={
          'returnUrl': 'https://yourapp.com/settings/billing'
      }
  )
  data = response.json()
  print(f"Redirect to: {data['url']}")
  ```
</RequestExample>

## 最佳实践

* **设置页入口**：在应用设置中提供「管理账单」按钮
* **结账后**：订阅购买完成后可引导用户进入门户
* **客服**：将门户作为账单问题的自助渠道