Visão geral da API de Subaccounts (Beta)

Introdução

A API de Subaccounts permite criar e gerenciar, por meio de programação, subcontas para unidades de negócios distintas, casos de uso, estágios de produtos ou clientes específicos. A API permite que os desenvolvedores lidem com diversos aspectos da logística das subcontas: gerenciar crédito, acompanhar o uso, definir limites de uso, suspender subcontas e assim por diante.

A figura abaixo ilustra a relação entre a conta principal e as subcontas criadas pela API de Subaccounts:

Beta

Atualmente, essa API está em fase beta.

A Vonage sempre agradece seus comentários. Suas sugestões nos ajudam a melhorar o produto. Caso precise de ajuda, envie um e-mail para apoio e inclua “API de Subaccounts” na linha de assunto.

Durante a fase beta, a Vonage ampliará os recursos da API.

Provisionamento

A API de Subaccounts foi lançada com disponibilidade limitada. Para ter acesso à API de Subaccounts, entre em contato com seu gerente de contas. Parceiros da Vonage obter acesso automaticamente.

Recursos compatíveis

Nesta versão, os seguintes recursos são suportados:

• Criar uma nova subconta
• Atribuir saldo individual ou compartilhado à subconta
• Transferência de crédito (oferecida pela Vonage) da conta principal para a subconta e vice-versa
• Transferir o saldo da conta principal para a subconta e vice-versa
• Listar todos os saldos e créditos das subaccounts
• Mostrar o crédito total e o saldo total em todas as Subaccounts
• Suspender/reativar un subconta

Concepts

Saldo da conta e crédito

Todas as contas da API da Vonage possuem um saldo associado. Ele indica o valor disponível para gastos. O saldo da conta é deduzido sempre que é feita uma chamada de API cobrável. Quando o saldo da conta chega a zero, não é possível realizar chamadas de API cobráveis, a menos que a conta disponha de uma linha de crédito fornecida pela Vonage. Se um account tiver uma linha de crédito, seu saldo poderá ficar negativo. Um account pós-paga é aquele que possui uma linha de crédito; um account pré-paga é aquele sem linha de crédito.

O valor do crédito disponível para o cliente é chamado de credit_limit. Assim, qualquer account pós-paga que tenha saldo positivo possui account_balance + |credit_limit| recursos disponíveis para gastos. Uma conta pré-paga tem apenas account_balance disponível para gastos.

Criação de subconta

Por padrão, uma subconta recém-criada compartilha seu saldo com a conta principal; ou seja, quaisquer cobranças decorrentes das transações da subconta são aplicadas diretamente ao saldo da conta principal.

Para criar uma subconta com saldo próprio (todas as cobranças decorrentes da atividade da subconta são aplicadas diretamente ao saldo da subconta), é necessário definir o parâmetro use_primary_account_balance para FALSE. Essa alteração é irreversível. A subconta com saldo próprio não pode, posteriormente, ser revertida para a subconta com saldo compartilhado.

Subaccounts pós-pagas e pré-pagas

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

Legenda:

• = Compatível.
• = Não é compatível.

Se um account principal for pré-pago, os subaccounts criados também serão pré-pagos. Se o account principal for pós-pago, os subaccounts criados podem ser pós-pagos ou pré-pagos.

A subaccount (com saldo individual) passa a ser pós-paga somente se a subconta principal pós-paga transferir parte de seu crédito para essa subconta (o valor do crédito é zero para a subconta pré-paga). Portanto, contas principais pré-pagas que não possuam crédito não podem ter subaccounts pós-pagas.

Legenda:

• = Compatível.
• n/a = Não se aplica.

Transferência de saldo

A subaccount recém-criada com saldo compartilhado pode realizar chamadas de API diretamente, desde que o saldo ou crédito da conta principal correspondente (fornecido pela Vonage) seja diferente de zero. Uma subaccount recém-criada com saldo individual apresenta, inicialmente, saldo zero e, portanto, não pode realizar chamadas de API. É necessário transferir algum valor da conta principal para a subaccount.

Isso significa que a conta principal pode transferir fundos para a subconta, e esses fundos podem provir tanto do seu saldo (desde que seja positivo) quanto do crédito fornecido pela Vonage. Também é possível transferir o saldo da subconta de volta para a conta principal, mas a transferência direta de saldo entre subaccounts não é permitida.

