Gérer le solde de comptes prépayés

Cette page s'applique à Apigee et à Apigee hybrid.

Consultez la documentation d' Apigee Edge.

Cette page explique comment gérer vos comptes de facturation avec prépaiement.

Vous pouvez utiliser les API Apigee pour gérer les comptes de facturation avec prépaiement de vos développeurs d'applications et de vos AppGroups. Les API vous permettent d'effectuer les tâches suivantes :

Afficher la configuration de la monétisation

Pour afficher la configuration de monétisation d'un développeur d'applications, envoyez une requête GET à l'API suivante :

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

Pour afficher la configuration de monétisation d'un AppGroup, envoyez une requête GET à cette API :

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

L'API vous permet d'afficher le type de facturation. Pour en savoir plus sur l'API, consultez organizations.developers.getMonetizationConfig ou organizations.appgroups.getMonetizationConfig.

L'exemple suivant montre comment afficher la configuration de monétisation pour un développeur d'applications à l'aide de la commande curl :

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

Lorsque vous exécutez la commande, une réponse semblable à la suivante s'affiche :

{
  "billingType": "PREPAID",
}

Mettre à jour la configuration de la monétisation

Pour mettre à jour la configuration de monétisation d'un développeur d'applications, envoyez une requête PUT à l'API suivante :

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

Pour mettre à jour la configuration de monétisation d'un AppGroup, envoyez une requête PUT à l'API suivante :

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

Cette API vous permet de mettre à jour le type de facturation. Pour en savoir plus sur l'API, consultez updateMonetizationConfig ou organizations.appgroups.updateMonetizationConfig.

L'exemple suivant montre comment mettre à jour la configuration de monétisation pour un développeur d'applications à l'aide de la commande 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

Lorsque vous exécutez la commande, une réponse semblable à la suivante s'affiche :

{
  "billingType": "POSTPAID",
}

Modification du type de facturation

Vos développeurs d'applications et vos AppGroups peuvent passer de la facturation avec prépaiement au post-paiement et inversement. Cette section décrit les modifications qui se produisent dans Apigee lorsque vous modifiez un type de facturation.

Post-paiement vers prépaiement

Lorsque vous passez d'une facturation avec post-paiement à un modèle avec prépaiement, Apigee définit immédiatement le champ billingType sur PREPAID dans la configuration. Le développeur d'applications ou le groupe d'applications peut commencer à utiliser les API dans la limite du montant prépayé. En vous basant sur vos rapports de monétisation personnalisés, en votre qualité de fournisseur d'API, vous devez facturer toute utilisation existante dans le compte avec post-paiement séparément.

Prépaiement vers post-paiement

Lorsque vous passez du prépaiement au post-paiement, Apigee définit immédiatement le billingType sur POSTPAID dans la configuration. Vos rapports de monétisation personnalisés affichent tout solde existant (pour toutes les devises) dans le compte prépayé en tant que transaction de crédit. Lors du calcul du montant dû après le cycle de facturation, vous devez, en tant que fournisseur d'API, tenir compte du solde créditeur dans le compte.

Afficher le solde

Pour afficher le solde du compte prépayé d'un développeur d'applications, envoyez une requête GET à l'API suivante :

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

Pour afficher le solde du compte prépayé d'un AppGroup, envoyez une requête GET à l'API suivante :

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

Pour en savoir plus sur l'API, consultez organizations.developers.getBalance ou organizations.appgroups.getBalance.

L'exemple suivant montre comment afficher le solde du compte prépayé d'un développeur d'applications :

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

Lorsque vous exécutez la commande, une réponse semblable à la suivante s'affiche :

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

Dans l'exemple de réponse, le développeur d'applications dispose de deux soldes de compte prépayé, un pour chaque devise. Vous pouvez connaître le montant du solde en consultant les champs units et nanos. Le champ lastCreditTime, au format "epoch", indique la date et l'heure de la dernière opération de crédit sur le solde.

Solde négatif

