Configurer une règle d'enregistrement des transactions

Vous consultez la documentation Apigee Edge.
Accédez à la documentation Apigee X.

Configurez des règles d'enregistrement des transactions pour chaque produit d'API de votre offre groupée de produits d'API, comme décrit dans les sections suivantes.

Introduction

Un règlement concernant l'enregistrement des transactions permet à la monétisation d'enregistrer les paramètres de transaction et les attributs personnalisés. La monétisation a besoin de ces informations pour effectuer son traitement de monétisation, par exemple en appliquant des plans tarifaires.

Par exemple, si vous configurez un plan tarifaire de partage des revenus, un pourcentage des revenus générés par chaque transaction impliquant votre produit d'API monétisé est partagé avec le développeur de l'application qui a envoyé la requête. La part des revenus est basée sur le prix net ou brut de la transaction (vous choisissez celui qui vous convient). En d'autres termes, un pourcentage du prix brut ou net de chaque transaction est utilisé pour déterminer la part des revenus. Par conséquent, la monétisation doit connaître le prix brut ou net d'une transaction, selon le cas. Il récupère le prix brut ou net à partir des paramètres que vous définissez dans la règle d'enregistrement des transactions.

Si vous configurez un plan avec une grille tarifaire, dans lequel vous facturez le développeur pour chaque transaction, vous pouvez définir le tarif du plan en fonction d'un attribut personnalisé tel que le nombre d'octets transmis dans une transaction. La monétisation doit connaître l'attribut personnalisé et savoir où le trouver. Vous devez donc spécifier l'attribut personnalisé dans la règle d'enregistrement des transactions.

En plus de spécifier les attributs de transaction dans le règlement sur l'enregistrement des transactions, vous pouvez spécifier des critères de réussite des transactions pour déterminer quand une transaction est réussie (à des fins de facturation). Pour obtenir des exemples de définition des critères de réussite des transactions, consultez Exemples de définition des critères de réussite des transactions dans une règle d'enregistrement des transactions. Vous pouvez également spécifier des attributs personnalisés pour un produit d'API (sur lequel vous basez les frais du plan tarifaire).

Configurer une règle d'enregistrement des transactions

Accédez à la page "Groupes de produits", comme décrit ci-dessous.

Configurer les attributs de transaction

Dans la section Attributs de transaction, spécifiez les critères qui indiquent une transaction de monétisation réussie.

1. Dans le champ Critères de réussite de la transaction, spécifiez l'expression basée sur la valeur de l'attribut "État" (décrit ci-après) pour déterminer quand la transaction est réussie (à des fins de facturation). Les transactions qui n'ont pas abouti (c'est-à-dire qui ne répondent pas aux critères de l'expression) sont enregistrées, mais les forfaits ne leur sont pas appliqués. Exemple :

   txProviderStatus == 'OK'

2. L'attribut Status contient la valeur utilisée par l'expression configurée dans le champ Critères de réussite de la transaction. Configurez l'attribut Status en définissant les champs suivants :

   Champ	Description
   Ressource d'API	Modèles d'URI définis dans le produit d'API qui seront utilisés pour identifier les transactions monétisées.
   Emplacement de la réponse	Emplacement de la réponse où l'attribut est spécifié. Les valeurs valides incluent : "Variable de flux", "En-tête", "Corps JSON" et "Corps XML".
   Valeur	Valeur de la réponse. Pour spécifier plusieurs valeurs, cliquez sur + Ajouter x (par exemple, + Ajouter une variable de flux).

