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. Les API vous permettent d'effectuer les tâches suivantes :

Afficher la configuration de la monétisation
Mettre à jour la configuration de la monétisation
Afficher le solde du développeur
Créditer le solde du développeur
Ajuster le solde du développeur

Afficher la configuration de la monétisation

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

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

Cette API vous permet d'afficher le type de facturation du développeur. Pour en savoir plus sur l'API, consultez la page getMonetizationConfig.

L'exemple suivant montre comment afficher la configuration de monétisation pour un développeur à 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 pour un développeur, envoyez une requête PUT à l'API suivante :

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

Cette API vous permet de mettre à jour le type de facturation du développeur. Pour en savoir plus sur l'API, consultez la page updateMonetizationConfig.

L'exemple suivant montre comment mettre à jour la configuration de monétisation pour un développeur à 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 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 les développeurs modifient leur type de facturation.

Post-paiement vers prépaiement

Si un développeur passe d'une facturation avec post-paiement à un modèle avec prépaiement, Apigee définit immédiatement le billingType du développeur sur PREPAID dans la configuration. Le développeur 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 du développeur séparément.

Prépaiement vers post-paiement

Si un développeur passe d'une facturation avec prépaiement à un modèle avec post-paiement, Apigee définit immédiatement le champ billingType du développeur 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é du développeur en tant que transaction de crédit. Lors du calcul du montant dû par un développeur après le cycle de facturation, vous devez, en tant que fournisseur d'API, tenir compte du solde créditeur dans le compte du développeur.

Afficher le solde du développeur

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

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

Pour en savoir plus sur l'API, consultez la page getBalance.

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

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 dispose de deux éléments solde dans son 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 du développeur.

Solde de développeur négatif

Si un développeur effectue plusieurs appels d'API dans un délai court, il est possible qu'il soit autorisé à effectuer des appels d'API excédentaires, ce qui entraîne un solde de portefeuille négatif pour le développeur.

Ce scénario se produit lorsque plusieurs processeurs de messages gèrent les appels d'API du même développeur. Chaque processeur de messages dispose d'une copie du solde du développeur pour lequel il autorise les appels d'API. Tous les processeurs de messages synchronisent régulièrement leur solde avec le solde principal de la base de données Cassandra. En raison de retards mineurs dans la synchronisation, le solde de portefeuille d'un développeur dans un processeur de messages peut être désynchronisé avec le solde principal. Par exemple, à un moment donné, le solde du portefeuille du développeur 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 du développeur, en pensant que le portefeuille du développeur 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, tous les appels d'API effectués par un développeur en excès sont pris en compte. Après avoir traité tous les appels d'API d'un développeur, le montant final dans le portefeuille du développeur reflète les frais, en incluant les appels d'API excédentaires. Ainsi, lorsque le développeur 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.

Créditer le solde du développeur

Pour créditer le solde du compte prépayé d'un développeur, 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 en savoir plus sur l'API, consultez la page creditBalance.

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

Un développeur crédite le compte développeur depuis le portail des développeurs en utilisant une passerelle de paiement.
Le portail des développeurs génère un ID de transaction unique pour l'opération de crédit.
Le portail des développeurs actualise le solde du développeur à l'aide de l'API organizations/{org}/developers/{developer}/balance:credit.

L'exemple qui suit montre l'appel d'API de l'étape 3 ; le solde du développeur 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"
    }
  ]
}

Remarque : Une fois que vous avez crédité le solde d'un développeur pour une devise, il faut environ cinq minutes pour que le nouveau solde soit reflété dans tous les composants Apigee. Durant ce laps de temps, si vous essayez à nouveau de créditer le solde du développeur pour la devise ayant fait l'objet du crédit précédent, l'API creditBalance renvoie une erreur. Par conséquent, il est recommandé de définir un intervalle d'environ cinq minutes entre deux opérations de crédit concernant une devise particulière.

Ajuster le solde du développeur

Si vous avez surchargé ou sous-traité le compte d'un développeur, 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, 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 en savoir plus sur l'API, consultez la page adjustBalance.

Si vous souhaitez réduire le solde d'un compte de développeur 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ée d'un développeur 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 compte de développeur 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ée d'un développeur 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"
    }
  ]
}