Aperçu de l'API Subaccounts (Beta)

IMPORTANT : L'API Subaccounts est disponible avec disponibilité restreinte.

Introduction

L'API Subaccounts vous permet de créer et de gérer de manière programmatique des sous-comptes pour des unités commerciales distinctes, des cas d'utilisation, des étapes de produit ou des clients distincts. L'API donne aux développeurs les moyens de gérer divers aspects de la logistique des sous-comptes : gérer le crédit, suivre l'utilisation, définir des limites d'utilisation, suspendre les sous-comptes, etc.

La figure ci-dessous illustre la relation entre le compte principal et les sous-comptes créés par l'API Subaccounts :

Bêta

Cette API est actuellement en version bêta.

Vonage est toujours heureux de recevoir vos commentaires. Vos suggestions nous aident à améliorer le produit. Si vous avez besoin d'aide, veuillez envoyer un courriel à soutien et mentionnez l'API Subaccounts dans la ligne d'objet.

Pendant la phase bêta, Vonage élargira les capacités de l'API.

Provisionnement

L'API Subaccounts est disponible avec disponibilité restreinte. Pour obtenir l'accès à l'API Subaccounts, veuillez contacter votre gestionnaire de compte. Partenaires Vonage obtenir l'accès automatiquement.

Caractéristiques prises en charge

Dans cette version, les fonctionnalités suivantes sont prises en charge :

Créer un nouveau Subaccounts
Attribuer un solde individuel ou partagé au Subaccounts
Transfert de crédit (fourni par Vonage) du compte principal vers le sous-compte et vice versa.
Transfert du solde du compte principal vers le sous-compte et vice-versa
Liste de tous les soldes et crédits des Subaccounts
Afficher le crédit total et le solde total de tous les Subaccounts
Suspendre/réactiver le Subaccounts

Concepts

Solde et crédit du compte

Tous les comptes API de Vonage ont un solde de compte associé. Il indique le montant des fonds disponibles pour les dépenses. Le solde du compte est déduit chaque fois qu'un appel API payant est effectué. Lorsque le solde du compte atteint zéro, les appels API payants ne peuvent pas être exécutés, sauf si le compte dispose d'une facilité de crédit fournie par Vonage. Si un Account dispose d'une facilité de crédit, le solde du compte peut descendre en dessous de zéro. Un compte postpayé est un compte qui dispose d'une facilité de crédit, un compte prépayé est un compte sans facilité de crédit.

Le montant du crédit disponible pour le client est appelé credit_limit. Ainsi, tout compte postpayé qui présente un solde positif a account_balance + |credit_limit| les fonds disponibles pour les dépenses. Un compte prépayé ne dispose que de account_balance disponibles pour les dépenses.

Création de Subaccounts

Par défaut, un sous-compte nouvellement créé partage son solde avec le compte principal, c'est-à-dire que tous les frais résultant de l'activité du sous-compte sont appliqués directement au solde du compte principal.

