管理预付款账号余额

本页面适用于 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 文档。

本页面介绍如何管理预付费结算账号。

您可以使用 Apigee API 管理开发者的预付费结算账号。通过使用 API，您可以执行以下任务：

查看获利配置
更新获利配置
查看开发者余额
存入开发者余额
调整开发者余额

查看获利配置

如需查看开发者的获利配置，请向以下 API 发出 GET 请求：

https://apigee.googleapis.com/v1/organizations/$YOUR_GOOGLE_PROJECT_ID/developers/$DEVELOPER_EMAIL_ID/monetizationConfig

使用此 API，您可以查看开发者的结算类型。如需详细了解此 API，请参阅 getMonetizationConfig。

以下示例展示了如何使用 curl 命令查看开发者的获利配置：

curl -H "Authorization: Bearer $TOKEN" \
https://apigee.googleapis.com/v1/organizations/$YOUR_GOOGLE_PROJECT_ID/developers/$DEVELOPER_EMAIL_ID/monetizationConfig

运行该命令时，您会看到类似于以下内容的响应：

{
  "billingType": "PREPAID",
}

更新获利配置

如需更新开发者的获利配置，请向以下 API 发出 PUT 请求：

https://apigee.googleapis.com/v1/organizations/$YOUR_GOOGLE_PROJECT_ID/developers/$DEVELOPER_EMAIL_ID/monetizationConfig

使用此 API，您可以更新开发者的结算类型。如需详细了解此 API，请参阅 updateMonetizationConfig。

以下示例展示了如何使用 curl 命令更新开发者的获利配置：

curl -H "Authorization: Bearer $TOKEN" \
-H "Content-type: application/json" \
-X PUT \
-d '{
"billingType": "POSTPAID",
}' \
https://apigee.googleapis.com/v1/organizations/$YOUR_GOOGLE_PROJECT_ID/developers/$DEVELOPER_EMAIL_ID/monetizationConfig

运行该命令时，您会看到类似于以下内容的响应：

{
  "billingType": "POSTPAID",
}

更改结算类型

您的开发者可以将结算从预付费切换为后付费，反之亦然。本部分介绍当开发者更改其结算类型时 Apigee 中发生的更改。

后付费到预付费

如果开发者从后付费切换为预付费，Apigee 会立即在配置中将开发者的 billingType 设置为 PREPAID。开发者可以在预付的充值金额范围内开始使用 API。根据您的自定义获利报告，开发者后付费账号中的所有现有用量应由您（API 提供方）单独结算。

预付费到后付费

如果开发者从预付费切换为后付费，Apigee 会立即在配置中将开发者的 billingType 设置为 POSTPAID。您的自定义获利报告会将开发者预付费账号中的所有现有余额（所有币种）显示为存入交易。计算开发者在结算周期后应付的金额时，您（API 提供方）必须考虑开发者账号中的存入余额。

查看开发者余额

如需查看开发者预付费账号的余额，请向以下 API 发出 GET 请求：

https://apigee.googleapis.com/v1/organizations/$YOUR_GOOGLE_PROJECT_ID/developers/$DEVELOPER_EMAIL_ID/balance

如需详细了解此 API，请参阅 getBalance。

以下示例展示了如何查看开发者预付费账号中的余额：

curl -H "Authorization: Bearer $TOKEN" \
https://apigee.googleapis.com/v1/organizations/$YOUR_GOOGLE_PROJECT_ID/developers/$DEVELOPER_EMAIL_ID/balance

运行该命令时，您会看到类似于以下内容的响应：

{
  "wallets": [
    {
      "balance": {
        "currencyCode": "USD",
        "units": "150",
        "nanos": 500000000
      },
      "lastCreditTime": 1234567890
    },
    {
      "balance": {
        "currencyCode": "INR",
        "units": "10000",
        "nanos": 600000000
      },
      "lastCreditTime": 9876543210
    }
  ]
}

在示例响应中，开发者有两笔预付费账号余额，分别为不同币种。您可以通过 units 和 nanos 字段查看余额的金额。lastCreditTime 字段以纪元时间格式表示，表示开发者余额的上次存入时间。

负开发者余额

如果开发者在短时间内进行了多次 API 调用，则可能会允许开发者进行过多的 API 调用，从而导致开发者的钱包余额为负。

当多个消息处理器处理来自同一开发者的 API 调用时，就会出现这种情况。每个消息处理器都具有一个开发者余额的副本，根据该副本允许 API 调用。所有消息处理器会定期将其平衡与 Cassandra 数据库中的主余额进行同步。由于同步会出现短暂的延迟，消息处理器中开发者的钱包余额可能与主余额不同步。例如，在给定的时间点，如果开发者在消息处理器中的钱包余额为 2 美元，则主余额可能为 0 美元。因此，消息处理器允许开发者进行 API 调用，因为开发者的钱包中仍然有 2 美元。

