Gerir saldos de contas pré-pagas

Esta página aplica-se ao Apigee e ao Apigee Hybrid.

Veja a documentação do Apigee Edge.

Esta página descreve como pode gerir as suas contas de faturação pré-pagas.

Pode usar as APIs Apigee para gerir as contas de faturação pré-pagas dos seus programadores. Ao usar as APIs, pode realizar as seguintes tarefas:

Veja a configuração de rentabilização

Para ver a configuração de rentabilização de um programador, emita um pedido GET para a seguinte API:

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

Com esta API, pode ver o tipo de faturação do programador. Para mais informações sobre a API, consulte getMonetizationConfig.

O exemplo seguinte mostra como ver a configuração de rentabilização de um programador através do comando curl:

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

Quando executa o comando, pode ver uma resposta semelhante à seguinte:

{
  "billingType": "PREPAID",
}

Atualize a configuração de rentabilização

Para atualizar a configuração de rentabilização de um programador, envie um pedido PUT para a seguinte API:

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

Com esta API, pode atualizar o tipo de faturação do programador. Para mais informações sobre a API, consulte updateMonetizationConfig.

O exemplo seguinte mostra como atualizar a configuração de rentabilização de um programador através do 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

Quando executa o comando, pode ver uma resposta semelhante à seguinte:

{
  "billingType": "POSTPAID",
}

Alteração do tipo de faturação

Os programadores podem alternar a respetiva faturação de pré-paga para pós-paga e vice-versa. Esta secção descreve as alterações que ocorrem no Apigee quando os programadores alteram o respetivo tipo de faturação.

Pós-pago para pré-pago

Se um programador mudar de pós-pago para pré-pago, o Apigee define imediatamente o billingType do programador como PREPAID na configuração. O programador pode começar a usar as APIs até ao valor do recarregamento pré-pago. Com base nos seus relatórios de rentabilização personalizados, qualquer utilização existente na conta pós-paga do programador deve ser faturada separadamente por si (fornecedor da API).

Pré-pago para pós-pago

Se um programador mudar de pré-pago para pós-pago, o Apigee define imediatamente o billingType do programador como POSTPAID na configuração. Os relatórios de rentabilização personalizada mostram qualquer saldo existente (de todas as moedas) na conta pré-paga do programador como uma transação de crédito. Ao calcular o valor em dívida de um programador após o ciclo de faturação, o fornecedor da API tem de considerar o saldo de crédito na conta do programador.

Ver saldo de programador

Para ver o saldo na conta pré-paga de um programador, emita um pedido 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, consulte getBalance.

O exemplo seguinte mostra como ver o saldo na conta pré-paga de um programador:

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

Quando executa o comando, pode ver uma resposta semelhante à seguinte:

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

Na resposta de exemplo, o programador tem dois saldos de conta pré-pagos, um para cada moeda. Pode saber o valor do saldo nos campos units e nanos. O campo lastCreditTime está no formato de hora de época e indica a hora em que o saldo do programador foi creditado pela última vez.

Saldo negativo do programador

Se um programador fizer várias chamadas API num curto período, é possível que o programador seja autorizado a fazer chamadas API em excesso, o que resulta num saldo negativo na carteira do programador.

Este cenário ocorre quando vários processadores de mensagens estão a processar as chamadas da API do mesmo programador. Cada processador de mensagens tem uma cópia do saldo do programador com base no qual permite as chamadas API. Todos os processadores de mensagens sincronizam periodicamente os respetivos saldos com o saldo principal na base de dados Cassandra. Devido aos pequenos atrasos na sincronização, o saldo da carteira de um programador num processador de mensagens pode estar dessincronizado com o saldo principal. Por exemplo, num determinado momento, se o saldo da carteira do programador num processador de mensagens for de 2 USD, o saldo principal pode ser de 0 USD. Assim, o processador de mensagens permite as chamadas API do programador, pensando que a carteira do programador ainda tem 2 USD.

O Apigee sincroniza o saldo da carteira de um processador de mensagens praticamente em tempo real com pequenos atrasos, e não pode controlar nem configurar este comportamento do Apigee. No entanto, todas as chamadas API em excesso feitas por um programador são contabilizadas. Após o processamento de todas as chamadas da API de um programador, o valor final na carteira do programador reflete a cobrança, mesmo para as chamadas da API em excesso. Assim, quando o programador recarregar a conta da próxima vez, para ter um saldo positivo na carteira, tem primeiro de pagar qualquer valor de saldo negativo na carteira.

Crédito do saldo de programador

Para creditar o saldo na conta pré-paga de um programador, emita um pedido 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, consulte creditBalance.

A atribuição de crédito ao saldo de um programador envolve os seguintes passos pela ordem indicada:

  1. Um programador carrega a conta de programador a partir do portal do programador através de um gateway de pagamento.
  2. O portal do programador gera um ID da transação exclusivo para o carregamento.
  3. O portal para programadores atualiza o saldo do programador através da API organizations/{org}/developers/{developer}/balance:credit.

O exemplo seguinte mostra a chamada API para o passo 3 e credita o saldo do programador em 150,21 USD. O valor transactionId é definido como o valor do ID da transação de recarga (passo 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

Quando executa o comando, pode ver uma resposta semelhante à seguinte:

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

Ajuste o saldo de programador

Se tiver cobrado um valor inferior ou superior ao devido à conta de um programador, pode usar a API para diminuir ou aumentar o saldo da conta.adjustBalance

Para ajustar o saldo na conta pré-paga de um programador, emita um pedido 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 programador com cobrança inferior, defina o campo units no pedido para um valor positivo. O exemplo seguinte diminui o saldo na conta pré-paga de um programador em 50 USD:

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

Quando executa o comando, pode ver uma resposta semelhante à seguinte:

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

Se quiser aumentar o saldo de um programador com cobrança excessiva, defina o campo units no pedido para um valor negativo. O exemplo seguinte aumenta o saldo na conta pré-paga de um programador em 50.1 USD:

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

Quando executa o comando, pode ver uma resposta semelhante à seguinte:

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