Fazer ajustes de faturamento

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

Introdução

A monetização permite que você faça ajustes nos detalhes de faturamento. Por exemplo, pode ser necessário aumentar ou diminuir a participação na receita ou as taxas de um determinado mês de faturamento devido a uma discrepância nos seus registros.

Como explorar a página "Ajustes de faturamento"

Acesse a página Ajustes de faturamento, conforme descrito abaixo.

Edge

Para acessar a página "Ajustes de faturamento" usando a IU do Edge:

  1. Faça login em apigee.com/edge.
  2. Selecione Publicar > Monetização > Ajustes de faturamento na barra de navegação à esquerda.

A página Ajustes de faturamento é exibida.

Como destacado na figura, a página Ajustes de faturamento permite:

Borda clássica (nuvem privada)

Para acessar a página "Ajustes de faturamento" 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 Monetização > Ajustes na barra de navegação superior.

A página Ajustes de faturamento permite:

  • Visualizar a lista atual de ajustes de serviço
  • Adicionar um ajuste de faturamento
  • Editar um ajuste de faturamento
  • Pesquisar na lista de ajustes de serviço

Adicionar um ajuste de faturamento

Para adicionar um ajuste de faturamento, faça o seguinte:

  1. Acessar a página "Ajustes de faturamento".
  2. Clique em + Ajuste.
  3. Digite as seguintes informações:
    Campo Descrição
    Nome

    Um nome descritivo que aparecerá no documento de faturamento.

    % de ajuste

    Valor do ajuste, como uma porcentagem positiva ou negativa. Uma porcentagem positiva ajusta a participação na receita ou as taxas na transação de acordo com essa porcentagem. Um ajuste negativo reduz a participação na receita ou as taxas na transação de acordo com essa porcentagem. Insira um número decimal positivo ou negativo com até duas casas decimais.

    Mês do faturamento

    Mês de faturamento do ajuste. Selecione um mês na lista suspensa.

    Tipo de transação

    Tipo de transação à qual você quer aplicar o ajuste. Selecione um valor na lista suspensa:

    • Todas as transações
    • Cobrar (transações do modelo de carregamento)
    • Compra (transações do modelo de participação na receita)
    • Reembolso (transações do modelo de participação na receita)
    Produto

    Produto de API a que você quer aplicar o ajuste. Não é possível aplicar um único ajuste a vários produtos da API. Se for necessário aplicar um ajuste a vários produtos de API, crie um ajuste para cada um deles. Selecione um produto de API no menu suspenso.

    Desenvolvedor

    Desenvolvedor a quem você quer aplicar o ajuste. É possível aplicar o ajuste a todos os desenvolvedores (por padrão) ou a um desenvolvedor específico. Selecione "Todos os desenvolvedores" ou um desenvolvedor específico no menu suspenso.

  4. Clique em Criar ajuste.

Como editar um ajuste de faturamento

Para editar um ajuste de faturamento, faça o seguinte:

  1. Acessar a página "Ajustes de faturamento".
  2. Posicione o cursor sobre o ajuste de faturamento que você quer editar e clique em no menu de ações.
  3. Atualize o ajuste de faturamento, conforme necessário.
  4. Clique em Atualizar ajuste.

Como fazer ajustes de serviço usando a API

As seções a seguir descrevem como fazer ajustes de faturamento usando a API.

Como fazer um ajuste de faturamento usando a API

É possível ajustar os detalhes de faturamento emitindo uma solicitação POST para /organizations/{org_name}/billing-adjustments. Ao fazer a solicitação, você especifica no corpo da solicitação:

  • Nome do ajuste de faturamento.
  • Uma porcentagem de ajuste, ou seja, um valor percentual positivo ou negativo que, respectivamente, aumenta ou reduz a fatura.
  • Mês de faturamento.
  • Ano de faturamento.
  • Organização à qual o ajuste de faturamento é aplicado.

Também é possível especificar outras propriedades, como:

  • Tipo de transação a que você quer aplicar o ajuste (como uma transação de compra).
  • Desenvolvedor a quem você quer aplicar o ajuste.
  • Indica se você quer aplicar o ajuste a desenvolvedores pré-pagos, pós-pagos ou ambos.
  • Pacote de API em que você quer aplicar o ajuste.
  • Produto de API a que você quer aplicar o ajuste.

Consulte Configurações de ajuste de faturamento para conferir uma lista completa das propriedades de ajuste de serviço que podem ser especificadas em uma solicitação de ajuste.

Se uma propriedade opcional não for especificada, o ajuste do documento de faturamento será tudo incluído nessa propriedade. Por exemplo, se nenhum tipo de transação for especificado, o ajuste de faturamento será aplicado a todos eles.

