前払い残高の管理

このページの内容は Apigee と Apigee ハイブリッドに該当します。

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
    }
  ]
}

このサンプルレスポンスでは、このデベロッパーに 2 つの前払い残高があり、通貨ごとに 1 つずつです。残高は units フィールドと nanos フィールドで確認できます。lastCreditTime フィールドはエポックタイム形式で、デベロッパーの残高が最後にクレジットされた時間を示します。

デベロッパー残高がマイナス

デベロッパーが短い時間内に複数の API 呼び出しを行う場合、デベロッパーが過剰な API 呼び出しを実行でき、そのデベロッパーにとってマイナスのウォレット残高が発生する可能性があります。

このシナリオは、同じデベロッパーからの API 呼び出しを複数の Message Processor が処理している場合に発生します。それぞれの Message Processor には、API 呼び出しが許可されているデベロッパー残高のコピーが含まれます。すべての Message Processor は定期的に Cassandra データベースのメイン残高とそれぞれの残高を同期します。同期にわずかな遅延があるため、Message Processor のデベロッパーのウォレット残高がメイン残高と同期されていない可能性があります。たとえば、ある時点での Message Processor のデベロッパーのウォレット残高が $2 の場合、メインの残高は $0 になることがあります。そのため、Message Processor はデベロッパーのウォレットにまだ $2 であると考えて、デベロッパーからの API 呼び出しを許可します。

Apigee は、Message Processor のウォレット残高を、わずかな遅延しか生じさせずほぼリアルタイムで同期します。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"
    }
  ]
}

注: 特定通貨のデベロッパー残高にクレジットした後、新しい残高が Apigee のすべてのコンポーネントに反映されるまでに 5 分ほどかかります。この間、その通貨についてデベロッパーの残高を再度クレジットしようとすると、creditBalance API によってエラーが報告されます。したがって、ベストプラクティスとして、特定の通貨の 2 回のクレジットの間に約 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"
    }
  ]
}