Descripción general de la API de Subaccounts (Beta)

IMPORTANTE: La API de Subaccounts se publica con disponibilidad restringida.

Introducción

La API de Subaccounts permite crear y gestionar mediante programación subcuentas para unidades de negocio, casos de uso, fases de productos o clientes independientes. La API permite a los desarrolladores gestionar diversos aspectos de la logística de las subcuentas: gestión del crédito, seguimiento del uso, establecimiento de límites de uso, suspensión de subcuentas, etc.

La siguiente figura ilustra la relación entre la cuenta principal y las subcuentas creadas por la API Subaccounts:

Beta

Esta API se encuentra actualmente en fase Beta.

Vonage siempre agradece tus comentarios. Tus sugerencias nos ayudan a mejorar el producto. Si necesitas ayuda, envía un email a soporte e incluya la API de Subaccounts en el asunto.

Durante la versión beta, Vonage ampliará las capacidades de la API.

Aprovisionamiento

La API de Subaccounts se publica con disponibilidad restringida. Para acceder a la API de Subaccounts, póngase en contacto con su gestor de Account. Socios de Vonage acceder automáticamente.

Funciones compatibles

En esta versión se admiten las siguientes funciones:

Crear una nueva subcuenta
Asignar saldo individual o compartido a la subcuenta
Transferir crédito (proporcionado por Vonage) de la cuenta principal a la subcuenta y viceversa
Transferir saldo de la cuenta principal a la subcuenta y viceversa
Lista de todos los saldos y créditos de las subaccounts
Mostrar el crédito total y el saldo total de todas las subcuentas
Suspender/reactivar la subcuenta

Concepts

Account balance and credit

Todas las cuentas API de Vonage tienen un saldo de cuenta asociado. Muestra la cantidad de fondos disponibles para gastar. El saldo de cuenta se deduce cada vez que se realiza una llamada de API con cargo. Cuando el saldo de la Account llega a cero, las llamadas a la API con cargo no pueden ejecutarse a menos que la cuenta tenga una línea de crédito provista por Vonage. Si una cuenta tiene una línea de crédito, el saldo de la cuenta puede ser inferior a cero. Una Account pospaga es una cuenta que tiene una línea de crédito, una cuenta prepaga es una cuenta sin línea de crédito.

El importe del crédito disponible para el cliente se denomina credit_limit. Por lo tanto, cualquier cuenta de pospago que tenga un saldo positivo tiene account_balance + |credit_limit| fondos disponibles para gastar. Una Account de prepago sólo tiene account_balance disponible para gastar.

Creación de Subaccounts

Por defecto, una subcuenta recién creada comparte su saldo con la cuenta principal, es decir, cualquier cargo resultante de la actividad de la subcuenta se aplica directamente al saldo de la cuenta principal.

Para crear una subcuenta con su propio saldo (todos los cargos derivados de la actividad de la subcuenta se aplican directamente al saldo de la subcuenta), debe establecer el parámetro use_primary_account_balance a FALSE. Este cambio es irreversible. La subcuenta con saldo propio no puede volver a convertirse posteriormente en la subcuenta con saldo compartido.

Subaccounts de postpago y prepago

Las Subaccounts con saldo individual pueden ser de prepago o de postpago. Subaccounts that share balance with the primary account cannot be prepaid/postpaid because the shared balance belongs to the primary account.

Tipo de cuenta principal	Subaccounts postpago	Subaccounts prepagées	Subaccounts con saldo compartido
Cuenta principal de pospago
Cuenta principal de prepago

Llave:

= Compatible.
= No compatible.

Si la cuenta principal es de prepago, las subcuentas creadas también serán de prepago. Si la cuenta principal es de pospago, las subcuentas creadas pueden ser de pospago o de prepago.

Una subcuenta (con saldo individual) pasa a ser de pospago sólo si la subcuenta de pospago principal asigna parte de su crédito a la subcuenta (el importe del crédito es cero para la subcuenta de prepago). Por lo tanto, las cuentas primarias de prepago que no tienen crédito no pueden tener subcuentas de postpago.

Característica	Subcuenta de pospago	Subcuenta de prepago	Subaccounts con saldo compartido
Saldo individual			n/a
Crédito individual		0	n/a

Llave:

= Compatible.
n/a = No aplicable.

Transferencia de saldo

Una subcuenta recién creada con saldo compartido puede realizar llamadas a la API directamente, siempre que el saldo o crédito de la cuenta principal correspondiente (provisto por Vonage) sea distinto de cero. Una subcuenta recién creada con saldo individual inicialmente tiene saldo cero y, por lo tanto, no puede realizar llamadas a la API. Es necesario transferir algún monto de la cuenta principal a la subcuenta.

REGLA: Saldo_disponible_para_transferencia = |saldo_cuenta - límite_crédito|