O exemplo a seguir faz um ajuste de serviço para o mês de faturamento aberto, junho de 2013. O ajuste faz uma redução de 3% e é aplicado a transações de compra, ao produto de pagamento e a desenvolvedores pós-pagos. Como as propriedades para identificar um desenvolvedor ou pacote de API específico não estão especificadas, o ajuste será aplicado a todos os desenvolvedores (que são desenvolvedores pós-pagos) e ao produto de pagamento em todos os pacotes de API.

$ curl -H "Content-Type:application/json" -X POST -d \
'{
  "name": "Purchase Adjustment Negative3",
  "adjustmentPercentageFactor": -3,
  "billingMonth": 6,
  "billingYear": 2017,
  "isPublished": false,
  "transactionType": "PURCHASE",
  "developerBillingType": "POSTPAID",
  "organization": {
      "id": "{org_name}" 
  },
  "product": { "id": "payment" }
}' \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/billing-adjustments" \
-u email:password

A resposta deve ser semelhante a esta (apenas parte da resposta é exibida):

{
  "adjustmentPercentageFactor" : -3,
  "billingMonth" : 6,
  "billingYear" : 2017,
  "developerBillingType" : "POSTPAID",
  "id" : "511144db-7fb1-4c74-bafb-5bc7a6380c9c",
  "isPublished" : false,
  "name" : "Purchase Adjustment Negative3",
  "organization" : {
   ...
  },
  "product" : {
    "customAtt1Name" : "user",
    "description" : "Payment",
    "displayName" : "Payment",
    "id" : "payment",
    "name" : "payment",
    "organization" : {
      ...
    },
    "status" : "CREATED",
    "transactionSuccessCriteria" : "Status=='200 OK'"
  },
  "transactionType" : "PURCHASE"
}

Como visualizar ajustes de faturamento usando a API

É possível consultar um ajuste de faturamento específico ou todos os ajustes de faturamento de uma organização. Para conferir um ajuste de faturamento específico, emita uma solicitação GET para /organizations/{org_name}/billing-adjustments/{billing_adjustment_id}, em que {billing_adjustment_id} é a identificação do ajuste específico. O ID é retornado na resposta quando você cria o ajuste. Exemplo:

$ curl -H "Accept:application/json" -X GET \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/billing-adjustments/511144db-7fb1-4c74-bafb-5bc7a6380c9c" \
-u email:password

Para visualizar todos os ajustes de faturamento de uma organização, emita uma solicitação GET para /organizations/{org_name}/billing-adjustments. Exemplo:

$ curl -H "Accept:application/json" -X GET \ 
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/billing-adjustments" \ 
-u email:password

A resposta deve ser semelhante a esta (apenas parte da resposta é exibida):

{
  "billingAdjustment" : [ {
    "adjustmentPercentageFactor" : -3,
    "billingMonth" : 6,
    "billingYear" : 2017,
    "developerBillingType" : "POSTPAID",
    "id" : "511144db-7fb1-4c74-bafb-5bc7a6380c9c",
    "isPublished" : false,
    "name" : "Purchase Adjustment Negative3",
    "organization" : {
      ...
    },
    "product" : {
      "customAtt1Name" : "user",
      "description" : "Payment",
      "displayName" : "Payment",
      "id" : "payment",
      "name" : "payment",
      "organization" : {
        ...
      },
      "status" : "CREATED",
      "transactionSuccessCriteria" : "Status=='200 OK'"
    },
    "transactionType" : "PURCHASE"
  }, {
    "adjustmentPercentageFactor" : 5.0000,
    "billingMonth" : 5,
    "billingYear" : 2017,
    "id" : "53c363c0-7e1d-4dc1-9392-cf86656225f2",
    "isPublished" : false,
    "monetizationPackage" : {
      "description" : "Communications",
      "displayName" : "Communications",
      "id" : "communications",
      "name" : "Communications",
      "organization" : {
       ...
      },
      "product" : [ {
        "customAtt1Name" : "user",
        "description" : "Messaging",
        "displayName" : "Messaging",
        "id" : "messaging",
        "name" : "messaging",
        "organization" : {
          ...
        },
        "status" : "CREATED"
      }, {
        ...
        },
        "status" : "CREATED",
        "transactionSuccessCriteria" : "Status=='200 OK'"
      } ],
      "status" : "CREATED"
    },
    "name" : "Test Package Adjustment",
    "organization" : {
     ...
    },
    "product" : {
      "customAtt1Name" : "user",
      "description" : "Location",
      "displayName" : "Location",
      "id" : "location",
      "name" : "location",
      "organization" : {
        ...
      },
      "status" : "CREATED",
      "transactionSuccessCriteria" : "Status=='200 OK'"
    }
  } ],
  "totalRecords" : 2
}

Como atualizar um ajuste de faturamento usando a API

