Configurar uma política de gravação de transações

Você está lendo a documentação do Apigee Edge.
Acesse a documentação da Apigee X. info

Configure políticas de gravação de transações para cada produto de API no pacote, conforme descrito nas seções a seguir.

Introdução

Uma política de gravação de transações permite que a monetização capture parâmetros de transação e atributos personalizados. A monetização precisa dessas informações para realizar o processamento de monetização, como a aplicação de planos de taxas.

Por exemplo, se você configurar um plano de taxas de participação na receita, uma porcentagem da receita gerada por cada transação envolvendo seu produto de API monetizado será compartilhada com o desenvolvedor do app que emite a solicitação. A participação na receita é baseada no preço líquido ou bruto da transação (você especifica qual deles). Ou seja, uma porcentagem do preço bruto ou líquido de cada transação é usada para determinar a participação na receita. Por isso, a monetização precisa saber o preço bruto ou líquido de uma transação, conforme aplicável. Ele recebe o preço bruto ou líquido das configurações feitas na política de gravação de transações.

Se você configurar um plano de tabela de preços em que cobra o desenvolvedor por cada transação, poderá definir a taxa do plano com base em um atributo personalizado, como o número de bytes transmitidos em uma transação. A monetização precisa saber o que é o atributo personalizado e onde encontrá-lo. Portanto, é necessário especificar o atributo personalizado na política de gravação de transações.

Além de especificar atributos de transação na política de gravação de transações, você pode especificar critérios de sucesso para determinar quando uma transação é bem-sucedida (para fins de cobrança). Para exemplos de como definir critérios de sucesso de transação, consulte Exemplos de como definir critérios de sucesso de transação em uma política de gravação de transações. Também é possível especificar atributos personalizados para um produto de API (em que você baseia as cobranças do plano de tarifas).

Como configurar uma política de gravação de transações

Acesse a página "Pacotes de produtos", conforme descrito abaixo.

Configurar atributos de transação

Na seção Atributos da transação, especifique os critérios que indicam uma transação de monetização bem-sucedida.

1. No campo Critérios de sucesso da transação, especifique a expressão com base no valor do atributo "Status" (descrito a seguir) para determinar quando a transação é bem-sucedida (para fins de cobrança). As transações que não são bem-sucedidas (ou seja, não atendem aos critérios na expressão) são registradas, mas os planos de tarifas não são aplicados a elas. Exemplo:

   txProviderStatus == 'OK'

2. O atributo Status contém o valor usado pela expressão configurada no campo Critérios de sucesso da transação. Configure o atributo Status definindo os seguintes campos:

   Campo	Descrição
   Recurso da API	Padrões de URI definidos no produto de API que serão usados para identificar transações monetizadas.
   Local da resposta	Local da resposta em que o atributo é especificado. Os valores válidos incluem: variável de fluxo, cabeçalho, corpo JSON e corpo XML.
   Valor	Valor da resposta. Para especificar mais de um valor, clique em + Adicionar x (por exemplo, + Adicionar variável de fluxo).

3. Para configurar atributos de transação opcionais, ative a opção Usar atributos opcionais e configure qualquer um dos atributos de transação definidos na tabela a seguir.

   Atributo	Descrição
   Preço bruto	Esse atributo só é aplicável a planos de tarifas que usam o modelo de participação na receita. Para esses planos de tarifação, o preço bruto ou líquido é obrigatório. Verifique se o valor numérico está expresso como um tipo de string. Preço bruto de uma transação. Para planos de participação na receita, é necessário registrar o atributo "Preço bruto" ou "Preço líquido". O atributo obrigatório depende da base da participação na receita. Por exemplo, é possível configurar um plano de tarifas de participação na receita com base no preço bruto de uma transação. Nesse caso, o campo "Preço bruto" é obrigatório.
   Preço líquido	Esse atributo só é aplicável a planos de tarifas que usam o modelo de participação na receita. Para esses planos de tarifação, o preço bruto ou líquido é obrigatório. Verifique se o valor numérico está expresso como um tipo de string. Preço líquido de uma transação. Para planos de participação na receita, é necessário registrar o campo "Preço líquido" ou "Preço bruto". O campo obrigatório depende da base da participação na receita. Por exemplo, é possível definir um plano de tarifas de compartilhamento de receita com base no preço líquido de uma transação. Nesse caso, o campo "Preço líquido" é obrigatório.
   Moeda	Esse atributo é obrigatório para planos de tarifas que usam o modelo de divisão da receita. Tipo de moeda aplicável à transação.
   Código do erro	Código de erro associado à transação. Ele fornece mais informações sobre uma transação com falha.
   Descrição do item	Descrição da transação.
   Tributo	Esse atributo é relevante apenas para modelos de compartilhamento de receita e somente se o valor do tributo for capturado nas chamadas de API. Verifique se o valor numérico está expresso como um tipo de string. Valor dos tributos na compra. Preço líquido + tributos = preço bruto.

