Configura una política de grabación de transacciones

Estás viendo la documentación de Apigee Edge.
Ir a la documentación de Apigee X. info

Configura políticas de registro de transacciones para cada producto de API en tu paquete de productos de API, como se describe en las siguientes secciones.

Introducción

Una política de grabación de transacciones permite que la monetización capture parámetros de transacciones y atributos personalizados. La monetización necesita esta información para realizar el procesamiento de la monetización, como aplicar planes de tarifas.

Por ejemplo, si configuras un plan de tarifas de participación en los ingresos, se comparte un porcentaje de los ingresos generados a partir de cada transacción asociada a tu producto de API monetizado con el desarrollador de la app que emite la solicitud. El reparto de ingresos se basa en el precio neto o bruto de la transacción (tú especificas cuál), es decir, se usa un porcentaje del precio bruto o neto de cada transacción para determinar el reparto de ingresos. Por lo tanto, la monetización debe conocer el precio bruto o neto de una transacción, según corresponda. Obtiene el precio bruto o neto de la configuración que estableces en la política de registro de transacciones.

Si configuras un plan de tarjeta de tarifas, en el que le cobras al desarrollador por cada transacción, puedes establecer la tarifa del plan en función de un atributo personalizado, como la cantidad de bytes transmitidos en una transacción. La monetización necesita saber qué es el atributo personalizado y dónde encontrarlo. Por lo tanto, debes especificar el atributo personalizado en la política de registro de transacciones.

Además de especificar atributos de transacción en la política de grabación de transacciones, puedes especificar criterios de éxito de la transacción para determinar cuándo una transacción se realiza correctamente (para fines de facturación). Para ver ejemplos de cómo establecer criterios de éxito de transacciones, consulta Ejemplos de cómo establecer criterios de éxito de transacciones en una política de grabación de transacciones. También puedes especificar atributos personalizados para un producto de API (en el que basas los cargos del plan de tarifas).

Configura una política de grabación de transacciones

Accede a la página Paquetes de productos, como se describe a continuación.

Cómo configurar atributos de transacción

En la sección Transaction Attributes, especifica los criterios que indican una transacción de monetización exitosa.

1. En el campo Criterios de éxito de la transacción, especifica la expresión basada en el valor del atributo Estado (que se describe a continuación) para determinar cuándo la transacción es exitosa (para fines de facturación). Se registran las transacciones que no se completan correctamente (es decir, que no cumplen con los criterios de la expresión), pero no se les aplican planes de tarifas. Por ejemplo:

   txProviderStatus == 'OK'

2. El atributo Estado contiene el valor que usa la expresión configurada en el campo Criterios de éxito de la transacción. Configura el atributo Status definiendo los siguientes campos:

   Campo	Descripción
   Recurso de API	Son los patrones de URI definidos en el producto de API que se usarán para identificar las transacciones monetizadas.
   Ubicación de la respuesta	Es la ubicación de la respuesta en la que se especifica el atributo. Los valores válidos incluyen: Variable de flujo, Encabezado, Cuerpo JSON y Cuerpo XML.
   Valor	Es el valor de la respuesta. Para especificar más de un valor, haz clic en + Agregar x (por ejemplo, + Agregar variable de flujo).

3. Para configurar atributos de transacción opcionales, habilita el botón de activación Usar atributos opcionales y configura cualquiera de los atributos de transacción definidos en la siguiente tabla.

   Atributo	Descripción
   Precio bruto	Este atributo solo se aplica a los planes de tarifas que usan el modelo de participación en los ingresos. En el caso de esos planes de tarifas, el precio bruto o el precio neto son obligatorios. Asegúrate de que el valor numérico se exprese como un tipo de cadena. Es el precio bruto de una transacción. En el caso de los planes de participación en los ingresos, debes registrar el atributo Precio bruto o el atributo Precio neto. El atributo requerido depende de la base del porcentaje de ingresos. Por ejemplo, puedes configurar un plan de tarifas de reparto de ingresos basado en el precio bruto de una transacción. En ese caso, el campo Precio bruto es obligatorio.
   Precio neto	Este atributo solo se aplica a los planes de tarifas que usan el modelo de participación en los ingresos. En el caso de esos planes de tarifas, el precio bruto o el precio neto son obligatorios. Asegúrate de que el valor numérico se exprese como un tipo de cadena. Es el precio neto de una transacción. En el caso de los planes de porcentaje de ingresos, debes registrar el campo Precio neto o el campo Precio bruto. El campo obligatorio depende de la base del porcentaje de ingresos. Por ejemplo, puedes configurar un plan de tarifas de reparto de ingresos que se base en el precio neto de una transacción. En ese caso, el campo Precio neto es obligatorio.
   Moneda	Este atributo es obligatorio para los planes de tarifas que usan el modelo de participación en los ingresos. Es el tipo de moneda que se aplica a la transacción.
   Código de error	Es el código de error asociado a la transacción. Proporciona más información sobre una transacción fallida.
   Descripción de artículo	Es la descripción de la transacción.
   Impuesto	Este atributo solo es relevante para los modelos de reparto de ingresos y solo si el importe del impuesto se captura en las llamadas a la API. Asegúrate de que el valor numérico se exprese como un tipo String. Es el importe del impuesto sobre la compra. Precio neto más impuestos = precio bruto.

