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

Você está vendo a documentação do Apigee Edge.
Acesse a documentação da Apigee X.
informações

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

Introdução

Uma política de registro 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 da monetização, como aplicar planos de preços.

Por exemplo, se você configurar um plano de participação na receita, uma porcentagem da receita gerada em 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), 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. Ela recebe o preço bruto ou líquido das configurações feitas na política de registro de transações.

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

Além de especificar os atributos de transação na política de registro de transações, você pode especificar os critérios de sucesso da transação para determinar quando ela é bem-sucedida (para fins de cobrança). Para ver exemplos de como definir critérios de sucesso da transação, consulte Exemplos de configuração de critérios de sucesso da transação em uma política de registro 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 tarifa).

Como configurar uma política de registro de transações

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

Edge

Ao adicionar um pacote de produtos da API usando a interface do Edge, você precisa configurar a política de gravação de transações seguindo estas etapas:

  1. Selecione o produto de API a ser configurado na seção Política de registro de transações (se houver vários produtos de API no pacote).
  2. Configure os atributos da transação.
  3. Configurar atributos personalizados
  4. Vincular recursos com IDs de transação exclusivos.
  5. Configurar reembolsos.
  6. Repita o procedimento para cada produto de API definido no pacote de produtos de API.

Borda clássica (nuvem privada)

Para configurar uma política de gravação de transações usando a interface clássica do Edge:

  1. Faça login em http://ms-ip:9000, em que ms-ip é o endereço IP ou o nome DNS do nó do servidor de gerenciamento.
  2. Selecione Publicar > Produtos na barra de navegação superior.
  3. Na linha do produto de API aplicável, clique em + Política de registro de transações. A janela "Nova política de registro de transações" será exibida.
  4. Configure a política de registro de transações seguindo estas etapas:
  5. Clique em Salvar.

Como 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 foi concluída (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 preços 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 é aplicável somente a planos de tarifas que usam o modelo de participação na receita. Para esses planos de tarifas, é obrigatório definir o preço bruto ou líquido. Garanta que o valor numérico seja expresso como um tipo de string. É o preço bruto de uma transação. Para planos de participação na receita, é necessário registrar o atributo "Preço bruto" ou o "Preço líquido". O atributo obrigatório depende da base da participação na receita. Por exemplo, é possível configurar um plano de taxas 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 é aplicável somente a planos de tarifas que usam o modelo de participação na receita. Para esses planos de tarifas, é obrigatório definir o preço bruto ou líquido. Garanta que o valor numérico seja expresso como um tipo de string. Preço líquido de uma transação. Para planos de participação na receita, você precisa registrar o campo "Preço líquido" ou "Preço bruto". O campo obrigatório depende da participação na receita. Por exemplo, é possível configurar um plano de tarifas de participação na 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 participação na receita. Tipo de moeda que se aplica à transação.

    Código do erro

    Código do erro associado à transação. Ele fornece mais informações sobre uma transação com falha.

    Descrição do item

    Descrição da transação.

    Tributos

    Esse atributo só é relevante para modelos de participação na receita e apenas se o valor dos tributos for capturado nas chamadas de API. Verifique se o valor numérico é expresso como um tipo de string. Valor dos tributos da compra. Preço líquido mais impostos = 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 estiver correto e a política de verificação dos limites de monetização estiver anexada à solicitação do ProxyEndpoint de API, a monetização contará isso como uma transação.

Campo Valor
Critérios de sucesso da transação txProviderStatus == 'OK'
Status: recurso da API **
Status: local da resposta Variável de fluxo
Status: variável de fluxo response.reason.phrase

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 o desenvolvedor é cobrado por cada transação, é possível definir a taxa para o plano com base em um atributo personalizado, como o número de bytes transmitidos em uma transação. Em seguida, você precisa incluir esse atributo personalizado na política de registro de transações.

Cada um desses atributos é armazenado no registro de transação, que você pode consultar. Eles também são exibidos quando você cria um plano de tarifas para que você possa escolher um ou mais desses atributos como base para a tarifa do plano.

Você pode incluir atributos personalizados definidos na política de registro de transações nos relatórios de resumo de receita, conforme descrito em Como incluir atributos de transação personalizados em relatórios de resumo de receita.

Para configurar atributos personalizados, ative a opção Use Custom Attributes e defina até 10 atributos personalizados. Para cada atributo personalizado incluído na política de registro de transações, é necessário especificar as informações a seguir.

Campo Descrição
Nome do atributo personalizado Insira um nome que descreva o atributo personalizado. Se o plano de tarifa for baseado em um atributo personalizado, esse nome será exibido ao usuário nos detalhes do plano. Por exemplo, se o atributo personalizado captura duração, nomeie-o como duração. As unidades reais do atributo personalizado (como horas, minutos ou segundos) são definidas no campo de unidade de classificação quando você cria um plano de tarifa com atributos personalizados. Consulte Especificar plano de tarifa com detalhes do atributo personalizado.
Recurso da API Selecione um ou mais sufixos de URI (ou seja, o fragmento de URI que segue o caminho base) de um recurso de API acessado na transação. Os recursos disponíveis são os mesmos dos atributos de transação.
Local da resposta Selecione o local na resposta em que o atributo é especificado. Os valores válidos incluem: variável de fluxo, cabeçalho, corpo JSON e corpo XML.
Valor Especifique um valor para o atributo personalizado. Cada valor especificado corresponde a um campo, parâmetro ou elemento de conteúdo que fornece o atributo personalizado no local especificado. Para especificar mais de um valor, clique em + Adicionar x (por exemplo, + Adicionar variável de fluxo).

Por exemplo, se você configurar um atributo personalizado chamado Comprimento do conteúdo e selecionar Cabeçalho como o local da resposta, se o valor Comprimento do conteúdo for fornecido no campo Comprimento do conteúdo HTTP, especifique Content-Length como o valor.

Algumas transações são simples e envolvem uma chamada de API para um recurso. No entanto, outras transações podem ser mais complexas. Por exemplo, suponha que uma transação de compra de um produto em um app de jogo 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 de e para a API de reserva) ao segundo recurso (a chamada e a resposta de e para a API de cobrança). Para fazer isso, use as informações especificadas na seção Vincular recursos com código 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 de cobrança sejam 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, você pode definir as entradas na seção "Recursos de link com ID de transação exclusivo" da seguinte maneira:

Recurso Local da resposta Valor
reserve/{id}**

Cabeçalho

session_id
/charge/{id}**

Cabeçalho

reference_id

Como configurar reembolsos

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

Por exemplo, imagine que um usuário compre um produto de um app para dispositivos móveis que usa suas APIs monetizadas. A transação gera receita com base no plano de receita compartilhada. No entanto, suponha que o usuário esteja insatisfeito com o produto e queira devolvê-lo. Se o produto for reembolsado por meio de uma chamada para a API que faz o reembolso, a monetização vai fazer 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 do reembolso:

  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 fornece vários recursos, selecione apenas o recurso que executa o reembolso.
    Critérios de sucesso do reembolso Expressão com base no valor do atributo "Status" (descrito a seguir) para determinar quando a transação de reembolso foi realizada (para fins de cobrança). As transações de reembolso 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. 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 Parent ID 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 compra um produto e depois solicita um reembolso, o ID da transação principal é 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 de reembolso opcionais são iguais aos atributos de transação opcionais, conforme definido em Como configurar atributos de transação.

Como gerenciar políticas de registro de transações usando a API

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

Como criar uma política de registro de transações usando a API

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

  • O sufixo de URI do recurso do produto ao qual a política de registro de transações está anexada. O sufixo inclui uma variável de padrão entre chaves. A variável de padrão é avaliada pelos serviços da API no ambiente de execução. Por exemplo, o sufixo de URI a seguir inclui a variável de padrão {id}.
    /reserve/{id}**
    

    Nesse caso, os serviços da 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 ao qual ele está anexado. Um produto de API pode ter vários recursos, e cada um deles pode ter uma política de registro de transações anexada a uma resposta desse recurso.
  • Uma política de extração de variável que permite à política de gravação de transações extrair o conteúdo de uma mensagem de resposta para os parâmetros de transação que você quer capturar.

Você adiciona o atributo de política de registro de transações a um produto de API emitindo 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 da transação usando a API

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

Como especificar atributos personalizados usando a API

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

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 da transação em uma política de registro de transações

A tabela a seguir fornece 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 da API. txProviderStatus é a variável interna que a monetização usa para determinar o sucesso da transação.

Expressão de critérios de sucesso Expressão válida? Valor txProviderStatus do proxy de API Resultado da avaliação
null verdadeiro "200" false
"" false "200" false
" " false "200" false
"sdfsdfsdf" false "200" false
"txProviderStatus =='100'" verdadeiro "200" false
"txProviderStatus =='200'" verdadeiro "200" verdadeiro
"true" verdadeiro "200" verdadeiro
"txProviderStatus=='OK' OR
txProviderStatus=='Not Found' OR
txProviderStatus=='Bad Request'"
verdadeiro "OK" verdadeiro
"txProviderStatus matches '(OK)|(Not Found)|(Bad Request)'" verdadeiro "OK" verdadeiro
"txProviderStatus matches '(OK)|(Not Found)|(Bad Request)'" verdadeiro "Not Found" verdadeiro
"txProviderStatus matches '(OK)|(Not Found)|(Bad Request)'" verdadeiro "Bad Request" verdadeiro
"(txProviderStatus?:'') matches '(?i)(OK)|(Not Found)|(Bad Request)'" verdadeiro "Bad Request" verdadeiro
"(txProviderStatus?:'') matches '(?i)(OK)|(Not Found)|(Bad Request)'" verdadeiro null false
"txProviderStatus matches '(?i)(OK)|(Not Found)|(Bad Request)'" verdadeiro "bad request" verdadeiro
"txProviderStatus matches '(?i)(OK)|(Not Found)|(Bad Request)'" verdadeiro "Redirect" false
"txProviderStatus matches '(?i)(OK)|(Not Found)|(Bad Request)'" verdadeiro "heeeelllooo" false
"txProviderStatus matches '(?i)(OK)|(Not Found)|(Bad Request)'" verdadeiro null false
"txProviderStatus == 100" verdadeiro "200" false