Übersicht der Subaccounts API (Beta)

Einführung

Mit der Subaccounts-API können Sie programmgesteuert Unterkonten für separate Geschäftseinheiten, Anwendungsfälle, Produktphasen oder separate Kunden erstellen und verwalten. Die API ermöglicht es Entwicklern, verschiedene Aspekte der Subaccount-Logistik zu handhaben: Guthaben verwalten, Nutzung nachverfolgen, Nutzungsgrenzen festlegen, Subaccounts sperren und so weiter.

Die folgende Abbildung veranschaulicht die Beziehung zwischen dem primären Konto und den von der Subaccounts-API erstellten Unterkonten:

Beta

Diese API befindet sich derzeit im Beta-Stadium.

Vonage freut sich immer über Ihr Feedback. Ihre Vorschläge helfen uns, das Produkt zu verbessern. Wenn Sie Hilfe benötigen, senden Sie bitte eine E-Mail an Unterstützung und geben Sie die Subaccounts API in der Betreffzeile an.

Während der Beta-Phase wird Vonage die Möglichkeiten der API erweitern.

Bereitstellung

Subaccounts API ist freigegeben mit eingeschränkte Verfügbarkeit. Um Zugang zur Subaccounts API zu erhalten, wenden Sie sich bitte an Ihren Account Manager. Vonage-Partner automatisch Zugang erhalten.

Unterstützte Funktionen

In dieser Version werden die folgenden Funktionen unterstützt:

• Ein neues Subaccount anlegen
• Einzelnen oder gemeinsamen Saldo dem Unterkonto zuordnen
• Überweisung von Guthaben (von Vonage zur Verfügung gestellt) vom primären Account auf den Sub-Account und umgekehrt
• Übertragung des Saldos vom Hauptkonto auf das Unterkonto und umgekehrt
• Auflistung aller Subaccountsalden und -guthaben
• Gesamtguthaben und Gesamtsaldo für alle Subaccounts anzeigen
• Das Unterkonto aussetzen/reaktivieren

Concepts

Kontostand und Guthaben

Alle Vonage API-Konten verfügen über einen entsprechenden Kontostand. Er zeigt den Betrag an, der für Ausgaben zur Verfügung steht. Der Kontostand wird jedes Mal abgezogen, wenn ein kostenpflichtiger API-Aufruf getätigt wird. Wenn der Kontostand Null erreicht, können keine kostenpflichtigen API-Aufrufe ausgeführt werden, es sei denn, das Konto verfügt über eine von Vonage bereitgestellte Kreditlinie. Wenn ein Account über einen Kreditrahmen verfügt, kann der Kontostand unter Null sinken. Ein Postpaid-Konto ist ein Konto mit einem Guthaben, ein Prepaid-Konto ist ein Konto ohne Guthaben.

Der dem Kunden zur Verfügung stehende Kreditbetrag wird als credit_limit. Jedes Postpaid-Konto, das einen positiven Saldo aufweist, hat also account_balance + |credit_limit| Mittel, die für Ausgaben zur Verfügung stehen. Ein Prepaid Account hat nur account_balance für Ausgaben zur Verfügung.

Einrichtung eines Subaccounts

Standardmäßig teilt ein neu angelegtes Unterkonto seinen Saldo mit dem Hauptkonto, d. h. alle Gebühren, die sich aus den Aktivitäten des Unterkontos ergeben, werden direkt dem Saldo des Hauptkontos zugerechnet.

Um ein Unterkonto mit eigenem Saldo einzurichten (alle Gebühren, die sich aus den Aktivitäten des Unterkontos ergeben, werden direkt dem Saldo des Unterkontos belastet), müssen Sie den Parameter use_primary_account_balance zu FALSE. Diese Änderung ist unumkehrbar. Das Unterkonto mit eigenem Saldo kann nicht zu einem späteren Zeitpunkt wieder in das Unterkonto mit gemeinsamem Saldo umgewandelt werden.

Postpaid- und Prepaid-Subaccounts