3. Pour configurer les attributs de transaction facultatifs, activez l'option Utiliser les attributs facultatifs et configurez les attributs de transaction définis dans le tableau suivant.

   Attribut	Description
   Prix brut	Cet attribut ne s'applique qu'aux forfaits qui utilisent le modèle de partage des revenus. Pour ces plans tarifaires, le prix brut ou le prix net est obligatoire. Assurez-vous que la valeur numérique est exprimée sous la forme d'une chaîne. Prix brut d'une transaction. Pour les forfaits avec partage des revenus, vous devez enregistrer l'attribut "Prix brut" ou "Prix net". L'attribut requis dépend de la base de la répartition des revenus. Par exemple, vous pouvez configurer un plan tarifaire de partage des revenus basé sur le prix brut d'une transaction. Dans ce cas, le champ "Prix brut" est obligatoire.
   Prix net	Cet attribut ne s'applique qu'aux forfaits qui utilisent le modèle de partage des revenus. Pour ces plans tarifaires, le prix brut ou le prix net est obligatoire. Assurez-vous que la valeur numérique est exprimée sous la forme d'une chaîne. Prix net d'une transaction. Pour les forfaits avec partage des revenus, vous devez enregistrer le champ "Prix net" ou le champ "Prix brut". Le champ requis dépend de la base du partage des revenus. Par exemple, vous pouvez configurer un plan tarifaire de partage des revenus basé sur le prix net d'une transaction. Dans ce cas, le champ "Prix net" est obligatoire.
   Devise	Cet attribut est obligatoire pour les forfaits qui utilisent le modèle de partage des revenus. Type de devise applicable à la transaction.
   Code d'erreur	Code d'erreur associé à la transaction. Il fournit des informations supplémentaires sur une transaction ayant échoué.
   Description de l'article	Description de la transaction.
   Taxes	Cet attribut ne concerne que les modèles de partage des revenus et uniquement si le montant des taxes est indiqué dans les appels d'API. Assurez-vous que la valeur numérique est exprimée sous la forme d'une chaîne. Montant des taxes sur l'achat. Prix net + taxes = prix brut.

Par exemple, en définissant les valeurs suivantes, la monétisation obtient la valeur de la variable de flux à partir de la réponse du message dans une variable appelée response.reason.phrase. Si la valeur est OK et que la règle de vérification des limites de monétisation est associée à la requête ProxyEndpoint du proxy d'API, la monétisation la comptabilise comme une transaction.

Configurer des attributs personnalisés

Dans la section Custom Attributes (Attributs personnalisés), vous identifiez les attributs personnalisés à inclure dans la règle d'enregistrement des transactions. Par exemple, si vous configurez un forfait avec grille tarifaire, où vous facturez le développeur pour chaque transaction, vous pouvez définir le tarif du forfait en fonction d'un attribut personnalisé tel que le nombre d'octets transmis lors d'une transaction. Vous devez ensuite inclure cet attribut personnalisé dans la règle d'enregistrement des transactions.

Chacun de ces attributs est stocké dans le journal des transactions, que vous pouvez interroger. Ils s'affichent également lorsque vous créez un forfait (pour que vous puissiez choisir un ou plusieurs de ces attributs sur lesquels baser le tarif du forfait).

Vous pouvez inclure des attributs personnalisés définis dans la règle d'enregistrement des transactions dans vos rapports récapitulatifs sur les revenus, comme décrit dans Inclure des attributs de transaction personnalisés dans les rapports récapitulatifs sur les revenus.

Pour configurer des attributs personnalisés, activez l'option Utiliser des attributs personnalisés et définissez jusqu'à 10 attributs personnalisés. Pour chaque attribut personnalisé que vous incluez dans la règle d'enregistrement des transactions, vous devez spécifier les informations suivantes.

Associer des ressources avec un ID de transaction unique

Certaines transactions sont simples et impliquent un appel d'API à une seule ressource. Toutefois, d'autres transactions peuvent être plus complexes. Par exemple, supposons qu'une transaction pour l'achat d'un produit intégré dans une application de jeu mobile implique plusieurs appels de ressources :

• Appel à une API de réservation qui garantit qu'un utilisateur prépayé dispose de suffisamment de crédit pour acheter le produit et qui alloue ("réserve") les fonds pour l'achat.
• Appel à une API de facturation qui déduit les fonds du compte de l'utilisateur prépayé.

Pour traiter l'intégralité de la transaction, la monétisation doit pouvoir associer la première ressource (l'appel et la réponse à l'API de réservation) à la deuxième ressource (l'appel et la réponse à l'API de facturation). Pour ce faire, il s'appuie sur les informations que vous spécifiez dans la section Associer des ressources avec un ID de transaction unique.

Pour configurer des attributs personnalisés, activez l'option Utiliser des ID de transaction uniques et associez les transactions. Pour chaque transaction, vous spécifiez une ressource, un emplacement de réponse et une valeur d'attribut qui sont associés aux valeurs correspondantes dans les autres transactions.