Por ejemplo, si estableces los siguientes valores, la monetización obtiene el valor de la variable de flujo de la respuesta del mensaje en una variable llamada response.reason.phrase. Si el valor es correcto y la política de verificación de límites de monetización está adjunta a la solicitud de ProxyEndpoint del proxy de API, la monetización la cuenta como una transacción.

Configura atributos personalizados

En la sección Custom Attributes, identifica los atributos personalizados que se incluirán en la política de grabación de transacciones. Por ejemplo, si configuras un plan de tarjeta de tarifas en el que le cobras al desarrollador por cada transacción, puedes establecer la tarifa del plan en función de un atributo personalizado, como la cantidad de bytes transmitidos en una transacción. Luego, debes incluir ese atributo personalizado en la política de registro de transacciones.

Cada uno de estos atributos se almacena en el registro de transacciones, que puedes consultar. También se muestran cuando creas un plan de tarifas (para que puedas elegir uno o más de estos atributos en los que basar la tarifa del plan).

Puedes incluir atributos personalizados definidos en la política de grabación de transacciones en tus informes de resumen de ingresos, como se describe en Cómo incluir atributos de transacciones personalizados en los informes de resumen de ingresos.

Para configurar atributos personalizados, habilita el botón de activación Usar atributos personalizados y define hasta 10 atributos personalizados. Para cada atributo personalizado que incluyas en la política de registro de transacciones, debes especificar la siguiente información.

Vincula recursos con un ID de transacción único

Algunas transacciones son simples y requieren una llamada a la API para un recurso. Sin embargo, otras transacciones pueden ser más complejas. Por ejemplo, supongamos que una transacción para comprar un producto integrado en una app de juegos para dispositivos móviles implica varias llamadas a recursos:

• Es una llamada a una API de reserva que garantiza que un usuario prepago tenga suficiente crédito para comprar el producto y asigna ("reserva") los fondos para la compra.
• Es una llamada a una API de cargos que deduce los fondos de la cuenta del usuario prepago.

Para procesar toda la transacción, la monetización necesita una forma de vincular el primer recurso (la llamada y la respuesta a la API de Reserve) con el segundo recurso (la llamada y la respuesta a la API de Charge). Para ello, se basa en la información que especificas en la sección Vincula recursos con un ID de transacción único.

Para configurar atributos personalizados, habilita el botón de activación Usar IDs de transacción únicos y vincula las transacciones. Para cada transacción, debes especificar un recurso, una ubicación de respuesta y un valor de atributo que estén vinculados con los valores correspondientes en las demás transacciones.

Por ejemplo, supongamos que la llamada a la API de reserva y la llamada a la API de cargo están vinculadas de la siguiente manera: un campo llamado session_id en el encabezado de respuesta de la API de reserva corresponde a un encabezado de respuesta llamado reference_id de la API de cargo. En este caso, puedes configurar las entradas de la sección Link Resources with Unique Transaction ID de la siguiente manera:

Cómo configurar los reembolsos

En la sección Reembolsos, especifica los atributos que la monetización usa para procesar los reembolsos.

Por ejemplo, supongamos que un usuario compra un producto desde una app para dispositivos móviles que usa tus APIs monetizadas. La transacción se monetiza según el plan de ingresos compartidos. Sin embargo, supongamos que el usuario no está satisfecho con el producto y quiere devolverlo. Si el producto se reembolsa con una llamada a tu API que realiza el reembolso, la monetización hace los ajustes necesarios. Esto se basa en la información que especificas en la sección Reembolsos de la política de registro de transacciones.

Para configurar los reembolsos, habilita el botón de activación Usar atributos de reembolso y define los detalles del reembolso:

1. Define los criterios de reembolso especificando los siguientes campos:

   Campo	Descripción
   Ubicación de la respuesta	Es el recurso para la transacción de reembolso. Si el producto de API proporciona varios recursos, solo puedes seleccionar el recurso que realiza el reembolso.
   Criterios de éxito del reembolso	Es una expresión basada en el valor del atributo Status (que se describe a continuación) para determinar cuándo la transacción de reembolso se realiza correctamente (para fines de cobro). Se registran las transacciones de reembolso que no se realizan correctamente (es decir, que no cumplen con los criterios de la expresión), pero no se les aplican planes de tarifas. Por ejemplo: txProviderStatus == 'OK'

2. Configura el atributo Status definiendo los siguientes campos:

   Campo	Descripción
   Ubicación de la respuesta	Es la ubicación de la respuesta en la que se especifica el atributo. Los valores válidos incluyen: Variable de flujo, Encabezado, Cuerpo JSON y Cuerpo XML.
   Valor	Es el valor de la respuesta. Para especificar más de un valor, haz clic en + Agregar x (por ejemplo, + Agregar variable de flujo).