Apigee 以近乎实时的方式同步消息处理器的钱包余额，并且延迟时间很短，您无法控制或配置 Apigee 的这种行为。但是，开发者进行的所有多余 API 调用都会被计算在内。在处理完开发者的所有 API 调用后，开发者钱包中的最终金额将反映该费用，即使过多的 API 调用也是如此。因此，当开发者下次向账户进行扣款时，为了获得正的钱包余额，开发者必须首先支付钱包中的负余额。

存入开发者余额

如需在开发者的预付费账号中存入余额，请向以下 API 发出 POST 请求：

https://apigee.googleapis.com/v1/organizations/$YOUR_GOOGLE_PROJECT_ID/developers/$DEVELOPER_EMAIL_ID/balance:credit

如需详细了解此 API，请参阅 creditBalance。

存入开发者的余额包括以下顺序步骤：

开发者使用支付网关从开发者门户向开发者账号充值。
开发者门户为该充值生成唯一的交易 ID。
开发者门户使用 organizations/{org}/developers/{developer}/balance:credit API 更新开发者余额。

以下示例显示了第 3 步的 API 调用并向开发者余额存入 150.21 美元。transactionId 设置为充值交易的交易 ID 的值（第 3 步）。

curl -H "Authorization: Bearer $TOKEN" \
-H "Content-type: application/json" \
-X POST \
-d '{
  "transactionAmount": {
     "currencyCode": "USD",
     "units": "150",
     "nanos": 210000000
  },
  "transactionId": "ab31b63e-f8e8-11eb-9a03-0242ac130003"
}' \
https://apigee.googleapis.com/v1/organizations/$YOUR_GOOGLE_PROJECT_ID/developers/$DEVELOPER_EMAIL_ID/balance:credit

运行该命令时，您会看到类似于以下内容的响应：

{
  "wallets": [
    {
      "balance": {
        "currencyCode": "USD",
        "units": "300",
        "nanos": 710000000
      },
      "lastCreditTime": "9876543210"
    },
    {
      "balance": {
        "currencyCode": "INR",
        "units": "10000",
        "nanos": 600000000
      },
      "lastCreditTime": "1234567890"
    }
  ]
}

注意：在您以某个币种存入开发者余额后，新余额大约需要 5 分钟才会体现在 Apigee 的所有组件中。在此期间，如果您再次尝试以先前存入的币种存入开发者余额，creditBalance API 会报告错误。因此，最佳做法是，在某个特定币种的两次存入之间留出大约 5 分钟的间隔。

调整开发者余额

如果您向开发者账号收取的费用过少或过多，则可以使用 adjustBalance API 来减少或增加账号余额。

如需调整开发者的预付款账号中的余额，请向以下 API 发出 POST 请求：

https://apigee.googleapis.com/v1/organizations/$YOUR_GOOGLE_PROJECT_ID/developers/$DEVELOPER_EMAIL_ID/balance:adjust

如需详细了解此 API，请参阅 adjustBalance。

如果要减少费用不足的开发者的余额，请将请求中的 units 字段设置为正值。以下示例将开发者预付款账号中的余额减少 50 美元：

curl -H "Authorization: Bearer $TOKEN" \
-H "Content-type: application/json" \
-X POST \
-d '{
  "adjustment": {
    "units": "50",
    "currencyCode": "USD"
  }
}' \
https://apigee.googleapis.com/v1/organizations/$YOUR_GOOGLE_PROJECT_ID/developers/$DEVELOPER_EMAIL_ID/balance:adjust

运行该命令时，您会看到类似于以下内容的响应：

{
  "wallets": [
    {
      "balance": {
        "currencyCode": "USD",
        "units": "150"
      },
      "lastCreditTime": "1635489199530"
    }
  ]
}

如果要增加费用过高的开发者的余额，请将请求中的 units 字段设置为负值。以下示例将开发者预付款账号中的余额增加 50.1 美元：

curl -H "Authorization: Bearer $TOKEN" \
-H "Content-type: application/json" \
-X POST \
-d '{
  "adjustment": {
    "units": "-50",
    "nanos": "100000000",
    "currencyCode": "USD"
  }
}' \
https://apigee.googleapis.com/v1/organizations/$YOUR_GOOGLE_PROJECT_ID/developers/$DEVELOPER_EMAIL_ID/balance:adjust

运行该命令时，您会看到类似于以下内容的响应：

{
  "wallets": [
    {
      "balance": {
        "currencyCode": "USD",
        "units": "200",
        "nanos": 100000000
      },
      "lastCreditTime": "1635489199530"
    }
  ]
}