Configura una política de grabación de transacciones

Estás viendo la documentación de Apigee Edge.
Consulta la documentación de Apigee X. Más información

Configura las 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 registro de transacciones permite que la monetización capture los parámetros de las transacciones y los atributos personalizados. El equipo de monetización necesita esta información para realizar su procesamiento, como la aplicación de planes de tarifas.

Por ejemplo, si configuras un plan de tarifas de reparto de ingresos, un porcentaje de los ingresos generados por cada transacción relacionada con tu producto de API monetizado se comparte con el desarrollador de la app que emite la solicitud. El porcentaje de ingresos se basa en el precio neto o bruto de la transacción (especifica cuál), es decir, un porcentaje del precio bruto o neto de cada transacción que se usa para determinar el porcentaje de ingresos. Por este motivo, 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 hoja de tarifas en el que 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 que se transmiten 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 los atributos de la transacción en la política de registro de transacciones, puedes especificar criterios de éxito de la transacción para determinar cuándo una transacción se realiza de forma correcta (para fines de cobro). Para ver ejemplos de cómo configurar criterios de éxito de transacciones, consulta Ejemplos de configuración de criterios de éxito de transacciones en una política de registro de transacciones. También puedes especificar atributos personalizados para un producto de API (en el que se aplican los cargos del plan de tarifas base).

Configura una política de registro de transacciones

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

Configura los atributos de las transacciones

En la sección Atributos de la transacción, especifica los criterios que indican que se realizó correctamente la transacción de monetización.

1. En el campo Criterios de éxito de transacciones, especifica la expresión según el valor del atributo de estado (que se describe a continuación) para determinar cuándo se realizó correctamente la transacción (a fines de cobro). Las transacciones que no se ejecutan correctamente (es decir, que no cumplen con los criterios de la expresión) se registran, pero no se aplican los planes de tarifas. Por ejemplo:

   txProviderStatus == 'OK'

2. El atributo Status contiene el valor que usa la expresión configurada en el campo Transaction Success Criteria. Para configurar el atributo Status, define los siguientes campos:

   Campo	Descripción
   Recurso de API	Patrones de URI definidos en el producto de API que se usarán para identificar transacciones monetizadas.
   Ubicación de la respuesta	Ubicación de la respuesta en la que se especifica el atributo. Entre los valores válidos, se incluyen los siguientes: variable de flujo, encabezado, cuerpo de JSON y cuerpo XML.
   Valor	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 los 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 porcentaje de ingresos. Para 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 string. Precio bruto de una transacción. Para los planes de reparto de ingresos, debes registrar los atributos precio bruto o precio neto. El atributo obligatorio depende del porcentaje de ingresos. Por ejemplo, puedes configurar un plan de tarifas de reparto de ingresos que se base 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 porcentaje de ingresos. Para 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 string. Es el precio neto de una transacción. Para los planes de porcentaje de ingresos, debes registrar los campos Precio neto o 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 porcentaje de ingresos. Es el tipo de moneda que se aplica a la transacción.
   Código de error	Código de error asociado con la transacción. Proporciona más información sobre una transacción con errores.
   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 de string. Importe del impuesto sobre la compra. Precio neto más impuestos = precio bruto

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

Campo	Valor
Criterios de éxito de la transacción	txProviderStatus == 'OK'
Estado: recurso de API	**
Estado: Ubicación de la respuesta	Variable de flujo
Estado: Variable de flujo	response.reason.phrase

Configura atributos personalizados

En la sección Custom Attributes, identifica los atributos personalizados que se incluirán en la política de registro de transacciones. Por ejemplo, si configuras un plan de hoja de tarifas en el que 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 que se transmiten 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 tu tarifa del plan).

Puedes incluir atributos personalizados definidos en la política de registro de transacciones en los 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 Use Custom Attributes 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.