Par exemple, supposons que l'appel d'API de réservation et l'appel d'API de débit soient associés comme suit : un champ nommé session_id dans l'en-tête de réponse de l'API de réservation correspond à un en-tête de réponse nommé reference_id de l'API de débit. Dans ce cas, vous pouvez définir les entrées de la section "Associer des ressources avec un ID de transaction unique" comme suit :

Configurer les remboursements

Dans la section "Remboursements", vous spécifiez les attributs que la monétisation utilise pour traiter les remboursements.

Par exemple, supposons qu'un utilisateur achète un produit à partir d'une application mobile qui utilise vos API monétisées. La transaction est monétisée en fonction du plan de partage des revenus. Toutefois, supposons que l'utilisateur ne soit pas satisfait du produit et souhaite le renvoyer. Si le produit est remboursé à l'aide d'un appel à votre API qui effectue le remboursement, la monétisation effectue les ajustements nécessaires. Pour ce faire, il se base sur les informations que vous spécifiez dans la section "Remboursements" du règlement sur l'enregistrement des transactions.

Pour configurer les remboursements, activez l'option Utiliser les attributs de remboursement et définissez les détails du remboursement :

1. Définissez les critères de remboursement en renseignant les champs suivants :

   Champ	Description
   Emplacement de la réponse	Ressource pour la transaction de remboursement. Si le produit d'API fournit plusieurs ressources, vous ne pouvez sélectionner que celle qui effectue le remboursement.
   Critères de réussite des remboursements	Expression basée sur la valeur de l'attribut "État" (décrit ci-après) permettant de déterminer quand la transaction de remboursement est réussie (à des fins de facturation). Les transactions de remboursement qui n'aboutissent pas (c'est-à-dire qui ne répondent pas aux critères de l'expression) sont enregistrées, mais les forfaits ne leur sont pas appliqués. Exemple : txProviderStatus == 'OK'

2. Configurez l'attribut Status en définissant les champs suivants :

   Champ	Description
   Emplacement de la réponse	Emplacement de la réponse où l'attribut est spécifié. Les valeurs valides incluent : "Variable de flux", "En-tête", "Corps JSON" et "Corps XML".
   Valeur	Valeur de la réponse. Pour spécifier plusieurs valeurs, cliquez sur + Ajouter x (par exemple, + Ajouter une variable de flux).

3. Configurez l'attribut ID parent en définissant les champs suivants :

   Champ	Description
   Emplacement de la réponse	Emplacement de la réponse où l'attribut est spécifié. Les valeurs valides incluent : "Variable de flux", "En-tête", "Corps JSON" et "Corps XML".
   Valeur	ID de la transaction pour laquelle un remboursement est traité. Par exemple, si un utilisateur achète un produit, puis demande un remboursement, l'ID de transaction parent est l'ID de la transaction d'achat. Pour spécifier plusieurs valeurs, cliquez sur + Ajouter x (par exemple, + Ajouter une variable de flux).

4. Pour configurer les attributs de remboursement facultatifs, activez l'option Utiliser les attributs de remboursement facultatifs et configurez les attributs. Les attributs de remboursement facultatifs sont les mêmes que les attributs de transaction facultatifs, tels que définis dans Configurer les attributs de transaction.

Gérer les règles d'enregistrement des transactions à l'aide de l'API

Les sections suivantes décrivent comment gérer les règles d'enregistrement des transactions à l'aide de l'API.

Créer une règle d'enregistrement des transactions à l'aide de l'API

Vous spécifiez une règle d'enregistrement des transactions en tant qu'attribut d'un produit d'API. La valeur de l'attribut identifie :

• Suffixe URI de la ressource produit à laquelle la règle d'enregistrement des transactions est associée. Le suffixe inclut une variable de modèle placée entre accolades. La variable de modèle est évaluée par les services d'API lors de l'exécution. Par exemple, le suffixe d'URI suivant inclut la variable de modèle {id}.

  /reserve/{id}**

  Dans ce cas, les services d'API évaluent le suffixe URI de la ressource en tant que /reserve, suivi de tout sous-répertoire commençant par un ID défini par le fournisseur d'API.

• Ressource de la réponse à laquelle il est associé. Un produit d'API peut comporter plusieurs ressources, et chaque ressource peut être associée à une règle d'enregistrement des transactions pour une réponse de cette ressource.
• Règle d'extraction de variables qui permet à la règle d'enregistrement des transactions d'extraire le contenu d'un message de réponse pour les paramètres de transaction que vous souhaitez capturer.