3. Configura el atributo ID principal definiendo los siguientes campos:

   Campo	Descripción
   Ubicación de la respuesta	Es la ubicación de la respuesta en la que se especifica el atributo. Los valores válidos incluyen: Variable de flujo, Encabezado, Cuerpo JSON y Cuerpo XML.
   Valor	Es el ID de la transacción para la que se procesa un reembolso. Por ejemplo, si un usuario compra un producto y, luego, solicita un reembolso, el ID de transacción principal es el ID de la transacción de compra. Para especificar más de un valor, haz clic en + Agregar x (por ejemplo, + Agregar variable de flujo).

4. Para configurar atributos de reembolso opcionales, habilita el botón de activación Usar atributos de reembolso opcionales y configura los atributos. Los atributos de reembolso opcionales son los mismos que los atributos de transacción opcionales, como se definen en Cómo configurar atributos de transacción.

Administra las políticas de grabación de transacciones con la API

En las siguientes secciones, se describe cómo administrar las políticas de grabación de transacciones con la API.

Crea una política de grabación de transacciones con la API

Especificas una política de registro de transacciones como un atributo de un producto de API. El valor del atributo identifica lo siguiente:

• Es el sufijo del URI del recurso del producto al que se adjunta la política de grabación de transacciones. El sufijo incluye una variable de patrón que se encuentra entre llaves. Los servicios de API evalúan la variable de patrón en el tiempo de ejecución. Por ejemplo, el siguiente sufijo de URI incluye la variable de patrón {id}.

  /reserve/{id}**

  En este caso, los Servicios de API evalúan el sufijo del URI del recurso como /reserve seguido de cualquier subdirectorio que comience con un ID definido por el proveedor de la API.

• Es el recurso en la respuesta al que se adjunta. Un producto de API puede tener varios recursos, y cada recurso puede tener una política de registro de transacciones adjunta a una respuesta de ese recurso.
• Una política de extracción de variables que permite que la política de registro de transacciones extraiga contenido de un mensaje de respuesta para los parámetros de transacción que deseas capturar.

Para agregar el atributo de política de grabación de transacciones a un producto de API, envía una solicitud PUT a la API de administración https://api.enterprise.apigee.com/v1/organizations/{org_name}/apiproducts/{apiproduct_Id} (y no a una API de monetización).

Cómo especificar criterios de éxito de la transacción con la API

Puedes especificar criterios de éxito de la transacción para determinar cuándo una transacción es exitosa (a los efectos de la facturación). Se registran las transacciones que no se completan correctamente (es decir, que no cumplen con los criterios de la expresión), pero no se les aplican planes de tarifas. Para ver ejemplos de cómo establecer criterios de éxito de la transacción, consulta Ejemplos de cómo establecer criterios de éxito de la transacción en una política de grabación de transacciones.

Especificas los criterios de éxito de la transacción como un atributo de un producto de API. Para ello, envía una solicitud PUT a la API de administración https://api.enterprise.apigee.com/v1/organizations/{org_name}/apiproducts/{apiproduct_Id} (y no a la API de monetización).

Por ejemplo, en la siguiente solicitud, una transacción se realiza correctamente si el valor de txProviderStatus es success (se destacan las especificaciones relacionadas con los criterios de éxito de la transacción).

$ 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

Cómo especificar atributos personalizados con la API

Puedes especificar atributos personalizados para un producto de API en el que basas los cargos del plan de tarifas. Por ejemplo, si configuras un plan de tarjeta de tarifas, en el que le cobras al desarrollador por cada transacción, puedes establecer la tarifa del plan en función de un atributo personalizado, como la cantidad de bytes transmitidos en una transacción. Cuando creas un plan de tarifas, puedes especificar uno o más atributos personalizados en los que se basará la tarifa del plan. Sin embargo, cualquier producto específico de un plan de tarifas solo puede tener un atributo personalizado en el que se base la tarifa del plan.

Especificas atributos personalizados como atributos de un producto de API. Para ello, envía una solicitud PUT a la API de administración https://api.enterprise.apigee.com/v1/organizations/{org_name}/apiproducts/{apiproduct_Id} (y no a la API de monetización).

Para cada atributo personalizado que agregues a un producto de API, debes especificar un nombre y un valor de atributo. El nombre debe tener el formato MINT_CUSTOM_ATTRIBUTE_{num}, donde {num} es un número entero.

Por ejemplo, la siguiente solicitud especifica tres atributos personalizados.

$ 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

Ejemplos de cómo establecer criterios de éxito de la transacción en una política de grabación de transacciones

En la siguiente tabla, se proporcionan ejemplos de transacciones exitosas y fallidas según la expresión de criterios de éxito de la transacción y el valor de txProviderStatus que devuelve el proxy de API. txProviderStatus es la variable interna que usa la monetización para determinar el éxito de la transacción.