Como gerenciar saldos pré-pagos da conta

Esta página se aplica à Apigee e à Apigee híbrida.

Confira a documentação da Apigee Edge.

Nesta página, descrevemos como gerenciar contas de faturamento pré-pago.

Use as APIs Apigee para gerenciar as contas de faturamento pré-pago dos desenvolvedores. É possível realizar as seguintes tarefas usando as APIs:

Ver a configuração de monetização
Atualizar a configuração de monetização
Ver saldo do desenvolvedor
Creditar saldo do desenvolvedor
Ajustar o saldo do desenvolvedor

Ver a configuração de monetização

Para visualizar a configuração de monetização de um desenvolvedor, emita uma solicitação GET para a seguinte API:

https://apigee.googleapis.com/v1/organizations/$YOUR_GOOGLE_PROJECT_ID/developers/$DEVELOPER_EMAIL_ID/monetizationConfig

Com essa API, é possível visualizar o tipo de faturamento do desenvolvedor. Para mais informações sobre a API, veja getMonetizationConfig.

No exemplo a seguir, mostramos como visualizar a configuração de monetização para um desenvolvedor usando o comando curl:

curl -H "Authorization: Bearer $TOKEN" \
https://apigee.googleapis.com/v1/organizations/$YOUR_GOOGLE_PROJECT_ID/developers/$DEVELOPER_EMAIL_ID/monetizationConfig

Ao executar o comando, você vai ver uma resposta semelhante a esta:

{
  "billingType": "PREPAID",
}

Atualizar a configuração de monetização

Para atualizar a configuração de monetização de um desenvolvedor, emita uma solicitação PUT para a seguinte API:

https://apigee.googleapis.com/v1/organizations/$YOUR_GOOGLE_PROJECT_ID/developers/$DEVELOPER_EMAIL_ID/monetizationConfig

Com essa API, é possível atualizar o tipo de faturamento do desenvolvedor. Para mais informações sobre a API, consulte updateMonetizationConfig.

O exemplo a seguir mostra como atualizar a configuração de monetização de um desenvolvedor usando o comando curl:

curl -H "Authorization: Bearer $TOKEN" \
-H "Content-type: application/json" \
-X PUT \
-d '{
"billingType": "POSTPAID",
}' \
https://apigee.googleapis.com/v1/organizations/$YOUR_GOOGLE_PROJECT_ID/developers/$DEVELOPER_EMAIL_ID/monetizationConfig

Ao executar o comando, você vai ver uma resposta semelhante a esta:

{
  "billingType": "POSTPAID",
}

Alteração do tipo de faturamento

Os desenvolvedores podem alterar o faturamento deles de pré-pago para pós-pago e vice-versa. Nesta seção, descrevemos as mudanças que ocorrem na Apigee quando os desenvolvedores alteram o tipo de faturamento.

De pós-pago para pré-pago

Se um desenvolvedor mudar de pós-pago para pré-pago, a Apigee definirá imediatamente o billingType do desenvolvedor como PREPAID na configuração. O desenvolvedor pode começar a usar as APIs até o valor limite pré-pago de recarga. Com base nos relatórios de monetização personalizados, qualquer uso atual da conta pós-paga do desenvolvedor precisa ser cobrado separadamente por você (provedor de API).

De pré-pago para pós-pago

Se um desenvolvedor mudar de pré-pago para pós-pago, a Apigee define imediatamente o billingType do desenvolvedor como POSTPAID na configuração. Quaisquer saldos atuais (de todas as moedas) na conta pré-paga do desenvolvedor são exibidos como transação de crédito nos relatórios personalizados de monetização. Ao calcular o valor devido por um desenvolvedor após o ciclo de faturamento, você (provedor da API) precisa considerar o saldo de crédito na conta do desenvolvedor.

Ver saldo do desenvolvedor

Para visualizar o saldo na conta pré-paga de um desenvolvedor, emita uma solicitação GET para a seguinte API:

https://apigee.googleapis.com/v1/organizations/$YOUR_GOOGLE_PROJECT_ID/developers/$DEVELOPER_EMAIL_ID/balance

Para mais informações sobre a API, veja getBalance.

O exemplo a seguir mostra como visualizar o saldo na conta pré-paga de um desenvolvedor:

curl -H "Authorization: Bearer $TOKEN" \
https://apigee.googleapis.com/v1/organizations/$YOUR_GOOGLE_PROJECT_ID/developers/$DEVELOPER_EMAIL_ID/balance

Ao executar o comando, você vai ver uma resposta semelhante a esta:

{
  "wallets": [
    {
      "balance": {
        "currencyCode": "USD",
        "units": "150",
        "nanos": 500000000
      },
      "lastCreditTime": 1234567890
    },
    {
      "balance": {
        "currencyCode": "INR",
        "units": "10000",
        "nanos": 600000000
      },
      "lastCreditTime": 9876543210
    }
  ]
}

Na resposta de amostra, o desenvolvedor tem dois saldos de conta pré-paga, um para cada moeda. É possível saber o valor do saldo nos campos units e nanos. O campo lastCreditTime está no formato de tempo de época e indica a hora em que o saldo do desenvolvedor foi creditado pela última vez.

Saldo negativo do desenvolvedor

Se um desenvolvedor fizer várias chamadas de API em um curto período de tempo, é possível que o desenvolvedor tenha permissão para fazer chamadas de API em excesso, o que resulta em um saldo negativo da carteira para o desenvolvedor.

Esse cenário ocorre quando vários processadores de mensagens processam as chamadas de API do mesmo desenvolvedor. Cada processador de mensagens terá uma cópia do saldo do desenvolvedor com base na qual ele permite chamadas de API. Todos os processadores de mensagens sincronizam periodicamente os próprios saldos com o principal no banco de dados do Cassandra. Devido aos pequenos atrasos na sincronização, o saldo da carteira de um desenvolvedor em um processador de mensagens pode não estar sincronizado com o saldo principal. Por exemplo, em um determinado momento, se o saldo da carteira do desenvolvedor em um processador de mensagens for USD 2, o saldo principal poderá ser USD 0. Portanto, o processador de mensagens permite as chamadas de API do desenvolvedor, pensando que a carteira do desenvolvedor ainda tem USD 2.

A Apigee sincroniza o saldo da carteira de um processador de mensagens quase em tempo real com pequenos atrasos, e não é possível controlar ou configurar esse comportamento da Apigee. No entanto, todas as chamadas de API excedentes feitas por um desenvolvedor são consideradas. Depois de processar todas as chamadas de API de um desenvolvedor, o valor final na carteira do desenvolvedor reflete a cobrança mesmo pelas chamadas de API excedentes. Então, quando o desenvolvedor recarregar a conta na próxima vez, para que ele tenha um saldo positivo da carteira, primeiro ele precisará pagar qualquer valor de saldo negativo da carteira.

Creditar saldo do desenvolvedor

Para creditar o saldo na conta pré-paga de um desenvolvedor, emita uma solicitação POST para a seguinte API:

https://apigee.googleapis.com/v1/organizations/$YOUR_GOOGLE_PROJECT_ID/developers/$DEVELOPER_EMAIL_ID/balance:credit

Para mais informações sobre a API, veja creditBalance.

O crédito do saldo de um desenvolvedor abrange as seguintes etapas, nesta ordem:

Um desenvolvedor recarrega a conta do portal do desenvolvedor usando um gateway de pagamento.
O portal do desenvolvedor gera um código de transação exclusivo para a recarga.
O portal do desenvolvedor atualiza o saldo de desenvolvedor usando a API organizations/{org}/developers/{developer}/balance:credit.

