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

# 设置常规自动充值

> 使用 Bright Data 账号管理 API 的 PUT /billing/autorecharge/regular 开启或关闭常规自动充值，并设置扣款的支付方式和以美元计的充值金额。

`PUT /billing/autorecharge/regular` 端点开启或关闭 Bright Data 账户的常规自动充值，并设置扣款的支付方式和充值金额。数据集自动充值设置不会改变。

> [!TIP]
>
> 将您的 API key 粘贴到授权字段中。要获取 API key，请[创建账号](https://www.bright.cn/?hs_signup=1\&utm_source=docs\&utm_campaign=playground)，并查看[如何生成新的 API key？](https://docs.brightdata.com/cn/api-reference/authentication.md#如何生成新的-api-key？)

## 此端点需要哪种 API key 权限？

`PUT /billing/autorecharge/regular` 需要 `billing.write.pay.settings` 权限。具有**管理员**或**财务**[权限级别](https://docs.brightdata.com/cn/api-reference/authentication.md#api-key-拥有哪些权限级别？)的 API key 拥有该权限。缺少该权限时，端点返回 HTTP 403 和纯文本消息。请在[账户设置](https://www.bright.cn/cp/setting/users)中管理 API key 权限。

## 如何开启常规自动充值？

发送 `enabled: true`，并附带 `pmethod_id` 和 `amount`：

1. 从 [`GET /billing/pmethods`](https://docs.brightdata.com/cn/api-reference/account-management-api/Get_payment_methods) 获取 `autorecharge_supported` 为 `true` 的支付方式 ID。
2. 从 [`GET /billing/autorecharge`](https://docs.brightdata.com/cn/api-reference/account-management-api/Get_auto_recharge_settings) 的 `regular.limits` 获取允许的金额范围。
3. 发送请求：

```bash theme={null}
curl -X PUT "https://api.brightdata.com/billing/autorecharge/regular" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true, "pmethod_id": "64f0c2a1e4b0a1b2c3d4e5f6", "amount": 200}'
```

响应返回新的常规自动充值设置，包括 `threshold`。

## 常规自动充值扣款多少？

当可用余额低于 ceil(`amount` / 4) 时开始充值。常规自动充值从不将余额补足到某个目标水平。扣款金额取决于当时的余额：

* 余额大于零：扣款金额正好为 `amount`
* 余额为零或负数：扣款金额为 `amount` × ceil(欠款 / `amount`)，最多为 10 × `amount`

例如，当 `amount` 设置为 200 时，可用余额低于 \$50 时开始充值：

| 可用余额 | 扣款 |
| - | - |
| \$30 | \$200 |
| -\$450 | \$600（200 × ceil(450 / 200)） |
| -\$5,000 | \$2,000（上限为 10 × 200） |

## 充值金额有哪些规则？

`amount` 以美元计，必须满足：

* 为整数美元。否则端点返回 `amount_not_whole`
* 不低于 `limits.min_amount`，所有账户均为 \$50。否则端点返回 `amount_too_low`
* 不高于 `limits.max_amount`，该值取决于公司类型，也可以按账户调整。否则端点返回 `amount_too_high`

可从 [`GET /billing/autorecharge`](https://docs.brightdata.com/cn/api-reference/account-management-api/Get_auto_recharge_settings) 读取账户的 `limits.min_amount` 和 `limits.max_amount`。

## 如何关闭常规自动充值？

只发送 `enabled: false`，不附带其他字段：

```bash theme={null}
curl -X PUT "https://api.brightdata.com/billing/autorecharge/regular" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled": false}'
```

关闭自动充值始终允许，即使 `available` 为 `false`。关闭常规自动充值不会关闭数据集自动充值。在 `enabled: false` 时发送 `pmethod_id` 或 `amount` 会返回 `invalid_param`。

## PUT 如何更新设置？

请求体包含常规部分的全部设置，请求是幂等的。重复发送相同的请求体，设置保持不变。如只需修改金额，请发送 `enabled: true`，附带当前的 `pmethod_id` 和新的 `amount`。

## 此端点可能返回哪些错误？

HTTP 400 和 `not_eligible` 的 HTTP 403 返回包含 `error` 和 `error_code` 的 JSON：

| HTTP 状态码 | `error_code` | 原因 |
| - | - | - |
| 400 | `invalid_param` | 类型错误、未知字段、`enabled: true` 时缺少 `pmethod_id` 或 `amount`，或 `enabled: false` 时发送了这两个字段 |
| 400 | `amount_too_low` | `amount` 低于 `limits.min_amount` |
| 400 | `amount_too_high` | `amount` 高于 `limits.max_amount` |
| 400 | `amount_not_whole` | `amount` 不是整数美元 |
| 400 | `pmethod_not_found` | 账户中没有此 ID 的已激活支付方式 |
| 400 | `pmethod_not_supported` | 该支付方式不支持自动充值或尚未确认 |
| 400 | `payment_required` | 账户没有已完成的付款 |
| 403 | `not_eligible` | 账户不可使用自动充值（`available: false`），而请求中包含 `enabled: true` |

HTTP 401、权限不足导致的 HTTP 403 和 HTTP 429 返回纯文本。账单端点允许每分钟 1,000 个请求、每小时 5,000 个请求。

## 相关端点

* [获取自动充值设置](https://docs.brightdata.com/cn/api-reference/account-management-api/Get_auto_recharge_settings.md)。当前设置和金额限制。
* [获取支付方式](https://docs.brightdata.com/cn/api-reference/account-management-api/Get_payment_methods.md)。支付方式 ID 以及是否支持自动充值。
* [设置数据集自动充值](https://docs.brightdata.com/cn/api-reference/account-management-api/Set_dataset_auto_recharge.md)。开启或关闭数据集自动充值。


## OpenAPI

````yaml cn-openapi PUT /billing/autorecharge/regular
openapi: 3.0.1
info:
  title: Bright Data API
  description: 将 Bright Data API 集成到您的流程中，以实现高端的爬取精度
  version: 1.0.0
servers:
  - url: https://api.brightdata.com
security:
  - bearerAuth: []
paths:
  /billing/autorecharge/regular:
    put:
      description: >-
        启用、修改或停用常规自动充值。需要 `billing.write.pay.settings` 权限。


        请求体包含常规部分的全部设置，PUT 是幂等的。数据集部分不会改变。


        `{"enabled": false}` 会停用常规自动充值，并且始终允许，即使 `available` 为
        `false`。要重新启用自动充值，请发送 `pmethod_id` 和 `amount`。


        当可用余额低于 ceil(`amount` / 4) 时开始充值。余额大于零时，扣款金额正好为 `amount`。余额为零或负数时，扣款金额为
        `amount` × ceil(欠款 / `amount`)，最多为 10 × `amount`。
      operationId: setRegularAutoRecharge
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/BillingRegularEnable'
                - $ref: '#/components/schemas/BillingDisable'
            examples:
              enable:
                summary: 启用
                value:
                  enabled: true
                  pmethod_id: 64f0c2a1e4b0a1b2c3d4e5f6
                  amount: 200
              disable:
                summary: 停用
                value:
                  enabled: false
      responses:
        '200':
          description: 新的常规自动充值设置
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingAutoRechargeRegular'
        '400':
          description: >-
            请求错误。`error_code` 取值：


            - `invalid_param`：类型错误、未知字段、`enabled: true` 时缺少 `pmethod_id` 或
            `amount`，或 `enabled: false` 时发送了 `pmethod_id` 或 `amount`。

            - `amount_too_low`："Amount should be at least $<min>"。

            - `amount_too_high`："Amount should be at most $<max>"。

            - `amount_not_whole`："Amount must be rounded"。

            - `pmethod_not_found`：账户中没有此 ID 的已激活支付方式。

            - `pmethod_not_supported`：该支付方式不支持自动充值或尚未确认。

            - `payment_required`：账户没有已完成的付款。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingError'
              example:
                error: Amount should be at least $50
                error_code: amount_too_low
        '401':
          description: 身份验证失败
          content:
            text/plain:
              schema:
                type: string
              example: User authentication is required
        '403':
          description: >-
            `text/plain`：API key 缺少 `billing.write.pay.settings`
            权限。`application/json` 且 `error_code` 为
            `not_eligible`：账户不可使用自动充值（`available: false`），而请求中包含 `enabled:
            true`。
          content:
            text/plain:
              schema:
                type: string
              example: >-
                Your API key lacks the required permissions for this action. You
                can change your token permissions at
                https://brightdata.com/cp/setting/users
            application/json:
              schema:
                $ref: '#/components/schemas/BillingError'
              example:
                error: Autocharge is not available for this account
                error_code: not_eligible
        '429':
          description: 超出速率限制（每分钟 1,000 个请求，每小时 5,000 个请求）
          content:
            text/plain:
              schema:
                type: string
components:
  schemas:
    BillingRegularEnable:
      title: 启用
      type: object
      required:
        - enabled
        - pmethod_id
        - amount
      additionalProperties: false
      properties:
        enabled:
          type: boolean
          enum:
            - true
        pmethod_id:
          type: string
          description: 来自 `GET /billing/pmethods` 的支付方式 ID。
          example: 64f0c2a1e4b0a1b2c3d4e5f6
        amount:
          type: integer
          description: 充值金额，单位为美元，必须为整数，介于 `limits.min_amount` 和 `limits.max_amount` 之间。
          example: 200
    BillingDisable:
      title: 停用
      type: object
      required:
        - enabled
      additionalProperties: false
      properties:
        enabled:
          type: boolean
          enum:
            - false
    BillingAutoRechargeRegular:
      type: object
      required:
        - available
        - enabled
        - pmethod_id
        - amount
        - threshold
        - limits
      properties:
        available:
          type: boolean
          description: >-
            账户可使用常规自动充值，且账户中有支持自动充值的支付方式时为 `true`。AWS Marketplace organic 账户、IBM
            账户，以及没有支持自动充值的支付方式或所有此类支付方式均被冻结的账户为 `false`。
        enabled:
          type: boolean
          description: 此部分已启用自动充值时为 `true`。
        pmethod_id:
          type: string
          nullable: true
          description: 用于自动充值的支付方式。停用时为 `null`。
        amount:
          type: integer
          nullable: true
          description: 充值金额，单位为美元。停用时为 `null`。
        threshold:
          type: number
          nullable: true
          readOnly: true
          description: 触发充值的余额水平：当可用余额低于 ceil(`amount` / 4) 时开始充值。停用时为 `null`。只读。
        limits:
          type: object
          description: 账户的金额限制。
          required:
            - min_amount
            - max_amount
          properties:
            min_amount:
              type: integer
              description: 最低金额，单位为美元。所有账户均为 $50。
            max_amount:
              type: integer
              description: 最高金额，单位为美元。取决于公司类型，也可以按账户调整。
    BillingError:
      type: object
      required:
        - error
        - error_code
      properties:
        error:
          type: string
          description: 可读的错误消息
        error_code:
          type: string
          enum:
            - invalid_param
            - amount_too_low
            - amount_too_high
            - amount_not_whole
            - pmethod_not_found
            - pmethod_not_supported
            - payment_required
            - not_eligible
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        在 Authorization 头中使用您的 Bright Data API Key 作为 Bearer token。


        **认证方法:**

        1. 从 Bright Data 账户设置获取您的 API Key:
        https://brightdata.com/cp/setting/users

        2. 在请求的 Authorization 头中包含 API Key

        3. 格式: `Authorization: Bearer YOUR_API_KEY`


        **示例:**

        ```

        Authorization: Bearer
        b5648e1096c6442f60a6c4bbbe73f8d2234d3d8324554bd6a7ec8f3f251f07df

        ```


        了解如何获取 Bright Data API Key:
        https://docs.brightdata.com/cn/api-reference/authentication#如何生成新的-api-key？
      bearerFormat: API Key

````