Significa que la cuenta principal puede transferir fondos a la subcuenta, y estos fondos pueden provenir de su saldo (suponiendo que sea positivo) o del crédito provisto por Vonage. También es posible transferir saldo de la subcuenta de vuelta a la cuenta principal, pero no se admite la transferencia directa de saldo entre subcuentas.

Ejemplo: Una Account principal de pospago que inicialmente tenía un saldo cero y a la que Vonage otorgó 100 euros en crédito ya utilizó 20 euros del crédito otorgado, es decir, su saldo era de 20 euros. Aún le quedaban 80 euros = |-20 - -100| que podía gastar ella misma o transferir a una de sus subcuentas. La cuenta principal de pospago decidió transferir 20 euros a la subcuenta 1. El saldo de la cuenta principal pasó a ser de 40 euros tras esta operación.

Asignación de créditos

Una cuenta principal se considera pospaga si tiene una línea de crédito provista por Vonage. La cuenta principal pospaga puede asignar una parte de su servicio de crédito a una de sus subcuentas. Por lo tanto, es posible tener una subcuenta con saldo cero pero crédito distinto de cero. Esta subcuenta podrá realizar llamadas a la API hasta que se agote el crédito asignado. En general, cualquier Account con saldo positivo tiene account_balance + |credit_limit| fondos disponibles para gastar.

Significa que la cuenta principal puede asignar a la subcuenta una parte o la totalidad de su crédito que no se haya gastado o asignado ya, y viceversa (el crédito no utilizado por la subcuenta puede devolverse a la cuenta principal).

Ejemplo: Tras gastar 20 euros y transferir otros 20 euros a la subcuenta1, el saldo de la cuenta principal de pospago descendió a 40 euros, por lo que decidió asignar el saldo individual a la subcuenta2 y asignarle 35 euros de su crédito restante. La cuenta primaria tenía |-100| - |-40| = 60 euros de crédito disponible para asignar. Tras la operación de asignación de crédito, la línea de crédito restante de la cuenta primaria pasó a ser de 65 euros: |Límite_crédito = 100 - 35 = 65 euros.

Cargos y control del gasto

Vonage cobra por el uso real de la API de Vonage, pero la manera en que se captura y aplica difiere para las cuentas prepagadas y pospagadas. Las Subaccounts heredan los precios de la cuenta principal.

Cuenta principal de prepago

Tras la recarga, las cuentas de prepago reciben un saldo positivo que se deduce posteriormente con el uso de la API. Cuando se alcanza el saldo cero, la cuenta de prepago no puede realizar más llamadas a la API (hasta otra recarga). Una cuenta principal de prepago que distribuyera todo su saldo entre sus subcuentas no podría realizar llamadas a la API, pero sus subcuentas con saldo positivo sí podrían realizarlas:

En total_balance devuelto por la API de Subaccounts representa la cantidad de saldo que queda entre todas las subcuentas y la cuenta principal desde la recarga inicial realizada por la cuenta principal.
En balance devuelto por la API de Subaccounts muestra la cantidad de saldo restante para cada cuenta individual, incluyendo la cuenta principal y las subcuentas.

Cuenta principal de pospago

Una cuenta principal pospaga es responsable de los gastos de todas sus subcuentas y de sus propios gastos (de la clave API principal). El valor que captura el monto total adeudado a Vonage es el negativo total_balance (positivo total_balance significa que no se le debe nada a Vonage). A fin de mes, Vonage factura a una cuenta principal de pospago por todo el uso de todas sus claves API (cuentas) en ese mes. En teoría, el monto total de la factura sería igual al total_balance en todas las cuentas (todo el uso más los pagos realizados).

Ejemplo: En el ejemplo anterior, el saldo de la subcuenta1 era de 20, el de la subcuenta2 era de 0 y el de la cuenta principal era de -40. El saldo total de la cuenta principal prepagada y sus Subaccounts es: total_balance = -40 + 20 + 0 = -20.

Buenas prácticas

Un socio de Vonage debe poseer y administrar una cuenta principal de API de Vonage y debe crear subcuentas para sus clientes finales.
El socio no debe usar su clave de API principal (Account) para realizar llamadas a la API. Si el socio desea usar la API de Vonage por sí mismo, deberá crear otra subcuenta.
Cuando un cliente final está a punto de alcanzar su límite de crédito, el Partner debe asignar un límite de crédito adicional al cliente final o esperar a que el cliente final pague antes de aumentar el saldo del cliente final; de lo contrario, las llamadas a la API del cliente final se bloquearán temporalmente.
El socio no debe transferir ningún saldo a la subcuenta del cliente final a menos que el cliente final haya pagado la cantidad equivalente de dinero al socio.
Corresponde a los socios elegir el modo de pago para sus clientes finales: clientes finales de pospago con límite de crédito asignado o clientes finales de prepago con límite de crédito cero pero con saldo preasignado.