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

# 从 v1 迁移到 v2

> 从客户 API v1 升级到 v2 的分步指南

<Warning>
  **API v1 已弃用。** 目前仍可用，但将在未来版本中移除。请迁移到 v2，以使用完整端点集合、改进的身份验证、个人资料管理与发票操作。
</Warning>

## 变更内容

API v2 引入版本化 URL 结构、新端点组，并在现有 API 密钥方式之外提供可选的 Bearer 令牌身份验证流程。

| 方面                 | v1                          | v2                              |
| ------------------ | --------------------------- | ------------------------------- |
| **基础路径**           | `/customer/v1/`             | `/customer/v2/`                 |
| **认证 — API 密钥**    | 标头 `X-ORBIT-KEY: <key>`     | 相同 — 无变化                        |
| **认证 — Bearer 令牌** | 不支持                         | `Authorization: Bearer <token>` |
| **许可证端点**          | `/customer/v1/licenses/...` | `/customer/v2/licenses/...`     |
| **IP 白名单**         | 扁平端点                        | 嵌套在 `/licenses/{id}/ips` 下      |
| **API 密钥管理**       | 不可用                         | `/customer/v2/api-keys/...`     |
| **个人资料**           | 不可用                         | `/customer/v2/profile/...`      |
| **发票**             | 不可用                         | `/customer/v2/invoices/...`     |

## 身份验证 — 无需变更

若使用 `X-ORBIT-KEY` 标头认证，**认证方面无需变更**。同一密钥可用于 v2。

```bash theme={null}
# Works with both v1 and v2
curl -H "X-ORBIT-KEY: YOUR_API_KEY" https://api.orbitflare.com/customer/v2/licenses
```

可选择升级到 Bearer 令牌认证（设备流程或钱包签名）以提高安全性。详见 [认证端点](/cn/api-documentation/customer-endpoints/auth/device-code)。

## 端点映射

### 许可证

| v1 端点                                            | v2 等价                                            |
| ------------------------------------------------ | ------------------------------------------------ |
| `GET /customer/v1/licenses`                      | `GET /customer/v2/licenses`                      |
| `GET /customer/v1/licenses/{id}`                 | `GET /customer/v2/licenses/{id}`                 |
| `POST /customer/v1/licenses/{id}/reset-key`      | `POST /customer/v2/licenses/{id}/reset-key`      |
| `POST /customer/v1/licenses/{id}/regenerate-key` | `POST /customer/v2/licenses/{id}/regenerate-key` |
| `GET /customer/v1/locations`                     | `GET /customer/v2/licenses/locations`            |
| `GET /customer/v1/licenses/{id}/ips`             | `GET /customer/v2/licenses/{id}/ips`             |
| `POST /customer/v1/licenses/{id}/ips`            | `POST /customer/v2/licenses/{id}/ips`            |
| `DELETE /customer/v1/licenses/{id}/ips/{ip}`     | `DELETE /customer/v2/licenses/{id}/ips/{ip}`     |

### 仅 v2 新增

这些端点在 v1 中不存在，仅在 v2 中可用：

| 端点                                        | 说明          |
| ----------------------------------------- | ----------- |
| `POST /customer/v2/auth/device/code`      | 启动设备授权流程    |
| `POST /customer/v2/auth/device/token`     | 用设备码换取访问令牌  |
| `POST /customer/v2/auth/wallet/challenge` | 请求钱包签名质询    |
| `POST /customer/v2/auth/wallet/verify`    | 验证钱包签名并获取令牌 |
| `GET /customer/v2/api-keys`               | 列出全部 API 密钥 |
| `POST /customer/v2/api-keys`              | 创建新 API 密钥  |
| `PATCH /customer/v2/api-keys/{id}`        | 更新 API 密钥   |
| `DELETE /customer/v2/api-keys/{id}`       | 删除 API 密钥   |
| `GET /customer/v2/profile`                | 获取用户资料      |
| `PATCH /customer/v2/profile`              | 更新用户资料      |
| `GET /customer/v2/profile/balance`        | 获取账户余额      |
| `GET /customer/v2/invoices`               | 列出发票        |
| `GET /customer/v2/invoices/{id}`          | 获取指定发票      |
| `POST /customer/v2/invoices/{id}/pay`     | 使用账户余额支付发票  |

## 迁移步骤

<Steps>
  <Step title="更新基础 URL">
    将客户端路径前缀从 `/customer/v1/` 改为 `/customer/v2/`：

    ```bash theme={null}
    # Before
    curl -H "X-ORBIT-KEY: YOUR_API_KEY" \
      https://api.orbitflare.com/customer/v1/licenses

    # After
    curl -H "X-ORBIT-KEY: YOUR_API_KEY" \
      https://api.orbitflare.com/customer/v2/licenses
    ```
  </Step>

  <Step title="更新 locations 端点">
    locations 端点从顶层路径移至 licenses 组：

    ```bash theme={null}
    # Before
    GET /customer/v1/locations

    # After
    GET /customer/v2/licenses/locations
    ```
  </Step>

  <Step title="测试集成">
    在 v2 端点上运行现有集成。共享端点（许可证、IP）的响应形状向后兼容。已迁移端点通常无需修改响应解析。
  </Step>

  <Step title="（可选）升级认证">
    若希望使用 Bearer 令牌而非 API 密钥，请实现 [设备授权流程](/cn/api-documentation/customer-endpoints/auth/device-code)或[钱包签名流程](/cn/api-documentation/customer-endpoints/auth/wallet-challenge)。
  </Step>
</Steps>

## 需要帮助？

迁移中遇到问题，请在 [Discord](https://discord.gg/orbitflare) 联系或发邮件至 [support@orbitflare.com](mailto:support@orbitflare.com)。