Exemplo: Um account principal pós-paga que inicialmente tinha saldo zero e recebeu €100 em crédito da Vonage já havia utilizado €20 do crédito fornecido, ou seja, seu saldo era de €-20. Ela ainda tinha 80 € = |-20 - -100| que poderia gastar ou transferir para uma de suas Subaccounts. A conta principal pós-paga decidiu transferir 20 € para a Subaccount 1. O saldo da conta principal passou a ser de -40 € após essa operação.

Alocação de crédito

Um account principal é considerado pós-paga se tiver uma linha de crédito concedida pela Vonage. A conta principal pós-paga pode alocar uma parte de sua linha de crédito a uma de suas subaccounts. Assim, é possível ter uma subaccount com saldo zero, mas com crédito diferente de zero. Essa subaccount poderá realizar chamadas de API até que o crédito alocado se esgote. Em geral, qualquer conta que tenha saldo positivo tem account_balance + |credit_limit| recursos disponíveis para gastos.

Isso significa que a conta principal pode alocar parte ou a totalidade de sua linha de crédito que ainda não tenha sido utilizada ou alocada à subconta, e vice-versa (o crédito que não foi utilizado pela subconta pode ser devolvido à conta principal).

Exemplo: Após gastar €20 e transferir outros €20 para a subconta1, o saldo da conta principal pós-paga caiu para €-40, e foi decidido atribuir um saldo individual à subconta2 e alocar €35 do crédito restante para ela. A conta principal tinha |-100| - |-40| = €60 em crédito disponível para alocação. Após a operação de alocação de crédito, a linha de crédito restante da conta principal passou a ser de €65: |limite_de_crédito| = |-100| - 35 = €65.

Despesas e acompanhamento dos gastos

A Vonage cobra pelo uso efetivo da API da Vonage, mas a forma como esse uso é registrado e cobrado difere entre contas pré-pagas e pós-pagas. Os Subaccounts herdam os preços da conta principal.

Conta principal pré-paga

Após a recarga, as contas pré-pagas recebem um saldo positivo que é deduzido posteriormente com o uso da API. Quando o saldo chega a zero, a conta pré-paga não pode mais realizar chamadas de API (até que seja feita outra recarga). A conta principal pré-paga que distribuiu todo o seu saldo entre suas Subaccounts não poderia realizar chamadas de API, mas suas Subaccounts com saldo positivo ainda poderiam realizar chamadas de API:

• O total_balance O campo retornado pela API de Subaccounts representa o saldo restante em todas as subcontas e na conta principal, a partir da recarga inicial realizada pela conta principal.
• O balance O campo retornado pela API de Subaccounts mostra o saldo restante de cada conta individual, incluindo a conta principal e as subcontas.

Conta principal pós-paga

Uma conta principal pós-paga é responsável pelos gastos de todas as suas Subaccounts e pelos seus próprios gastos (por meio da chave de API principal). O valor que representa o montante total devido à Vonage é o valor negativo total_balance (positivo total_balance significa que não há nenhum valor a pagar à Vonage). No final do mês, a Vonage fatura uma conta principal pós-paga por todo o uso em todas as suas chaves de API (contas) naquele mês. Em teoria, o valor total da fatura seria igual ao total_balance em todas as contas (todo o uso e os pagamentos efetuados).

Exemplo: No exemplo anterior, o saldo da subconta1 era 20, o saldo da subconta2 era 0 e o saldo da conta principal era -40. O saldo total da conta principal pré-paga e de suas subaccounts é: total_balance = -40 + 20 + 0 = -20.

Melhores práticas

• Um parceiro da Vonage deve possuir e gerenciar uma conta principal da API da Vonage e deve criar Subaccounts para seus clientes finais.
• O Parceiro não deve usar sua chave de API principal (Account) para realizar chamadas à API. Caso o Parceiro deseje utilizar a própria API da Vonage, ele deverá criar outra subconta.
• Quando um cliente final estiver prestes a atingir seu limite de crédito, o Parceiro deverá atribuir um limite de crédito adicional ao cliente final ou aguardar que ele efetue o pagamento antes de aumentar o saldo do cliente final; caso contrário, as chamadas de API do cliente final serão temporariamente bloqueadas.
• O Parceiro não deve transferir nenhum saldo para a subconta do cliente final, a menos que este tenha pago o valor equivalente ao Parceiro.
• Cabe aos parceiros escolher a forma de pagamento para seus clientes finais: clientes finais no sistema pós-pago com limite de crédito atribuído ou clientes finais no sistema pré-pago sem limite de crédito, mas com saldo pré-atribuído.

Referência

• Trechos de código
• Referência da API