Subaccounts mit individuellem Saldo können entweder vorausbezahlt oder nachbezahlt werden. Subaccounts, die ein gemeinsames Guthaben mit dem Hauptkonto haben, können nicht vorausbezahlt/nachbezahlt werden, da das gemeinsame Guthaben zum Hauptkonto gehört.

Schlüssel:

• = Unterstützt.
• = Nicht unterstützt.

Wenn ein primäres Konto vorausbezahlt ist, dann sind die erstellten Subaccounts ebenfalls vorausbezahlt. Ist das primäre Konto postpaid, können die erstellten Subaccounts entweder postpaid oder prepaid sein.

Ein Unterkonto (mit individuellem Saldo) wird nur dann zu einem Postpaid-Konto, wenn das primäre Postpaid-Unterkonto einen Teil seines Guthabens dem Unterkonto zuweist (der Guthabenbetrag ist für das Prepaid-Unterkonto gleich Null). Daher können vorausbezahlte primäre Konten, die kein Guthaben haben, keine nachbezahlten Subaccounts haben.

Schlüssel:

• = Unterstützt.
• n/a = Nicht zutreffend.

Überweisung

Ein neu erstellter Subaccount mit gemeinsamem Guthaben kann direkt API-Aufrufe durchführen, vorausgesetzt, der Saldo oder das Guthaben des entsprechenden primären Accounts (von Vonage bereitgestellt) ist ungleich Null. Ein neu erstellter Subaccount mit individuellem Guthaben hat zunächst einen Nullsaldo und kann daher keine API-Aufrufe tätigen. Man muss einen Betrag vom Hauptkonto auf das Unterkonto überweisen.

Das bedeutet, dass das Hauptkonto Geld auf das Unterkonto überweisen kann, und zwar entweder aus seinem Guthaben (vorausgesetzt, es ist positiv) oder aus dem von Vonage bereitgestellten Guthaben. Es ist auch möglich, Guthaben vom Subaccount zurück auf das Hauptkonto zu übertragen, aber eine direkte Übertragung von Guthaben zwischen Subaccounts wird nicht unterstützt.

Beispiel: Ein Postpaid-Primärkonto, das ursprünglich einen Nullsaldo hatte und von Vonage ein Guthaben von 100 € erhielt, hat bereits 20 € des bereitgestellten Guthabens verbraucht, d. h. sein Guthaben beträgt 20 €. Es hatte noch 80 € = |-20 - -100|, die es entweder selbst ausgeben oder auf eines seiner Subaccounts übertragen konnte. Das Postpaid-Hauptkonto beschloss, 20 € auf das Unterkonto1 zu übertragen. Der Saldo des Hauptkontos beträgt nun 40 €.

Kreditvergabe

Ein primärer Account gilt als postpaid, wenn er über einen von Vonage zur Verfügung gestellten Kreditrahmen verfügt. Das Postpaid-Primärkonto kann einen Teil seines Kreditrahmens einem seiner Subaccounts zuweisen. So ist es möglich, ein Unterkonto mit einem Nullsaldo, aber einem Guthaben, das nicht Null ist, zu haben. Dieses Unterkonto kann API-Aufrufe tätigen, bis das zugewiesene Guthaben aufgebraucht ist. Im Allgemeinen hat jedes Konto mit einem positiven Saldo account_balance + |credit_limit| Mittel, die für Ausgaben zur Verfügung stehen.

Das bedeutet, dass das Hauptkonto einen Teil oder die Gesamtheit seines Kreditrahmens, der noch nicht ausgegeben oder zugewiesen wurde, dem Unterkonto zuweisen kann und umgekehrt (Guthaben, das vom Unterkonto nicht verwendet wurde, kann an das Hauptkonto zurückgegeben werden).