Este exemplo mostra a chamada de API para a etapa 3 e credita o saldo do desenvolvedor em USD 150,21. O campo transactionId é definido como o valor do ID da transação de recarga (etapa 3).

curl -H "Authorization: Bearer $TOKEN" \
-H "Content-type: application/json" \
-X POST \
-d '{
  "transactionAmount": {
     "currencyCode": "USD",
     "units": "150",
     "nanos": 210000000
  },
  "transactionId": "ab31b63e-f8e8-11eb-9a03-0242ac130003"
}' \
https://apigee.googleapis.com/v1/organizations/$YOUR_GOOGLE_PROJECT_ID/developers/$DEVELOPER_EMAIL_ID/balance:credit

Ao executar o comando, você vai ver uma resposta semelhante a esta:

{
  "wallets": [
    {
      "balance": {
        "currencyCode": "USD",
        "units": "300",
        "nanos": 710000000
      },
      "lastCreditTime": "9876543210"
    },
    {
      "balance": {
        "currencyCode": "INR",
        "units": "10000",
        "nanos": 600000000
      },
      "lastCreditTime": "1234567890"
    }
  ]
}

Observação: após o crédito do saldo de um desenvolvedor em uma moeda, leva cerca de cinco minutos para que o novo saldo seja refletido em todos os componentes da Apigee. Durante esse tempo, se você tentar creditar novamente o saldo do desenvolvedor na moeda creditada anteriormente, a API creditBalance informará um erro. Portanto, como prática recomendada, aguarde aproximadamente cinco minutos entre um crédito e outro de uma determinada moeda.

Ajustar o saldo do desenvolvedor

Se você tiver cobrado um valor incorreto na conta de um desenvolvedor, use a API adjustBalance para diminuir ou aumentar o saldo da conta.

Para creditar o saldo na conta pré-paga de um desenvolvedor, emita uma solicitação POST para a seguinte API:

https://apigee.googleapis.com/v1/organizations/$YOUR_GOOGLE_PROJECT_ID/developers/$DEVELOPER_EMAIL_ID/balance:adjust

Para mais informações sobre a API, consulte adjustBalance.

Se quiser diminuir o saldo de um desenvolvedor cobrado a menos, defina o campo units na solicitação como um valor positivo. O exemplo a seguir diminui o saldo na conta pré-paga de um desenvolvedor em USD 50:

curl -H "Authorization: Bearer $TOKEN" \
-H "Content-type: application/json" \
-X POST \
-d '{
  "adjustment": {
    "units": "50",
    "currencyCode": "USD"
  }
}' \
https://apigee.googleapis.com/v1/organizations/$YOUR_GOOGLE_PROJECT_ID/developers/$DEVELOPER_EMAIL_ID/balance:adjust

Ao executar o comando, você vai ver uma resposta semelhante a esta:

{
  "wallets": [
    {
      "balance": {
        "currencyCode": "USD",
        "units": "150"
      },
      "lastCreditTime": "1635489199530"
    }
  ]
}

Se quiser aumentar o saldo de um desenvolvedor cobrado a mais, defina o campo units na solicitação como um valor negativo. O exemplo a seguir aumenta o saldo da conta pré-paga de um desenvolvedor em USD 50.1:

curl -H "Authorization: Bearer $TOKEN" \
-H "Content-type: application/json" \
-X POST \
-d '{
  "adjustment": {
    "units": "-50",
    "nanos": "100000000",
    "currencyCode": "USD"
  }
}' \
https://apigee.googleapis.com/v1/organizations/$YOUR_GOOGLE_PROJECT_ID/developers/$DEVELOPER_EMAIL_ID/balance:adjust

Ao executar o comando, você vai ver uma resposta semelhante a esta:

{
  "wallets": [
    {
      "balance": {
        "currencyCode": "USD",
        "units": "200",
        "nanos": 100000000
      },
      "lastCreditTime": "1635489199530"
    }
  ]
}