Configura una política de grabación de transacciones

Estás consultando la documentación de Apigee Edge.
Consulta la documentación de Apigee X.
Información

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

Introducción

Una política de registro de transacciones permite que la monetización capture parámetros de transacciones y atributos personalizados. La 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 porcentaje de ingresos, un porcentaje de los ingresos generados por cada transacción que involucre tu producto de API monetizado se comparte 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 (especificas cuál), es decir, un porcentaje del precio bruto o neto de cada transacción que se utiliza para determinar el reparto 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 realizas en la política de registro de transacciones.

Si configuras un plan de hoja de tarifas en el que se le cobra al desarrollador por cada transacción, puedes establecer la tarifa del plan según un atributo personalizado, como la cantidad de bytes que se transmiten en una transacción. La monetización debe 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 las transacciones en la política de registro de transacciones, puedes especificar criterios de éxito de las transacciones para determinar cuándo se realizaron de forma correcta (para fines de cobro). Si quieres ver ejemplos de cómo configurar criterios de éxito de transacciones, consulta Ejemplos de cómo configurar 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 tarifa base).

Configura una política de registro de transacciones

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

Conexión de integración

Cuando agregas un paquete de productos de la API con la IU de Edge, debes configurar la política de registro de transacciones mediante los siguientes pasos:

  1. Selecciona el producto de API que quieres configurar en la sección Política de registro de transacciones (si hay varios productos de API en el paquete de productos).
  2. Configura los atributos de las transacciones.
  3. Configura atributos personalizados.
  4. Vincula recursos con IDs de transacción únicos.
  5. Configura los reembolsos.
  6. Repite los pasos para cada producto de la API definido en el paquete de productos de la API.

Versión clásica de Edge (nube privada)

Para configurar una política de registro de transacciones mediante la IU de Edge clásica, sigue estos pasos:

  1. Accede a http://ms-ip:9000, donde ms-ip es la dirección IP o el nombre de DNS del nodo del servidor de administración.
  2. Selecciona Publish > Products en la barra de navegación superior.
  3. Haz clic en + Política de registro de transacciones en la fila del producto de API aplicable. Aparecerá la ventana New Transaction Recording Policy.
  4. Para configurar la política de registro de transacciones, sigue estos pasos:
  5. Haz clic en Guardar.

Configura los atributos de las transacciones

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

  1. En el campo Criterios de éxito de la transacción, especifica la expresión según el valor del atributo Estado (que se describe a continuación) para determinar cuándo la transacción se realiza de forma correcta (para fines de cobro). Las transacciones que no se realizan 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 utilizarán para identificar las 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 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 opcionales de las transacciones, habilita el botón de activación Use Optional Attributes y, luego, 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, es obligatorio indicar el precio bruto o el precio neto. Asegúrate de que el valor numérico se exprese como un tipo de string. Es el precio bruto de una transacción. Para los planes de porcentaje de ingresos, debes registrar el atributo precio bruto o el precio neto. El atributo obligatorio depende del porcentaje de ingresos. Por ejemplo, puedes configurar un plan de tarifas de porcentaje 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 porcentaje de ingresos. Para esos planes de tarifas, es obligatorio indicar el precio bruto o el precio neto. 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 reparto 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 porcentaje de ingresos basado 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. Indica el tipo de moneda que se aplica a la transacción.

    Código de error

    Es el código de error asociado con la transacción. Brinda 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 es relevante solo para los modelos de reparto de ingresos y 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 de impuestos sobre la compra El precio neto más los impuestos = el precio bruto.

Por ejemplo, cuando se establecen 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 se adjunta a la solicitud de ProxyEndpoint del proxy de la API, la monetización la 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 Atributos personalizados, identificas los atributos personalizados que se deben incluir 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 según 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).

Se pueden incluir los atributos personalizados definidos en la política de registro de transacciones en los informes de resumen de ingresos, tal como se describe en Incluye atributos de transacciones personalizados en los informes de resumen de ingresos.

Para configurar los 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 Ingresa 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 de tarifas. Por ejemplo, si el atributo personalizado captura la duración, entonces debes asignarle un nombre a la duración del atributo. Las unidades reales del atributo personalizado (como horas, minutos o segundos) se establecen en el campo de unidades de calificación cuando creas un plan de tarifas de atributos personalizados (consulta Especifica el plan de tarifas con los detalles de atributos personalizados).
Recurso de API Selecciona uno o más sufijos 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 JSON y cuerpo XML.
Valor Especifique un valor para el atributo personalizado. Cada valor que especificas 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 llamado Longitud del contenido y seleccionas Encabezado como ubicación de respuesta, si el valor de Longitud del contenido se proporciona en el campo Longitud del contenido de HTTP, debes especificar Content-Length como valor.

Algunas transacciones son simples y requieren 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 incluye varias llamadas a recursos:

  • Es una llamada a una API de Reserve que garantiza que un usuario prepagado tenga crédito suficiente 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 prepagada del usuario.

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 reserva) con el segundo recurso (la llamada y la respuesta desde y hacia la API de cobro). Para hacerlo, se basa en la información que especifiques en la sección Cómo vincular recursos con un ID de transacción único.

Para configurar los 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é 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 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 desde una app para dispositivos móviles que utiliza 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 desea 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 Use Refund Attributes 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 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 de los 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 (para fines de cobro). Las transacciones de reembolso que no se realizan correctamente (es decir, que no cumplen con los criterios de la expresión) se registran, pero no se les 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 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 el atributo ID principal, 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 JSON y cuerpo XML.
    Valor Es el ID de la transacción para la que se procesó 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 configúralos. 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 con la API

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

Crea una política de registro de transacciones mediante 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á 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 la 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).

Especifica 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 (para fines de cobro). Las transacciones que no se realizan correctamente (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.

Debes especificar 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 de forma correcta 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

Especifica atributos personalizados con 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 según 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 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 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}, 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 transacciones 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 de 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