É possível atualizar um ajuste de faturamento emitindo uma solicitação PUT para /organizations/{org_name}/billing-adjustments/{billing_adjustment_id}, em que {billing_adjustment_id} é a identificação do ajuste de faturamento específico. Ao fazer a atualização, você precisa especificar no corpo da solicitação as propriedades atualizadas e a identificação do ajuste de faturamento a ser atualizado. Também é preciso especificar as propriedades obrigatórias para o ajuste de faturamento, ou seja, as propriedades do nome, porcentagem de ajuste, mês de faturamento, ano de faturamento e organização.

Por exemplo, a seguinte chamada de API atualiza o fator da porcentagem de ajuste e o nome. As propriedades atualizadas estão destacadas no exemplo:

$ curl -H "Content-Type: application/json" -X PUT -d \
'{
  "id" : "511144db-7fb1-4c74-bafb-5bc7a6380c9c ",
  "adjustmentPercentageFactor": -5,
  "name" : "Purchase Adjustment Negative5",
  "billingMonth": 6,
  "billingYear": 2017,
  "isPublished": false,
  "transactionType": "PURCHASE",
  "developerBillingType": "POSTPAID",
  "organization": {
      "id": "{org_name}" 
    },
  "product": { "id": "payment" }
}' \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/billing-adjustments/511144db-7fb1-4c74-bafb-5bc7a6380c9c" \
-u email:password

Como excluir um ajuste de faturamento usando a API

É possível excluir um ajuste de faturamento emitindo uma solicitação DELETE para /organizations/{org_name}/billing-adjustments/{billing_adjustment_id}, em que {billing_adjustment_id} é a identificação do ajuste a ser excluído. Exemplo:

$ curl -H "Accept:application/json" -X GET \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/billing-adjustments/511144db-7fb1-4c74-bafb-5bc7a6380c9c" \
-u email:password

Configurações de ajuste de faturamento para a API

As seguintes opções de configuração estão disponíveis para ajustes de serviço:

Nome Descrição Padrão Obrigatório?
name

Um nome descritivo para o ajuste de faturamento.

N/A Sim
adjustmentPercentageFactor

O valor do ajuste, como uma porcentagem numérica positiva ou negativa. Uma porcentagem positiva ajusta a participação na receita ou as taxas na transação de acordo com essa porcentagem. Uma porcentagem negativa ajusta a participação na receita ou as taxas na transação de acordo com essa porcentagem. Os valores podem variar de -100 a 999,9999.

N/A Sim
billingMonth

O mês de faturamento para o ajuste de faturamento, especificado como um número inteiro. Por exemplo, 11 para dezembro.

N/A Sim
billingYear

O ano de faturamento do ajuste de faturamento, especificado no seguinte formato: AAAA. Por exemplo, 2017.

N/A Sim
organization

A organização a que o ajuste de faturamento se aplica.

N/A Sim
isPublished

Uma sinalização que especifica se o ajuste será publicado. O valor pode ser um dos seguintes:

  • true. O ajuste de serviço será publicado.
  • false. O ajuste de faturamento não será publicado.
N/A Não
transactionType

É o tipo de transações a que o ajuste de faturamento se aplica. O tipo pode ser um dos seguintes:

  • PURCHASE
  • CHARGE
  • REFUND
  • CREDIT
  • BALANCE
  • SETUPFEES
  • TERMINATIONFEES
  • RECURRINGFEES
  • TRUEUPS. São transações usadas para reajustar transações avaliadas. Elas são invocadas quando mudanças nos tributos são feitas no mês de faturamento anterior.
N/A Não
developerBillingType

É o tipo de faturamento do desenvolvedor a que o ajuste de faturamento se aplica. O valor pode ser um dos seguintes:

  • PREPAID.. Desenvolvedores pré-pagos.
  • POSTPAID. Desenvolvedores pós-pagos.
  • BOTH. Desenvolvedores pré e pós-pagos.
N/A Não
product

O produto de API a que o ajuste de faturamento se aplica. Se você não especificar essa propriedade, o ajuste de faturamento será aplicado a todos os produtos da API.

N/A Não
monetizationPackage

O pacote de API a que o ajuste de faturamento se aplica. Se você não especificar essa propriedade, o ajuste de faturamento será aplicado a todos os pacotes de API.

N/A Não
developer

O desenvolvedor a quem o ajuste de faturamento se aplica. Se você não especificar essa propriedade, o ajuste de faturamento será aplicado a todos os desenvolvedores.

.
N/A Não

Próximas etapas

A monetização oferece a flexibilidade de emitir créditos para um desenvolvedor. Talvez seja necessário fazer isso se um desenvolvedor não estiver satisfeito com um serviço e solicitar um reembolso parcial ou total pelo uso por um período. Saiba como emitir crédito em Como emitir créditos.