Por exemplo, ao definir os valores a seguir, a monetização recebe o valor da variável de fluxo da resposta da mensagem em uma variável chamada response.reason.phrase. Se o valor for OK e a política de verificação de limites de monetização estiver anexada à solicitação ProxyEndpoint do proxy de API, a monetização vai contar como uma transação.

Como configurar atributos personalizados

Na seção Atributos personalizados, identifique os atributos personalizados que serão incluídos na política de registro de transações. Por exemplo, se você configurar um plano de tabela de preços em que cobra do desenvolvedor por cada transação, poderá definir a taxa do plano com base em um atributo personalizado, como o número de bytes transmitidos em uma transação. Em seguida, inclua esse atributo personalizado na política de gravação de transações.

Cada um desses atributos é armazenado no registro de transações, que pode ser consultado. Eles também são mostrados quando você cria um plano de tarifas para escolher um ou mais atributos em que basear a tarifa do plano.

É possível incluir atributos personalizados definidos na política de registro de transações nos seus relatórios de resumo de receita, conforme descrito em Incluir atributos de transação personalizados nos relatórios de resumo de receita.

Para configurar atributos personalizados, ative a opção Usar atributos personalizados e defina até 10 atributos personalizados. Para cada atributo personalizado incluído na política de gravação de transações, especifique as seguintes informações.

Vincular recursos com ID de transação exclusivo

Algumas transações são simples, envolvendo uma chamada de API para um recurso. No entanto, outras transações podem ser mais complexas. Por exemplo, suponha que uma transação para comprar um produto no app em um app de jogos para dispositivos móveis envolva várias chamadas de recursos:

• Uma chamada para uma API de reserva que garante que um usuário pré-pago tenha crédito suficiente para comprar o produto e aloca ("reserva") os fundos para a compra.
• Uma chamada para uma API de cobrança que deduz os fundos da conta do usuário pré-pago.

Para processar toda a transação, a monetização precisa de uma maneira de vincular o primeiro recurso (a chamada e a resposta para e da API de reserva) ao segundo recurso (a chamada e a resposta para e da API de cobrança). Para isso, ele usa as informações especificadas na seção Vincular recursos com um ID de transação exclusivo.

Para configurar atributos personalizados, ative a opção Usar IDs de transação exclusivos e vincule as transações. Para cada transação, especifique um recurso, um local de resposta e um valor de atributo vinculados aos valores correspondentes nas outras transações.

Por exemplo, suponha que as chamadas de API de reserva e cobrança estejam vinculadas da seguinte maneira: um campo chamado session_id no cabeçalho de resposta da API de reserva corresponde a um cabeçalho de resposta chamado reference_id da API de cobrança. Nesse caso, defina as entradas na seção "Vincular recursos com ID da transação exclusivo" da seguinte maneira:

Como configurar reembolsos

Na seção "Reembolsos", especifique os atributos que a monetização usa para processar reembolsos.

Por exemplo, suponha que um usuário compre um produto em um app para dispositivos móveis que usa suas APIs monetizadas. A transação é monetizada com base no plano de receita compartilhada. No entanto, suponha que o usuário não esteja satisfeito com o produto e queira devolvê-lo. Se o produto for reembolsado usando uma chamada para sua API que faz o reembolso, a monetização fará os ajustes necessários. Isso é feito com base nas informações especificadas na seção "Reembolsos" da política de registro de transações.

Para configurar reembolsos, ative a opção Usar atributos de reembolso e defina os detalhes:

1. Defina os critérios de reembolso definindo os seguintes campos:

   Campo	Descrição
   Local da resposta	Recurso para a transação de reembolso. Se o produto de API fornecer vários recursos, selecione apenas aquele que realiza o reembolso.
   Critérios de sucesso do reembolso	Expressão baseada no valor do atributo "Status" (descrito a seguir) para determinar quando a transação de reembolso é bem-sucedida (para fins de cobrança). As transações de reembolso que não forem bem-sucedidas (ou seja, que não atenderem aos critérios da expressão) serão registradas, mas os planos de tarifas não serão aplicados a elas. Exemplo: txProviderStatus == 'OK'

2. Configure o atributo Status definindo os seguintes campos:

   Campo	Descrição
   Local da resposta	Local da resposta em que o atributo é especificado. Os valores válidos incluem: variável de fluxo, cabeçalho, corpo JSON e corpo XML.
   Valor	Valor da resposta. Para especificar mais de um valor, clique em + Adicionar x (por exemplo, + Adicionar variável de fluxo).