Beispiel: Nachdem das Postpaid-Hauptkonto 20 € ausgegeben und weitere 20 € auf das Unterkonto1 überwiesen hatte, sank sein Guthaben auf 40 €, und es beschloss, das individuelle Guthaben dem Unterkonto2 zuzuweisen und ihm 35 € aus seinem verbleibenden Guthaben zukommen zu lassen. Das Hauptkonto verfügte über |-100| - |-40| = 60 € Guthaben, das zugewiesen werden konnte. Nach der Zuteilung beträgt der verbleibende Kreditrahmen des Hauptkontos 65 €: |Kreditlimit| = |-100| - 35 = 65 €.

Anlastung und Überwachung der Ausgaben

Vonage berechnet die tatsächliche Nutzung der Vonage API, aber die Art und Weise, wie sie erfasst und angewendet wird, unterscheidet sich für Prepaid- und Postpaid-Accounts. Subaccounts erben die Preise des Hauptaccounts.

Vorausbezahltes Hauptkonto

Nach dem Aufladen erhalten Prepaid-Accounts ein positives Guthaben, das später mit der API-Nutzung abgezogen wird. Wenn das Guthaben Null ist, kann das Prepaid-Konto keine API-Aufrufe mehr tätigen (bis zur nächsten Aufladung). Ein Prepaid-Hauptkonto, das sein gesamtes Guthaben auf seine Subaccounts verteilt hat, kann keine API-Aufrufe tätigen, aber seine Subaccounts mit positivem Guthaben können weiterhin API-Aufrufe tätigen:

• Die total_balance Das von der Subaccounts-API zurückgegebene Feld "Guthaben" gibt den Betrag an, der nach der ersten Aufladung des Hauptkontos auf allen Unterkonten und dem Hauptkonto verbleibt.
• Die balance das von der Subaccounts API zurückgegeben wird, zeigt den verbleibenden Saldo für jedes einzelne Konto, einschließlich des Hauptkontos und der Unterkonten.

Postpaid primäres Konto

Ein primäres Postpaid-Konto ist für die Ausgaben aller seiner Subaccounts und für seine eigenen Ausgaben (aus dem primären API-Schlüssel) verantwortlich. Der Wert, der den an Vonage geschuldeten Gesamtbetrag erfasst, ist der negative total_balance (positiv total_balance bedeutet, dass Vonage nichts geschuldet wird). Am Ende des Monats stellt Vonage einem Postpaid-Primärkonto die gesamte Nutzung aller API-Schlüssel (Accounts) in diesem Monat in Rechnung. Theoretisch würde der gesamte Rechnungsbetrag dem total_balance über alle Accounts (gesamte Nutzung plus getätigte Zahlungen).

Beispiel: Im vorherigen Beispiel betrug der Saldo von Unterkonto1 20, der von Unterkonto2 0 und der des Hauptkontos -40. Der Gesamtsaldo des vorausbezahlten Hauptkontos und seiner Subaccounts beträgt: total_balance = -40 + 20 + 0 = -20.

Bewährte Praktiken

• Ein Vonage Partner sollte einen primären Vonage API Account besitzen und verwalten und Subaccounts für seine Endkunden anlegen.
• Der Partner sollte nicht seinen primären API-Schlüssel (Account) verwenden, um API-Aufrufe durchzuführen. Wenn der Partner die Vonage-API selbst nutzen möchte, sollte er ein anderes Unterkonto erstellen.
• Wenn ein Endkunde kurz davor ist, sein Kreditlimit zu erreichen, sollte der Partner dem Endkunden entweder ein zusätzliches Kreditlimit zuweisen oder warten, bis der Endkunde zahlt, bevor er das Guthaben des Endkunden erhöht.
• Der Partner sollte kein Guthaben auf das Unterkonto des Endkunden überweisen, solange der Endkunde nicht den entsprechenden Geldbetrag an den Partner gezahlt hat.
• Die Partner können die Zahlungsart für ihre Endkunden wählen: Postpaid-Endkunden mit zugewiesenem Kreditlimit oder Prepaid-Endkunden ohne Kreditlimit, aber mit vorab zugewiesenem Guthaben.

Referenz

• Code-Schnipsel
• API-Referenz