Si un développeur d'applications ou un AppGroup effectue plusieurs appels d'API dans un délai court, il peut dépasser le nombre d'appels d'API autorisés, ce qui entraîne un solde de portefeuille négatif.

Ce scénario se produit lorsque plusieurs processeurs de messages gèrent les appels d'API du même développeur d'applications ou AppGroup. Chaque processeur de messages dispose d'une copie du solde pour lequel il autorise les appels d'API. Tous les processeurs de messages synchronisent régulièrement leur solde avec le solde principal. En raison du léger retard de synchronisation, le solde du portefeuille dans un processeur de messages peut être désynchronisé avec le solde principal. Par exemple, à un moment donné, le solde du portefeuille dans un processeur de messages peut être de 2 USD alors que le solde principal est de 0 USD. Le processeur de messages autorise donc les appels d'API, en pensant que le portefeuille contient toujours 2 USD.

Apigee synchronise le solde de portefeuille du processeur de messages en quasi-temps réel avec des retards mineurs, et il est impossible de contrôler ou configurer ce comportement d'Apigee. Toutefois, dans ce cas, les appels d'API en excès sont pris en compte. Après avoir traité tous les appels d'API du développeur d'applications ou de l'AppGroup, le montant final dans le portefeuille reflète les frais, en incluant les appels d'API excédentaires. Ainsi, lorsque le développeur d'applications ou l'AppGroup recharge le compte la prochaine fois, il doit compenser le solde négatif du portefeuille avant de pouvoir disposer d'un solde de portefeuille positif.

Solde créditeur

Pour créditer le solde du compte prépayé d'un développeur d'applications, envoyez une requête POST à l'API suivante :

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

Pour créditer le solde du compte prépayé d'un AppGroup, envoyez une requête POST à l'API suivante :

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

Pour en savoir plus sur l'API, consultez organizations.developers.balance.credit ou organizations.appgroups.balance.credit.

Créditer un solde implique que les étapes suivantes soient effectuées dans l'ordre :

  1. Un développeur d'applications ou un groupe d'applications crédite le compte depuis le portail des développeurs en utilisant une passerelle de paiement.
  2. Le portail des développeurs génère un ID de transaction unique pour l'opération de crédit.
  3. Le portail des développeurs actualise le solde du développeur à l'aide de l'API appropriée, qu'il s'agisse d'un développeur d'applications ou d'un AppGroup.

L'exemple qui suit montre l'appel d'API de l'étape 3 ; le solde du développeur d'applications est crédité de 150,21 USD. Le champ transactionId est défini sur la valeur de l'ID de transaction de l'opération de crédit (étape 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

Lorsque vous exécutez la commande, une réponse semblable à la suivante s'affiche :

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

Ajuster le solde

Si vous avez surchargé ou sous-traité un compte, vous pouvez utiliser l'API adjustBalance pour réduire ou augmenter le solde du compte.

Pour ajuster le solde du compte prépayé d'un développeur d'applications, envoyez une requête POST à l'API suivante :

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

Pour ajuster le solde du compte prépayé d'un groupe d'applications, envoyez une requête POST à l'API suivante :

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

Pour en savoir plus sur l'API, consultez organizations.developers.balanceadjustBalance ou organizations.appgroups.balance.adjustBalance.

Si vous souhaitez réduire le solde d'un compte de développeur d'applications ou d'un AppGroup sous-traité, définissez le champ units dans la requête sur une valeur positive. L'exemple suivant réduit le solde du compte prépayé d'un développeur d'applications de 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

Lorsque vous exécutez la commande, une réponse semblable à la suivante s'affiche :

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

Si vous souhaitez augmenter le solde d'un développeur d'applications ou d'un AppGroup surchargé, définissez le champ units dans la requête sur une valeur négative. L'exemple suivant augmente le solde du compte prépayé d'un développeur d'applications de 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

Lorsque vous exécutez la commande, une réponse semblable à la suivante s'affiche :

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