Pour ajouter l'attribut de règle d'enregistrement des transactions à un produit d'API, envoyez une requête PUT à l'API de gestion https://api.enterprise.apigee.com/v1/organizations/{org_name}/apiproducts/{apiproduct_Id} (et non à une API de monétisation).

Spécifier les critères de réussite des transactions à l'aide de l'API

Vous pouvez spécifier des critères de réussite des transactions pour déterminer quand une transaction est réussie (à des fins de facturation). Les transactions qui n'ont pas abouti (c'est-à-dire celles qui ne répondent pas aux critères de l'expression) sont enregistrées, mais les forfaits ne leur sont pas appliqués. Pour obtenir des exemples de définition de critères de réussite des transactions, consultez Exemples de définition de critères de réussite des transactions dans une règle d'enregistrement des transactions.

Vous spécifiez les critères de réussite des transactions en tant qu'attribut d'un produit d'API. Pour ce faire, envoyez une requête PUT à l'API Management https://api.enterprise.apigee.com/v1/organizations/{org_name}/apiproducts/{apiproduct_Id} (et non à l'API Monetization).

Par exemple, dans la requête suivante, une transaction est considérée comme réussie si la valeur de txProviderStatus est success (les spécifications liées aux critères de réussite des transactions sont mises en évidence).

$ curl -H "Content-Type: application/json" -X PUT -d \ 
'{
        "apiResources": [
        "/reserve/{id}**"       
        ],
        "approvalType": "auto",
        "attributes": [                         
        {
                "name": "MINT_TRANSACTION_SUCCESS_CRITERIA",
                "value": "txProviderStatus == 'OK'"
        }
        ],
        "description": "Payment",
        "displayName": "Payment",
        "environments": [
        "dev"
        ],
        "name": "payment",
        "proxies": [],
        "scopes": [
        ""
        ]
}' \
"https://api.enterprise.apigee.com/v1/organizations/{org_name}/apiproducts/payment" \
-u email:password

Spécifier des attributs personnalisés à l'aide de l'API

Vous pouvez spécifier des attributs personnalisés pour un produit d'API sur lequel vous basez les frais du plan tarifaire. Par exemple, si vous configurez un forfait avec grille tarifaire, où vous facturez le développeur pour chaque transaction, vous pouvez définir le tarif du forfait en fonction d'un attribut personnalisé tel que le nombre d'octets transmis dans une transaction. Lorsque vous créez un forfait, vous pouvez spécifier un ou plusieurs attributs personnalisés sur lesquels baser le tarif du forfait. Toutefois, un produit spécifique d'un forfait ne peut avoir qu'un seul attribut personnalisé sur lequel baser le tarif du forfait.

Vous spécifiez des attributs personnalisés en tant qu'attributs d'un produit d'API. Pour ce faire, envoyez une requête PUT à l'API Management https://api.enterprise.apigee.com/v1/organizations/{org_name}/apiproducts/{apiproduct_Id} (et non à l'API Monetization).

Pour chaque attribut personnalisé que vous ajoutez à un produit API, vous devez spécifier un nom et une valeur d'attribut. Le nom doit être au format MINT_CUSTOM_ATTRIBUTE_{num}, où {num} est un entier.

Par exemple, la requête suivante spécifie trois attributs personnalisés.

$ curl -H "Content-Type: application/json" -X PUT -d \
'{
        "apiResources": [
        "/reserve/{id}**",
        "/charge/{id}**"
        ],
        "approvalType": "auto",
        "attributes": [
        {
                "name": "MINT_CUSTOM_ATTRIBUTE_1",
                "value": "test1"
        },
        {
                "name": "MINT_CUSTOM_ATTRIBUTE_2",
                "value": "test2"
        }
 
        ],
        "name": "payment",
        "proxies": [],
        "scopes": [
                ""
        ]
}' \
"https://api.enterprise.apigee.com/v1/organizations/{org_name}/apiproducts/payment" \
-u email:password

Exemples de définition de critères de réussite des transactions dans un règlement concernant l'enregistrement des transactions

Le tableau suivant fournit des exemples de transactions réussies et échouées, en fonction de l'expression des critères de réussite des transactions et de la valeur txProviderStatus renvoyée par le proxy d'API. txProviderStatus est la variable interne utilisée par la monétisation pour déterminer si une transaction a réussi.