3. Configure o atributo ID principal definindo os seguintes campos:

   Campo	Descrição
   Local da resposta	Local da resposta em que o atributo é especificado. Os valores válidos incluem: variável de fluxo, cabeçalho, corpo JSON e corpo XML.
   Valor	ID da transação para a qual um reembolso é processado. Por exemplo, se um usuário comprar um produto e depois pedir um reembolso, o ID da transação principal será o ID da transação de compra. Para especificar mais de um valor, clique em + Adicionar x (por exemplo, + Adicionar variável de fluxo).

4. Para configurar atributos de reembolso opcionais, ative a opção Usar atributos de reembolso opcionais e configure os atributos. Os atributos opcionais de reembolso são os mesmos atributos opcionais de transação, conforme definido em Configurar atributos de transação.

Como gerenciar políticas de gravação de transações usando a API

As seções a seguir descrevem como gerenciar políticas de gravação de transações usando a API.

Como criar uma política de gravação de transações usando a API

Você especifica uma política de gravação de transações como um atributo de um produto de API. O valor do atributo identifica:

• O sufixo do URI do recurso do produto a que a política de gravação de transações está anexada. O sufixo inclui uma variável de padrão entre chaves. A variável pattern é avaliada pelos serviços de API no ambiente de execução. Por exemplo, o seguinte sufixo de URI inclui a variável de padrão {id}.

  /reserve/{id}**

  Nesse caso, os Serviços de API avaliam o sufixo do URI do recurso como /reserve seguido por qualquer subdiretório que comece com um ID definido pelo provedor da API.

• O recurso na resposta a que ele está anexado. Um produto de API pode ter vários recursos, e cada um deles pode ter uma política de gravação de transações anexada a uma resposta desse recurso.
• Uma política de extração de variáveis que permite à política de gravação de transações extrair conteúdo de uma mensagem de resposta para os parâmetros de transação que você quer capturar.

Para adicionar o atributo de política de gravação de transações a um produto de API, emita uma solicitação PUT para a API de gerenciamento https://api.enterprise.apigee.com/v1/organizations/{org_name}/apiproducts/{apiproduct_Id} (e não para uma API de monetização).

Especificar critérios de sucesso de transação usando a API

É possível especificar critérios de sucesso da transação para determinar quando uma transação é bem-sucedida (para fins de cobrança). As transações que não são bem-sucedidas (ou seja, que atendem aos critérios na expressão) são registradas, mas os planos de tarifas não são aplicados a elas. Para exemplos de definição de critérios de sucesso de transação, consulte Exemplos de definição de critérios de sucesso de transação em uma política de gravação de transações.

Você especifica os critérios de sucesso da transação como um atributo de um produto de API. Para isso, emita uma solicitação PUT para a API de gerenciamento https://api.enterprise.apigee.com/v1/organizations/{org_name}/apiproducts/{apiproduct_Id} (e não para a API de monetização).

Por exemplo, na solicitação a seguir, uma transação será bem-sucedida se o valor de txProviderStatus for success (as especificações relacionadas aos critérios de sucesso da transação estão 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

Especificar atributos personalizados usando a API

É possível especificar atributos personalizados para um produto de API em que você baseia as cobranças do plano de tarifas. Por exemplo, se você configurar um plano de tabela de preços, em que cobra do desenvolvedor por cada transação, é possível definir a taxa do plano com base em um atributo personalizado, como o número de bytes transmitidos em uma transação. Ao criar um plano de tarifas, você pode especificar um ou mais atributos personalizados em que basear a tarifa do plano. No entanto, um produto específico em um plano de tarifas só pode ter um atributo personalizado em que basear a tarifa do plano.

Você especifica atributos personalizados como atributos de um produto de API. Para isso, emita uma solicitação PUT para a API de gerenciamento https://api.enterprise.apigee.com/v1/organizations/{org_name}/apiproducts/{apiproduct_Id} (e não para a API de monetização).

Para cada atributo personalizado adicionado a um produto da API, é necessário especificar um nome e um valor de atributo. O nome precisa estar no formato MINT_CUSTOM_ATTRIBUTE_{num}, em que {num} é um número inteiro.

Por exemplo, a solicitação a seguir especifica três 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

Exemplos de definição de critérios de sucesso de transação em uma política de gravação de transações

A tabela a seguir mostra exemplos de transações bem-sucedidas e malsucedidas com base na expressão de critérios de sucesso da transação e no valor txProviderStatus retornado pelo proxy de API. txProviderStatus é a variável interna que a monetização usa para determinar o sucesso da transação.