Subaccounts API（ベータ版）の概要

はじめに

Subaccounts APIを使用すると、別々のビジネスユニット、ユースケース、製品ステージ、または別々の顧客のためにサブアカウントをプログラムで作成および管理することができます。APIは、開発者がサブアカウントのロジスティクスの様々な側面を扱うことを可能にします：クレジットの管理、使用状況の追跡、使用制限の設定、サブアカウントの一時停止など。

下図は、プライマリアカウントとSubaccounts APIで作成されたサブアカウントとの関係を示している：

ベータ

このAPIは現在ベータ版です。

Vonageは常にお客様のフィードバックをお待ちしております。お客様のご意見は製品の改善に役立ちます。サポートが必要な場合は、Eメール サポート を送信し、件名にSubaccounts APIと明記してください。

ベータ期間中、VonageはAPIの機能を拡張する。

プロビジョニング

Subaccounts APIがリリースされました。 利用制限.Subaccounts APIにアクセスするには、アカウントマネージャーにご連絡ください。 ボンテージ・パートナー 自動的にアクセスできる。

対応機能

このリリースでは、以下の機能がサポートされています：

• 新しいサブアカウントを作成する
• 個人または共有残高をSubaccountに割り当てる
• プライマリアカウントからサブアカウントへのクレジット移動（Vonageが提供）、またはその逆。
• プライマリーアカウントからサブアカウントへの残高移動、またはその逆。
• すべてのSubaccountの残高とクレジットのリスト
• すべてのSubaccountの合計クレジットと合計残高を表示します。
• サブアカウントの一時停止/再アクティブ化

Concepts

Accountの残高とクレジット

すべてのVonage APIアカウントには、関連するアカウント残高があります。これは、使用可能な資金の量を示しています。アカウント残高は、チャージ可能なAPIコールが実行されるたびに差し引かれます。アカウント残高がゼロになると、そのアカウントにVonageが提供するクレジット機能がない限り、チャージ可能なAPIコールは実行できなくなります。アカウントにクレジット機能がある場合、アカウント残高はゼロ以下になる可能性があります。後払いアカウントはクレジット機能を持つアカウントであり、プリペイドアカウントはクレジット機能を持たないアカウントです。

顧客が利用可能なクレジットの額は、次のように呼ばれる。 credit_limit.従って、プラス残高のある後払い口座はすべて、その口座にある。 account_balance + |credit_limit| 使用可能な資金プリペイド・アカウントには、以下のものしかない。 account_balance 支出に充てることができる。

サブアカウント作成

デフォルトでは、新しく作成されたSubaccountsは、プライマリアカウントとその残高を共有します。つまり、Subaccountsのアクティビティから生じるすべての料金は、プライマリアカウントの残高に直接適用されます。

独自の残高を持つSubaccountを作成するには（Subaccountの活動から生じるすべての請求は、Subaccountの残高に直接適用されます）、パラメータを設定する必要があります。 use_primary_account_balance への FALSE.この変更は不可逆的である。独自の残高を持つSubaccountsは、後の段階で共有残高を持つSubaccountsに戻すことはできません。

後払いおよび前払いのサブアカウント

個別の残高を持つサブアカウントは、プリペイドまたはポストペイドのいずれかにすることができます。プライマリアカウントと残高を共有しているサブアカウントは、共有残高がプライマリアカウントに属しているため、プリペイド/ポストペイドを行うことはできません。

鍵だ：

• = 支持される。
• = サポートされていない。

プライマリーアカウントがプリペイドの場合、作成されたサブアカウントもプリペイドとなる。プライマリーアカウントが後払いである場合、作成されたサブアカウントは後払いまたは前払いのいずれかになります。

(個々の残高を持つ)サブアカウントは、プライマリ後払いサブアカウントがそのクレジットの一部をサブアカウントに割り当てた場合にのみ、後払いになる(プリペイドサブアカウントのクレジット量はゼロである)。したがって、クレジットを持たないプリペイド主勘定は、ポストペイド副勘定を持つことはできない。

鍵だ：

• = 支持される。
• n/a = 該当しない。

バランス・トランスファー

共有残高を持つ新しく作成されたSubaccountは、対応するプライマリアカウントの残高またはクレジット（Vonageによって提供される）がゼロでないことを前提として、APIコールを直接実行できます。新しく作成された個別残高のあるサブアカウントは、最初は残高がゼロであるため、APIコールを行うことはできません。プライマリアカウントからサブアカウントにいくらかの金額を送金する必要がある。

これは、プライマリアカウントがサブアカウントに資金を転送できることを意味し、これらの資金は、その残高（それが正であると仮定して）またはVonageによって提供される信用のいずれかから来ることができます。サブアカウントからプライマリアカウントに残高を戻すことも可能ですが、サブアカウント間の残高の直接移動はサポートされていません。