Campo	Descripción
Nombre del atributo personalizado	Ingrese un nombre que describa el atributo personalizado. Si el plan de tarifas se basa en un atributo personalizado, este nombre se muestra al usuario en los detalles del plan. Por ejemplo, si el atributo personalizado captura la duración, debes asignarle un nombre a la duración del atributo. Las unidades reales para el atributo personalizado (como horas, minutos o segundos) se establecen en el campo de la unidad de calificación cuando creas un plan de tarifas para atributos personalizados (consulta Cómo especificar el plan de tarifas con los detalles de los atributos personalizados).
Recurso de API	Selecciona uno o más sufijos de URI (es decir, el fragmento de URI que sigue la ruta base) de un recurso de API al que se accede en la transacción. Los recursos disponibles son los mismos que para los atributos de transacción.
Ubicación de la respuesta	Selecciona la ubicación en la respuesta en la que se especifica el atributo. Entre los valores válidos, se incluyen los siguientes: variable de flujo, encabezado, cuerpo de JSON y cuerpo XML.
Valor	Especifique un valor para el atributo personalizado. Cada valor que especifiques corresponde a un campo, parámetro o elemento de contenido que proporciona el atributo personalizado en la ubicación que especificaste. Para especificar más de un valor, haz clic en + Agregar x (por ejemplo, + Agregar variable de flujo). Por ejemplo, si configuras un atributo personalizado denominado Longitud del contenido y seleccionas Encabezado como la ubicación de la respuesta, si el valor de Longitud del contenido se proporciona en el campo Longitud del contenido HTTP, debes especificar Content-Length como valor.

Vincula recursos con un ID de transacción único

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

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

Para procesar toda la transacción, la monetización necesita una forma de vincular el primer recurso (la llamada y la respuesta desde y hacia la API de Reserve) con el segundo recurso (la llamada y respuesta desde y hacia la API de Charge). Para ello, se basa en la información que especifiques 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 ID de transacción únicos y vincula las transacciones. Para cada transacción, debes especificar un recurso, una ubicación de respuesta y un valor del atributo que esté vinculado con los valores correspondientes en las otras transacciones.

Por ejemplo, supongamos que la llamada a la API de Reserve y la llamada a la API de Charge están vinculadas de la siguiente manera: un campo llamado session_id en el encabezado de respuesta de la API de Reserve corresponde a un encabezado de respuesta llamado reference_id de la API de Charge. En este caso, puedes configurar las entradas en la sección para vincular recursos con un ID de transacción único de la siguiente manera:

Recurso	Ubicación de la respuesta	Valor
reserve/{id}**	Encabezado	session_id
/charge/{id}**	Encabezado	reference_id

Configuración de reembolsos

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

Por ejemplo, supongamos que un usuario compra un producto de una app para dispositivos móviles que usa tus APIs monetizadas. La transacción se monetiza según el plan de ingresos compartido. Sin embargo, supongamos que el usuario no está satisfecho con el producto y quiere devolverlo. Si se reembolsa el producto mediante una llamada a tu API que realiza el reembolso, la monetización realizará los ajustes necesarios. Lo hace según la información que especifiques 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. Para definir los criterios de reembolso, define los siguientes campos:

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

2. Para configurar el atributo Status, define los siguientes campos:

   Campo	Descripción
   Ubicación de la respuesta	Ubicación de la respuesta en la que se especifica el atributo. Entre los valores válidos, se incluyen los siguientes: variable de flujo, encabezado, cuerpo de JSON y cuerpo XML.
   Valor	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 superior mediante la definición de los siguientes campos:

   Campo	Descripción
   Ubicación de la respuesta	Ubicación de la respuesta en la que se especifica el atributo. Entre los valores válidos, se incluyen los siguientes: variable de flujo, encabezado, cuerpo de JSON y cuerpo XML.
   Valor	ID de la transacción para la cual 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 los atributos de reembolso opcionales, habilita el botón de activación Use optional Refund Attributes y configura los atributos. Los atributos opcionales de reembolso son los mismos que los atributos opcionales de transacción, tal como se define en Configura los atributos de transacción.

Administra las políticas de registro de transacciones mediante la API

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