Pour créer un sous-compte avec son propre solde (tous les frais résultant de l'activité du sous-compte sont appliqués directement au solde du sous-compte), vous devez définir le paramètre use_primary_account_balance à FALSE. Ce changement est irréversible. Le sous-compte avec un solde propre ne peut pas être reconverti ultérieurement en sous-compte avec un solde partagé.

Sous-comptes postpayés et prépayés

Les Subaccounts dont le solde est individuel peuvent être prépayés ou postpayés. Les Subaccounts qui partagent un solde avec le compte principal ne peuvent pas être prépayés/postpayés car le solde partagé appartient au compte principal.

Type de compte primaire	Subaccounts postpayés	Subaccounts prépayés	Subaccounts avec solde partagé
Compte primaire postpayé
Compte primaire prépayé

Clé :

= pris en charge.
= Non pris en charge.

Si un Account primaire est prépayé, les Subaccounts créés sont également prépayés. Si le compte primaire est post-payé, les sous-comptes créés peuvent être soit post-payés, soit prépayés.

Un sous-compte (avec solde individuel) ne devient postpayé que si le sous-compte primaire postpayé affecte une partie de son crédit au sous-compte (le montant du crédit est nul pour le sous-compte prépayé). Par conséquent, les comptes primaires prépayés qui n'ont pas de crédit ne peuvent pas avoir de sous-comptes postpayés.

Fonctionnalité	Subaccounts postpayés	Sous-compte prépayé	Subaccounts avec solde partagé
Solde individuel			s/o
Crédit individuel		0	s/o

Clé :

= pris en charge.
n/a = Non applicable.

Transfert de solde

Un Subaccounts nouvellement créé avec un solde partagé peut effectuer des appels API directement, en supposant que le solde ou le crédit du compte principal correspondant (fourni par Vonage) ne soit pas nul. Un sous-compte nouvellement créé avec un solde individuel a initialement un solde nul et ne peut donc pas effectuer d'appels API. Il faut transférer un certain montant du compte principal vers le sous-compte.

RÈGLE : Solde_disponible_pour_transfert = |solde_du_compte - limite_de_crédit|

Cela signifie que le compte principal peut transférer des fonds au sous-compte, et que ces fonds peuvent provenir soit de son solde (en supposant qu'il soit positif), soit du crédit fourni par Vonage. Il est également possible de transférer le solde du sous-compte vers le compte principal, mais le transfert direct du solde entre les sous-comptes n'est pas pris en charge.

Exemple : Un compte primaire postpayé qui avait initialement un solde nul et à qui Vonage a donné 100 € de crédit a déjà utilisé 20 € du crédit fourni, c'est-à-dire que son solde est de 20 €. Il lui restait 80 € = |-20 - -100| qu'il pouvait soit dépenser lui-même, soit transférer à l'un de ses Subaccounts. Le compte primaire postpayé a décidé de transférer 20 € au sous-compte 1. Le solde du compte primaire est passé à 40 € après cette opération.

Allocation de crédit

Un compte principal est considéré comme postpayé s'il dispose d'une facilité de crédit fournie par Vonage. Le compte primaire postpayé peut allouer une partie de sa facilité de crédit à l'un de ses sous-comptes. Ainsi, il est possible d'avoir un sous-compte avec un solde nul mais un crédit non nul. Ce sous-compte pourra effectuer des appels API jusqu'à ce que le crédit alloué soit épuisé. En général, tout Account dont le solde est positif dispose de account_balance + |credit_limit| les fonds disponibles pour les dépenses.

Cela signifie que le compte primaire peut allouer une partie ou la totalité de sa facilité de crédit qui n'a pas déjà été dépensée ou allouée au sous-compte, et vice versa (le crédit qui n'a pas été utilisé par le sous-compte peut être restitué au compte primaire).

Exemple : Après avoir dépensé 20 € et transféré 20 € supplémentaires sur le sous-compte1, le solde du compte primaire postpayé est tombé à 40 €, et il a décidé d'affecter le solde individuel au sous-compte2 et de lui allouer 35 € de son crédit restant. Le compte primaire disposait de |-100| - |-40| = 60 € de crédit disponible pour l'affectation. Après l'opération d'affectation du crédit, le crédit restant du compte primaire est devenu 65 € : |limite_de_crédit| = |-100| - 35 = 65 €.

Frais et contrôle des dépenses

Vonage facture l'utilisation réelle de l'API Vonage, mais la façon dont elle est saisie et appliquée diffère pour les comptes prépayés et postpayés. Les Subaccounts héritent des prix du compte principal.

Compte primaire prépayé

Après avoir été rechargés, les comptes prépayés reçoivent un solde positif qui est déduit ultérieurement en fonction de l'utilisation de l'API. Lorsque le solde est nul, le compte prépayé ne peut plus effectuer d'appels à l'API (jusqu'à ce qu'il soit à nouveau rechargé). Un compte principal prépayé qui a réparti la totalité de son solde entre ses sous-comptes ne pourra pas effectuer d'appels d'API, mais ses sous-comptes ayant un solde positif pourront toujours effectuer des appels d'API :

Les total_balance renvoyé par l'API Subaccounts représente le montant du solde restant sur tous les sous-comptes et le compte principal à la suite de la recharge initiale effectuée par le compte principal.
Les balance renvoyé par l'API Subaccounts indique le montant du solde restant pour chaque compte individuel, y compris le compte principal et les sous-comptes.

Compte primaire postpayé

Un compte primaire postpayé est responsable des dépenses de tous ses Subaccounts et de ses propres dépenses (à partir de la clé API primaire). La valeur qui saisit le montant total dû à Vonage est la valeur négative de total_balance (positif total_balance signifie que rien n'est dû à Vonage). À la fin du mois, Vonage facture un compte primaire postpayé pour toute l'utilisation de toutes ses clés API (comptes) au cours de ce mois. En théorie, le montant total de la facture devrait être égal à la somme de total_balance sur l'ensemble des Account (toutes les utilisations et tous les paiements effectués).

Exemple : Dans l'exemple précédent, le solde du sous-compte 1 était de 20, le solde du sous-compte 2 était de 0 et le solde du compte primaire était de -40. Le solde total du compte primaire prépayé et de ses sous-comptes est de : total_balance = -40 + 20 + 0 = -20.

Meilleures pratiques

Un partenaire de Vonage doit posséder et gérer un compte principal API de Vonage et doit créer des Subaccounts pour ses clients finaux.
Le partenaire ne doit pas utiliser sa clé API principale (Account) pour effectuer des appels API. Si le partenaire souhaite utiliser lui-même l'API de Vonage, il doit créer un autre Subaccounts.
Lorsqu'un client final est sur le point d'atteindre sa limite de crédit, le partenaire doit soit allouer une limite de crédit supplémentaire au client final, soit attendre que le client final paie avant d'augmenter son solde, sinon les appels API du client final seront temporairement bloqués.
Le partenaire ne doit pas transférer de solde sur le Subaccounts du client final à moins que ce dernier n'ait versé au partenaire une somme d'argent équivalente.
Il appartient aux partenaires de choisir le mode de paiement pour leurs clients finaux : clients postpayés avec une limite de crédit allouée ou clients prépayés avec une limite de crédit nulle mais avec un solde pré-alloué.