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

IMPORTANTE: Se lanza la API de Subaccounts con disponibilidad limitada.

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 mediante la API de 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 fase beta, Vonage ampliará las funcionalidades de la API.

Aprovisionamiento

La API de Subaccounts se publica con disponibilidad limitada. Para acceder a la API de Subaccounts, ponte en contacto con tu gestor de cuentas. Socios de Vonage acceder automáticamente.

Funcionalidades 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 saldo acreedor total y el saldo total de todas las Subaccounts
Suspender/reactivar la subcuenta

Concepts

Account balance and credit

Todas las cuentas de la API de Vonage tienen un saldo asociado. Este saldo indica la cantidad de fondos disponibles para gastar. El saldo de la cuenta se deduce cada vez que se realiza una llamada a la API sujeta a cargo. Cuando el saldo de la cuenta llega a cero, no se pueden realizar llamadas a la API sujetas a cargo, a menos que la cuenta cuente con una línea de crédito proporcionada por Vonage. Si un account dispone de una línea de crédito, su saldo puede ser inferior a cero. Un account de pospago es aquel que dispone de una línea de crédito, mientras que un account de prepago es aquel que carece de ella.

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 disponibles 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 una subcuenta con saldo compartido.

Subaccounts of postpaid and prepaid services

The subaccounts with own balance can be prepaid or postpaid. The subaccounts that share balance with the main account cannot be prepaid or postpaid, as the shared balance belongs to the main account.

Tipo de cuenta principal	Subaccounts postpago	Subaccounts prepagées	Subaccounts with shared balance
Cuenta principal de pospago
Cuenta principal de prepago

Llave:

= Compatible.
= No es 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.

A subaccount (with individual balance) becomes postpaid only if the primary postpaid subaccount allocates part of its balance to the subaccount (the balance amount is zero in the case of prepaid subaccounts). Therefore, prepaid primary accounts that do not have balance cannot have postpaid subaccounts.

Característica	Subaccount de pospago	Subaccount of prepayment	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.

Gastos 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:

El 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.
El balance El campo devuelto por la API de Subaccounts muestra el saldo restante de cada cuenta individual, incluidas 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 final de mes, Vonage factura a una cuenta principal de pospago el consumo total de todas sus claves API (accounts) durante ese mes. En teoría, el importe total de la factura equivaldría al total_balance en todas las cuentas (todo el uso más los pagos realizados).

Ejemplo: En el ejemplo anterior, el saldo de la subcuenta 1 era de 20, el de la subcuenta 2 era de 0 y el de la cuenta principal era de -40. El saldo total de la cuenta principal de prepago 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 socio deberá asignarle un límite de crédito adicional o esperar a que el cliente final realice el pago antes de aumentar su saldo; de lo contrario, las llamadas a la API del cliente final quedarán bloqueadas temporalmente.
El socio no debe transferir ningún saldo a la subcuenta del cliente final a menos que este haya abonado al socio la cantidad equivalente.
Corresponde a los socios elegir la forma de pago para sus clientes finales: clientes finales de pospago con un límite de crédito asignado o clientes finales de prepago sin límite de crédito, pero con un saldo preasignado.