Crea una política de registro de transacciones con la API

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

• El sufijo de URI del recurso del producto al que se adjunta la política de registro de transacciones. El sufijo incluye una variable de patrón que está encerrado entre llaves. Los servicios de API evalúan la variable de patrón en el entorno 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 de URI del recurso como /reserve seguido de cualquier subdirectorio que comience con un ID definido por el proveedor de la API.

• El recurso en la respuesta a la que se adjuntó. Un producto de API puede tener varios recursos, y cada uno de ellos 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 registro de transacciones a un producto de API, emite 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 los criterios de éxito de la transacción mediante la API

Puedes especificar criterios de éxito de la transacción para determinar cuándo una transacción se realizó correctamente (con fines de cobro). Las transacciones que no se ejecutan de forma correcta (es decir, que cumplen con los criterios de la expresión) se registran, pero no se aplican los planes de tarifas. Para ver ejemplos de cómo configurar criterios de éxito de transacciones, consulta Ejemplos de configuración de criterios de éxito de transacciones en una política de registro de transacciones.

Los criterios de éxito de la transacción se especifican como un atributo de un producto de API. Para ello, envía una solicitud PUT a la API de Management 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 (las especificaciones relacionadas con los criterios de éxito de la transacción están destacadas).

$ 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

Especifica atributos personalizados mediante la API

Puedes especificar atributos personalizados para un producto de API en el que se aplican los cargos del plan de tarifas base. Por ejemplo, si configuras un plan de hoja de tarifas, en el que 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 que se transmiten en una transacción. Cuando creas un plan de tarifas, puedes especificar uno o más atributos personalizados en los que basar tu tarifa del plan. Sin embargo, cualquier producto específico de un plan de tarifas solo puede tener un atributo personalizado en el que se basará la tarifa del plan.

Los atributos personalizados se especifican como atributos de un producto de API. Para ello, envía una solicitud PUT a la API de Management 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, deberás especificar un nombre y un valor de atributo. El nombre debe tener el formato MINT_CUSTOM_ATTRIBUTE_{num}, en el que {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 configuración de criterios de éxito de transacciones en una política de registro 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 txProviderStatus que muestra el proxy de API. txProviderStatus es la variable interna que usa la monetización para determinar el éxito de las transacciones.

Expresión de criterios de éxito	¿Expresión válida?	Valor txProviderStatus del proxy de API	Resultado de la evaluación
null	true	"200"	false
""	false	"200"	false
" "	false	"200"	false
"sdfsdfsdf"	false	"200"	false
"txProviderStatus =='100'"	verdadero	"200"	false
"txProviderStatus =='200'"	true	"200"	true
"true"	true	"200"	true
"txProviderStatus=='OK' OR txProviderStatus=='Not Found' OR txProviderStatus=='Bad Request'"	true	"OK"	true
"txProviderStatus matches '(OK)|(Not Found)|(Bad Request)'"	true	"OK"	true
"txProviderStatus matches '(OK)|(Not Found)|(Bad Request)'"	true	"Not Found"	true
"txProviderStatus matches '(OK)|(Not Found)|(Bad Request)'"	true	"Bad Request"	true
"(txProviderStatus?:'') matches '(?i)(OK)|(Not Found)|(Bad Request)'"	true	"Bad Request"	true
"(txProviderStatus?:'') matches '(?i)(OK)|(Not Found)|(Bad Request)'"	true	null	false
"txProviderStatus matches '(?i)(OK)|(Not Found)|(Bad Request)'"	true	"bad request"	true
"txProviderStatus matches '(?i)(OK)|(Not Found)|(Bad Request)'"	true	"Redirect"	false
"txProviderStatus matches '(?i)(OK)|(Not Found)|(Bad Request)'"	verdadero	"heeeelllooo"	false
"txProviderStatus matches '(?i)(OK)|(Not Found)|(Bad Request)'"	verdadero	null	false
"txProviderStatus == 100"	verdadero	"200"	false