例ある後払いプライマリアカウントの残高がゼロで、Vonageから100ユーロのクレジットが提供された。つまり、残高が€-20になった。まだ€80 = |-20 -100|があり、自分で使うか、Subaccountsの1つに移すことができる。後払いのプライマリアカウントは20ユーロをサブアカウント1に送金することにした。この操作の後、プライマリアカウントの残高は€40になった。

信用配分

プライマリアカウントは、Vonage によって提供された信用枠がある場合、後払いと見なされます。後払いのプライマリアカウントは、その信用枠の一部をサブアカウントの1つに割り当てることができます。従って、残高はゼロだがクレジットはゼロではないサブアカウントを持つことが可能です。このサブアカウントは、割り当てられたクレジットがなくなるまでAPIコールを行うことができる。一般的に、正の残高を持つアカウントはすべて account_balance + |credit_limit| 支出可能な資金。

つまり、プライマリー・アカウントは、まだ使用されていない、あるいは割り当てられていない与信枠の一部または全部をサブアカウントに割り当てることができ、その逆も可能である（サブアカウントで使用されなかった与信はプライマリー・アカウントに戻すことができる）。

例20ユーロを使用し、さらに20ユーロをサブアカウント1に送金した後、後払いのプライマリアカウントの残高は40ユーロに減少し、個々の残高をサブアカウント2に割り当て、残りのクレジットのうち35ユーロをサブアカウント2に割り当てることにした。プライマリアカウントには、100|-40| = 60ユーロの割り当て可能なクレジットがあった。割り当て操作の後、プライマリ・アカウントの残クレジットは65ユーロになった：|credit_limit| = |-100| - 35 = 65ユーロ。

料金および支出の監視

Vonageは実際のVonage API使用量に対して課金しますが、プリペイド・アカウントとポストペイド・アカウントでは、その課金方法が異なります。サブアカウントはプライマリアカウントの価格を継承します。

プリペイド・プライマリー・アカウント

トップアップ後、プリペイド・アカウントはプラスの残高を受け取り、後にAPI使用で差し引かれる。残高がゼロになると、プリペイド・アカウントはそれ以上APIコールができなくなる（再度トップアップするまで）。残高全体をサブアカウントに分配したプリペイド・プライマリー・アカウントはAPIコールができなくなるが、残高がプラスのサブアカウントはAPIコールができる：

• について total_balance Subaccounts API によって返されるフィールドは、プライマリアカウントによって行われた最初の上乗せから、すべてのサブアカウントとプライマリアカウントにわたって残っている残高を表します。
• について balance Subaccounts API が返すフィールドは、プライマリアカウントとサブアカウントを含む各個別アカウントの残金額を示します。

後払いプライマリー・アカウント

後払いのプライマリアカウントは、そのすべてのサブアカウントの支出とそれ自身の支出（プライマリAPIキーから）に責任があります。Vonageに支払うべき金額の合計をキャプチャする値は、負の値です。 total_balance (ポジティブ total_balance つまり、Vonage には何も支払う義務はありません)。月末になると、Vonageは後払いのプライマリアカウントに、その月のすべてのAPIキー（アカウント）の使用量を請求する。理論的には、請求書の合計金額は total_balance すべてのアカウント（すべての使用量と支払額）。

例先ほどの例では、サブアカウント1の残高は20、サブアカウント2の残高は0、プライマリアカウントの残高は-40でした。プリペイド主勘定とその Subaccounts の合計残高は次のとおりです： total_balance = -40 + 20 + 0 = -20.

ベストプラクティス

• Vonage パートナーは Vonage API プライマリ・アカウントを所有・管理し、エンド・カスタマ用の Subaccount を作成する必要があります。
• パートナーは、API 呼び出しを実行するためにプライマリ API キー（アカウント）を使用しないでください。パートナー自身が Vonage API を使用したい場合、パートナーは別の Subaccounts を作成する必要があります。
• エンド・カスタマがクレジット・リミットに達しそうになると、パートナーはエンド・カスタマに追加のクレジット・リミットを割り当てるか、エンド・カスタマの残高を増やす前にエンド・カスタマが支払うのを待つべきである。
• パートナーは、エンドカスタマーが同等の金額をパートナーに支払わない限り、いかなる残高もエンドカスタマーのSubaccountsに移転すべきではない。
• 最終顧客の支払い方法を選択するのはパートナー次第である。すなわち、与信限度額が割り当てられた後払いの最終顧客か、与信限度額はゼロだが事前に残高が割り当てられた前払いの最終顧客かである。

参考

• コード・スニペット
• APIリファレンス