Gerir saldos de contas pré-pagas

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

Veja a documentação do Apigee Edge.

Nota: as funcionalidades de rentabilização especificadas nas notas de lançamento da rentabilização do Apigee de 3 de novembro de 2021 só são suportadas no Apigee.

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 programadores de apps e dos grupos de apps. Ao usar as APIs, pode realizar as seguintes tarefas:

• Veja a configuração de rentabilização
• Atualize a configuração de rentabilização
• Ver saldo
• Saldo de crédito
• Ajuste o saldo

Nota: os seus planos tarifários determinam a quantia de dinheiro deduzida das contas pré-pagas. Para obter informações sobre a configuração de planos tarifários, consulte o artigo Gerir planos tarifários para produtos API.

Veja a configuração de rentabilização

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

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

Para ver a configuração de rentabilização de um AppGroup, envie um pedido GET para esta API:

https://apigee.googleapis.com/v1/organizations/$YOUR_GOOGLE_PROJECT_ID/appgroups/APPGROUP_ID/monetizationConfig

Com a API, pode ver o tipo de faturação. Para mais informações sobre a API, consulte organizations.developers.getMonetizationConfig ou organizations.appgroups.getMonetizationConfig.

O exemplo seguinte mostra como ver a configuração de rentabilização de um programador de apps 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 de apps, envie um pedido PUT para a seguinte API:

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

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

https://apigee.googleapis.com/v1/organizations/$YOUR_GOOGLE_PROJECT_ID/appgroups/$APPGROUP_NAME/monetizationConfig

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

O exemplo seguinte mostra como atualizar a configuração de rentabilização para um programador de apps 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 de apps e os AppGroups 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 altera um tipo de faturação.

Pós-pago para pré-pago

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

Pré-pago para pós-pago

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

Ver saldo

Para ver o saldo na conta pré-paga de um programador de apps, emita um pedido GET para a seguinte API:

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

Para ver o saldo na conta pré-paga de um AppGroup, emita um pedido GET para a seguinte API:

https://apigee.googleapis.com/v1/organizations/$YOUR_GOOGLE_PROJECT_ID/appgroups/$APPGROUP_NAME/balance

Para mais informações sobre a API, consulte organizations.developers.getBalance ou organizations.appgroups.getBalance.

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

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 de apps tem dois saldos de contas pré-pagos, um para cada moeda. Pode encontrar 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 foi creditado pela última vez.

Saldo negativo

Se um programador de apps ou um AppGroup fizer várias chamadas API num curto período, pode exceder as chamadas API permitidas, o que resulta num saldo negativo da carteira.

Este cenário ocorre quando vários processadores de mensagens estão a processar as chamadas API do mesmo programador de apps ou AppGroup. Cada processador de mensagens tem uma cópia do saldo com base no qual permite as chamadas da API. Todos os processadores de mensagens sincronizam periodicamente os respetivos saldos com o saldo principal. Devido ao pequeno atraso na sincronização, o saldo da carteira num processador de mensagens pode estar dessincronizado com o saldo principal. Por exemplo, num determinado momento, se o saldo da carteira num processador de mensagens for de 2 USD, o saldo principal pode ser de 0 USD. Assim, o processador de mensagens permite as chamadas da API, pensando que a carteira 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, nesta situação, as chamadas API em excesso são contabilizadas. Após o processamento de todas as chamadas da API do programador da app ou do AppGroup, o valor final na carteira reflete a cobrança, mesmo para as chamadas da API em excesso. Assim, quando o programador da app ou o grupo de apps recarregar a conta da próxima vez, para ter um saldo positivo na carteira, o programador da app ou o grupo de apps tem de pagar primeiro qualquer valor negativo na carteira.

Saldo de crédito

Para creditar o saldo na conta pré-paga de um programador de apps, 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 creditar o saldo na conta pré-paga de um AppGroup, emita um pedido POST para a seguinte API:

https://apigee.googleapis.com/v1/organizations/$YOUR_GOOGLE_PROJECT_ID/appgroups/$APPGROUP_NAME/balance:credit

Para mais informações sobre a API, consulte organizations.developers.balance.credit ou organizations.appgroups.balance.credit.

A atribuição de crédito a um saldo envolve os seguintes passos, por ordem:

1. Um programador de apps ou um AppGroup recarrega a conta a partir do portal do programador através de uma gateway de pagamento.
2. O portal do programador gera um ID da transação exclusivo para o carregamento.
3. O portal do programador atualiza o saldo do programador através da API adequada, quer seja um programador de apps ou um AppGroup.

O exemplo seguinte mostra a chamada da API para o passo 3 e credita o saldo de um programador de apps 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"
    }
  ]
}

Nota: depois de creditar um saldo para uma moeda, o novo saldo demora cerca de 5 minutos a ser refletido em todos os componentes do Apigee. Durante este período, se tentar novamente creditar o saldo para a moeda creditada anteriormente, a API de saldo de crédito comunica um erro. Por conseguinte, como prática recomendada, aguarde cerca de 5 minutos entre dois créditos de uma determinada moeda.

Ajuste o saldo

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

Para ajustar o saldo na conta pré-paga de um programador de apps, 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 ajustar o saldo na conta pré-paga de um AppGroup, emita um pedido POST para a seguinte API:

https://apigee.googleapis.com/v1/organizations/$YOUR_GOOGLE_PROJECT_ID/appgroups/$APPGROUP_NAME/balance:adjust

Para mais informações sobre a API, consulte organizations.developers.balanceadjustBalance ou organizations.appgroups.balance.adjustBalance.

Se quiser diminuir o saldo de um programador de apps ou de um AppGroup 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 de apps 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 de apps ou de um AppGroup 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 de apps 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"
    }
  ]
}