Você está vendo a documentação do Apigee Edge.
Acesse a
documentação da Apigee X. informações
Introdução
Os relatórios de monetização permitem que você acesse informações de uso e atividades de transação focadas. Por exemplo, é possível determinar quais aplicativos, desenvolvedores, pacotes de produtos de API ou produtos de API tiveram atividade de transação em um determinado período. Com a monetização, é possível gerar relatórios de resumo ou detalhado que rastreiam o uso da API.
Tipos de relatórios de monetização
É possível gerar os seguintes tipos de relatório de monetização.
Relatório | Descrição |
---|---|
Faturamento | Confira a atividade dos desenvolvedores em um único mês de faturamento e se os planos de tarifas foram aplicados corretamente. |
Saldo pré-pago | Confira as recargas de saldo que um desenvolvedor pré-pago fez em um mês de faturamento ou em um mês em aberto para poder reconciliar os pagamentos recebidos do processador de pagamentos. |
Receita | Confira a atividade e a receita gerada por desenvolvedores em um período para analisar o desempenho dos pacotes e produtos de API entre seus desenvolvedores e os aplicativos deles. |
Variância |
Compare a atividade e a receita gerada pelos desenvolvedores em dois períodos. Assim, você pode analisar as tendências crescentes ou decrescentes no desempenho de seus pacotes e produtos de API entre seus desenvolvedores (e os aplicativos deles). |
Sobre a retenção de dados
Na nuvem pública do Apigee Edge, a retenção de dados de monetização é um direito do plano. Consulte os direitos de monetização em https://cloud.google.com/apigee/specsheets. Entre em contato com a equipe de vendas da Apigee se quiser que os dados de monetização sejam retidos além do período de direito. A retenção estendida de dados é ativada no momento da solicitação e não pode ser ativada retroativamente para incluir dados anteriores à janela de retenção original.
Como explorar a página "Relatórios de monetização"
Acesse a página "Relatórios de monetização", conforme descrito abaixo.
Edge
Para acessar a página "Relatórios" na interface do Edge:
- Faça login em apigee.com/edge.
- Selecione Publicação > Monetização > Relatórios na barra de navegação à esquerda.
A página "Relatórios" é exibida.
Como destacado na figura, a página Relatórios permite que você:
- Mostrar informações resumidas de todos os relatórios, incluindo nome e descrição, tipo e período do relatório e data da última modificação
- Configurar um relatório
- Gere e faça o download de um relatório no formato de arquivo CSV ou ZIP
- Editar um relatório
- Excluir um relatório
- Pesquisar na lista de relatórios
Borda clássica (nuvem privada)
Para acessar a página "Relatórios" com a interface clássica do Edge:
- 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. - Selecione Monetização > Relatórios de monetização na barra de navegação superior.
A página "Relatórios" é exibida.
- Visualizar a lista atual de relatórios
- Configurar um relatório
- Gerar e fazer o download de um relatório no formato CSV
- Editar um relatório
- Excluir um relatório
Configurar um relatório
Configure um relatório usando a interface, conforme descrito nas seções a seguir.
Etapas para configurar um relatório
Configure um relatório usando a interface do Edge ou a clássica do Edge.
Edge
Para configurar um relatório usando a interface do usuário do Edge:
- Selecione Publicação > Monetização > Relatórios na barra de navegação à esquerda.
- Clique em + Denunciar.
- Configure os detalhes do relatório definidos na tabela a seguir.
Campo Descrição Nome Nome exclusivo do relatório. Descrição Descrição do relatório. Tipo de relatório Consulte o artigo Tipos de relatórios de monetização. - Configure os demais detalhes do relatório com base no tipo selecionado, conforme descrito nas seguintes seções:
- Depois de inserir as informações nessa janela, você pode fazer o seguinte:
- Clique em Salvar relatório para salvar a configuração dele.
Somente para um relatório detalhado, clique em Enviar job para executar o relatório de forma assíncrona e recuperar os resultados mais tarde. Consulte Como gerar e fazer o download de um relatório para mais informações.
- Clique em Salvar como CSV ou Salvar como ZIP para fazer o download do relatório gerado para sua máquina local como um arquivo de valores separados por vírgulas (CSV) ou um arquivo ZIP compactado contendo o CSV. Os downloads ZIP são recomendados para relatórios grandes e serão feitos de maneira mais eficaz.
Borda clássica (nuvem privada)
Para criar um relatório usando a interface clássica do Edge:
- Selecione Monetização > Relatórios de monetização na barra de navegação superior.
- No menu suspenso, selecione o tipo de relatório que você quer criar. Consulte o artigo Tipos de relatórios de monetização.
- Clique em + Denunciar.
- Configure os detalhes do relatório com base no tipo de faturamento selecionado, conforme descrito nas seguintes seções:
- Depois de inserir as informações nessa janela, você pode fazer o seguinte:
- Clique em Salvar como ... para salvar a configuração do relatório e fazer o download dele mais tarde.
Somente para um relatório detalhado, clique em Enviar job para gerar o relatório de maneira complementar e recuperar os resultados mais tarde. Consulte Como gerar e fazer o download de um relatório para mais informações.
- Clique em Fazer download do CSV para gerar e fazer o download do relatório na sua máquina local como um arquivo de valores separados por vírgulas (CSV) para visualização.
Como configurar um relatório de faturamento
Siga as etapas para configurar um relatório e insira as seguintes informações na página do relatório:
Campo | Descrição |
---|---|
Mês do faturamento |
O mês de faturamento do relatório. |
Nível do relatório |
Nível do relatório. Valores válidos:
|
Pacotes de produtos |
Observação: na IU clássica do Edge, os pacotes de produtos da API são chamados de pacotes de API. Selecione os pacotes de produtos da API que serão incluídos no relatório. Se nenhum for selecionado, todos os pacotes de produtos da API serão incluídos no relatório. O relatório inclui uma linha separada para cada pacote de produtos de API selecionado. Para um relatório de resumo, é possível marcar Não exibir nas opções de exibição do resumo. Nesse caso, o relatório agrega informações de todos os pacotes de produtos de API (ou selecionados) e não lista informações de cada pacote de produtos de API separadamente. |
Produtos |
Selecione os produtos de API a serem incluídos no relatório. Se nenhum for selecionado, todos os produtos da API serão incluídos no relatório. O relatório inclui uma linha separada para cada produto de API selecionado. Para um relatório de resumo, é possível marcar Não exibir nas opções de exibição do resumo. Nesse caso, o relatório agrega informações de todos os desenvolvedores (ou selecionados) e não lista informações de cada um deles separadamente. |
Empresas | Selecione as empresas a serem incluídas no relatório. Se nenhuma for selecionada, todas as empresas serão incluídas no relatório. |
Plano de tarifas |
Planos de tarifa a serem incluídos no relatório. Selecione uma das seguintes opções:
|
Como configurar um relatório de saldo pré-pago
Siga as etapas para configurar um relatório e insira as seguintes informações na página do relatório:Campo | Descrição |
---|---|
Mês do faturamento |
O mês de faturamento do relatório. |
Nível do relatório |
Nível do relatório. Valores válidos:
|
Empresas | Selecione as empresas a serem incluídas no relatório. Se nenhuma for selecionada, todas as empresas serão incluídas no relatório. |
Como configurar um relatório de receita
Siga as etapas para configurar um relatório e insira as seguintes informações na página do relatório:
Campo | Descrição |
---|---|
Período |
Intervalo de datas do relatório. Selecione uma das seguintes opções:
|
Selecionar moeda |
Moeda do relatório. Valores válidos:
|
Nível do relatório |
Nível do relatório. Valores válidos:
|
Pacotes de produtos |
Observação: na IU clássica do Edge, os pacotes de produtos da API são chamados de pacotes de API. Selecione os pacotes de produtos da API que serão incluídos no relatório. Se nenhum for selecionado, todos os pacotes de produtos da API serão incluídos no relatório. O relatório inclui uma linha separada para cada pacote de produtos de API selecionado. Para um relatório de resumo, é possível marcar Não exibir nas opções de exibição do resumo. Nesse caso, o relatório agrega informações de todos os pacotes de produtos de API (ou selecionados) e não lista informações de cada pacote de produtos de API separadamente. |
Produtos |
Selecione os produtos de API a serem incluídos no relatório. Se nenhum for selecionado, todos os produtos da API serão incluídos no relatório. O relatório inclui uma linha separada para cada produto de API selecionado. Para um relatório de resumo, é possível marcar Não exibir nas opções de exibição do resumo. Nesse caso, o relatório agrega informações de todos os desenvolvedores (ou selecionados) e não lista informações de cada um deles separadamente. |
Empresas | Selecione as empresas a serem incluídas no relatório. Se nenhuma for selecionada, todas as empresas serão incluídas no relatório. Para um relatório de resumo, você pode marcar Não exibir na seção "Opções de exibição do resumo". Nesse caso, o relatório agrega informações de todas as empresas (ou selecionadas) e não lista separadamente as informações de cada uma. |
Apps |
Selecione os aplicativos que você quer incluir no relatório. Se nenhum for selecionado, todos os aplicativos serão incluídos no relatório. O relatório inclui uma linha separada para cada aplicativo selecionado. Para um relatório de resumo, você pode marcar Não exibir na seção "Opções de exibição do resumo". Nesse caso, o relatório agrega informações de todos os apps (ou selecionados) e não lista informações de cada um deles separadamente. |
Opções de exibição de resumo |
Ordem na qual as colunas são agrupadas e exibidas no relatório. Selecione um número que indique a ordem relativa dessa seção no agrupamento (1 é o primeiro agrupamento). Por exemplo, os elementos a seguir agrupam o relatório primeiro por pacotes, depois por produtos, depois por desenvolvedores e depois por aplicativos. Se você não quiser exibir uma seção, selecione Não exibir e, em seguida, selecione os campos restantes em ordem. O pedido é atualizado automaticamente quando você altera a ordem relativa de uma seção ou opta por não exibir uma seção no relatório. |
Como incluir atributos personalizados de transação em relatórios de resumo de receita
Com as políticas de registro de transações, é possível capturar dados de atributos personalizados das transações e
incluí-los em relatórios resumidos de receitas. Defina o conjunto padrão de
atributos personalizados incluídos nas tabelas do banco de dados de monetização configurando
a propriedade MINT.SUMMARY_CUSTOM_ATTRIBUTES
para sua organização.
O uso desse recurso requer certa reflexão e planejamento, portanto, analise as considerações abaixo.
Se você for cliente do Cloud, entre em contato com o suporte do Apigee Edge para definir a propriedade. Se você for um cliente do Apigee Edge para nuvem privada, defina a sinalização usando uma solicitação PUT para a API a seguir com credenciais de administrador do sistema.
curl -u email:password -X PUT -H "Content-type:application/xml" http://host:port/v1/o/{myorg} -d \ "<Organization type="trial" name="MyOrganization"> <Properties> <Property name="features.isMonetizationEnabled">true</Property> <Property name="MINT.SUMMARY_CUSTOM_ATTRIBUTES">["partner_id","tax_source"]</Property> <Property name="features.topLevelDevelopersAreCompanies">false</Property> </Properties> </Organization>"
Neste exemplo, a chamada de API ativa o recurso e
adiciona as colunas partner_id
e tax_source
ao
banco de dados de monetização. A matriz de atributos personalizados na chamada de API é codificada para uso em URL.
Considerações para incluir atributos de transação personalizados em relatórios
- Confirme os nomes de atributo que você quer usar antes de criá-los com a API. Esses são nomes de colunas no banco de dados, e os dados de atributos personalizados sempre são armazenados lá.
- Há 10 slots de atributo personalizado disponíveis em cada política de registro de transações, conforme
mostrado na imagem a seguir. Use exatamente os mesmos nomes e posições de atributo para os mesmos
atributos em todos os produtos que serão incluídos nos relatórios. Por exemplo, na política de registro de transações a seguir, os atributos personalizados
partner_id
etax_source
ocupam as caixas 4 e 5, respectivamente. Precisam ser o nome e a posição delas em todas as políticas de registro de transações para que os produtos sejam incluídos nos relatórios.
Para incluir atributos personalizados em um relatório de receita resumida depois de ativar o recurso, use a API Report adicionando transactionCustomAttributes
ao MintCriteria
. Consulte Opções de configuração de critérios.
Como configurar um relatório de variância (descontinuado)
Siga as etapas para configurar um relatório e insira as seguintes informações na página do relatório:
Campo | Descrição |
---|---|
Período |
Intervalo de datas do relatório. Selecione uma das seguintes opções:
|
Pacotes |
Os pacotes de API a serem incluídos no relatório. Selecione uma das seguintes opções:
O relatório inclui uma linha separada para cada pacote de API selecionado. Para um relatório de resumo, você pode marcar "Não mostrar (pacotes)" na seção "Opções de exibição do resumo". Nesse caso, o relatório agrega informações de todos os pacotes de API (ou selecionados) e não lista informações de cada pacote de API separadamente. |
Produtos |
Os produtos de API a serem incluídos no relatório. Selecione uma das seguintes opções:
O relatório inclui uma linha separada para cada produto de API selecionado. Para um relatório de resumo, você tem a opção de marcar "Não exibir (produtos)" na seção "Opções de exibição de resumo". Nesse caso, o relatório agrega informações de todos os produtos de API (ou selecionados) e não lista informações de cada produto de API separadamente. |
Empresas |
As empresas a serem incluídas no relatório. Selecione uma das seguintes opções:
O relatório inclui uma linha separada para cada empresa selecionada. Para um relatório de resumo, você pode marcar "Não mostrar (empresas)" na seção "Opções de exibição do resumo". Nesse caso, o relatório agrega informações de todas as empresas (ou selecionadas) e não lista informações de cada empresa selecionada separadamente. |
Apps |
Os aplicativos a serem incluídos no relatório. Selecione uma das seguintes opções:
O relatório inclui uma linha separada para cada aplicativo selecionado. Para um relatório de resumo, você pode marcar "Não exibir (aplicativos)" na seção "Opções de exibição do resumo". Nesse caso, o relatório agrega informações de todos os apps (ou selecionados) e não lista informações de cada um deles separadamente. |
Moeda |
Moeda do relatório. Valores válidos:
|
Opções de exibição de resumo |
Ordem na qual as colunas são agrupadas e exibidas no relatório. Selecione um número que indique a ordem relativa dessa seção no agrupamento (1 é o primeiro agrupamento). Por exemplo, os elementos a seguir agrupam o relatório primeiro por pacotes, depois por produtos, depois por desenvolvedores e depois por aplicativos. Se você não quiser exibir uma seção, selecione Não exibir e, em seguida, selecione os campos restantes em ordem. O pedido é atualizado automaticamente quando você altera a ordem relativa de uma seção ou opta por não exibir uma seção no relatório. |
Gerar e fazer o download de um relatório
Depois de criar um relatório, você poderá fazer o download dos resultados em formato de arquivo CSV ou ZIP. É possível gerar o arquivo CSV ou ZIP de maneira síncrona ou assíncrona.
Para um relatório síncrono, você executa a solicitação de relatório, e a solicitação fica bloqueada até o servidor de análise retornar uma resposta. No entanto, como um relatório pode precisar processar uma grande quantidade de dados (por exemplo, centenas de GB), um relatório síncrono pode expirar.
O nível do relatório Resumo só oferece suporte à geração síncrona.
Para um relatório assíncrono, você executa a solicitação de relatório e recupera os resultados posteriormente. Veja a seguir algumas situações em que o processamento de consulta assíncrona pode ser uma boa alternativa:
- Análise e criação de relatórios que abrangem períodos longos
- Análise de dados com uma variedade de dimensões de agrupamento e outras restrições que aumentam a complexidade da consulta
- Gerenciamento de consultas quando você perceber que os volumes de dados aumentaram significativamente para alguns usuários ou organizações
Um nível de relatório Detalhado é compatível com a geração assíncrona.
Para gerar e fazer o download de um relatório em formato de arquivo CSV ou ZIP, execute uma das seguintes tarefas:
- Acesse a página "Relatórios".
- Posicione o cursor sobre o relatório que você quer salvar.
Na coluna Modificado, clique em uma destas opções:
- No ícone ou (para um relatório de resumo). O relatório é salvo em um arquivo CSV ou ZIP de forma síncrona.
- Envie job (para um relatório detalhado). O job assíncrono é iniciado.
Monitore o status do job na coluna Modificado.
O ícone do disco aparece quando o relatório está pronto para download:
- Depois que o job for concluído, clique no ícone de disco para fazer o download do relatório.
Confira a seguir um exemplo de arquivo CSV para um relatório resumido do faturamento.
Editar um relatório
Para editar um relatório:
- Acesse a página "Relatórios".
- Posicione o cursor sobre o relatório que você quer editar e clique em no menu de ações.
- Atualize a configuração do relatório conforme necessário.
- Clique em Atualizar relatório para salvar a configuração atualizada.
Como excluir um relatório
Para excluir um relatório:
- Acesse a página "Relatórios".
- Posicione o cursor sobre o relatório que você quer excluir.
- Clique em no menu de ações.
Como gerenciar relatórios de monetização usando a API
As seções a seguir descrevem como gerenciar relatórios de monetização usando a API.
Configurar um relatório usando a API
Para configurar um relatório para uma organização inteira, emita uma solicitação POST para
/organizations/{org_name}/report-definitions
.
Para configurar um relatório para um desenvolvedor específico, emita uma solicitação POST para
/organizations/{org_name}/developers/{dev_id}/report-definitions
, em que
{dev_id}
é a identificação do desenvolvedor.
Ao fazer a solicitação, você precisa especificar o nome e o tipo do relatório. O tipo é
um dos seguintes: BILLING
, REVENUE
, VARIANCE
(descontinuado) ou
PREPAID_BALANCE
. Além disso, é possível especificar critérios na propriedade mintCriteria
que configuram ainda mais o relatório. Há uma grande variedade de critérios que podem ser especificados. Isso oferece muita flexibilidade na configuração do relatório.
Você pode especificar alguns critérios:
- Para um relatório de faturamento ou de saldo pré-pago, o mês de faturamento do relatório.
- Em um relatório de receita, o tipo de transação abordado, como transações de compra, transações de cobrança e reembolsos
- Para um relatório de saldo pré-pago, o desenvolvedor a quem o relatório se aplica
- Em um relatório de receita, os pacotes de produtos (ou pacotes de API), os produtos, os planos de tarifas e os aplicativos da API a que ele se aplica
- Para um relatório de receita ou variação, a moeda aplicável do relatório
- Para faturamento, saldo pré-pago ou relatórios de receita, se é um relatório de resumo ou detalhado
- Para um relatório de resumo de receita, inclua atributos personalizados de transação no relatório
Consulte Opções de configuração de relatório para uma lista completa de critérios de relatório.
O exemplo a seguir cria um relatório de receita que resume a atividade de transações no mês de julho de 2015. O relatório inclui vários tipos de transação especificados na
propriedade transactionTypes
e se aplica especificamente ao pacote de produtos da API Payment e
ao produto da API Payment. Como nenhum desenvolvedor ou aplicativo específico está especificado na definição do relatório, o relatório se aplica a todos os desenvolvedores e aplicativos. Como a propriedade currencyOption
está definida como LOCAL
, cada linha do relatório será exibida usando a moeda do plano de tarifas aplicável. Além disso, a propriedade
groupBy
especifica que as colunas no relatório serão agrupadas na
seguinte ordem: PACKAGE, PRODUCT, Develop, APPLICATION e RATEPLAN (inclui o nome
e o ID do plano de tarifa no relatório).
$ curl -H "Content-Type: application/json" -X POST -d \ '{ "name": "July 2015 revenue report", "description": " July 2015 revenue report for Payment product", "type": "REVENUE", "mintCriteria":{ "fromDate":"2015-07-01 00:00:00", "toDate":"2015-08-01 13:35:00", "showTxDetail":true, "showSummary":true, "transactionTypes":[ "PURCHASE", "CHARGE", "REFUND", "CREDIT", "SETUPFEES", "TERMINATIONFEES", "RECURRINGFEES" ], "monetizationPackageIds":[ "payment" ], "productIds":[ "payment" ], "currencyOption":"LOCAL", "groupBy":[ "PACKAGE", "PRODUCT", "DEVELOPER", "APPLICATION", "RATEPLAN" ] } }' \ "https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/report-definitions" \ -u email:password
A seguir, é criado um relatório de faturamento detalhado que mostra a atividade de um desenvolvedor DEV FIVE para junho de 2015.
$ curl -H "Content-Type:application/json" -X POST -d \ '{ "name": "June billing report, DEV FIVE", "description": "June billing report, DEV FIVE", "type": "BILLING", "mintCriteria":{ "billingMonth": "JUNE", "billingYear": 2015, "showTxDetail":true, "showSummary":false, "currencyOption":"LOCAL" }, "devCriteria":[{ "id":"RtHAeZ6LtkSbEH56", "orgId":"myorg"}] }' \ "https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/developers/5cTWgdUvdr6JW3xU/report-definitions" \ -u email:password
Como acessar as configurações de relatórios usando a API
É possível visualizar uma configuração de relatório específica ou todas as configurações de relatório de uma organização. Também é possível conferir as configurações de relatório de um desenvolvedor.
Para acessar uma configuração de relatório específica de uma organização, emita uma solicitação GET para
/organizations/{org_name}/report-definitions/{report_definition_id}
, em que
{report_definition_id}
é a identificação da configuração específica do relatório (o
ID é retornado na resposta quando você cria a configuração do relatório). Exemplo:
$ curl -H "Accept:application/json" -X GET \ "https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/report-definitions/1f7fa53b-de5a-431d-9438-62131e1396c5" \ -u email:password
Para acessar todas as configurações de relatório da organização, emita uma solicitação GET para
/organizations/{org_name}/report-definitions
.
É possível transmitir os seguintes parâmetros de consulta para filtrar e classificar os resultados:
Parâmetro de consulta | Descrição |
---|---|
all |
Sinalização que especifica se todos os pacotes de produtos da API precisam ser devolvidos. Se definido como false, o número de pacotes de produtos da API retornados por página será definido pelo parâmetro de consulta size . O padrão é false. |
size |
Número de pacotes de produtos da API retornados por página. O padrão é 20. Se o parâmetro de consulta all for definido como true , ele será ignorado. |
page |
Número da página que você quer retornar (se o conteúdo for paginado). Se o parâmetro de consulta all estiver definido como true , ele será ignorado. |
sort |
Campo pelo qual as informações serão classificadas. Se o parâmetro de consulta all for definido como true , ele será ignorado. O valor padrão é UPDATED:DESC . |
Por exemplo, o comando a seguir retorna configurações de relatório para a organização e limita a recuperação a um máximo de cinco configurações de relatório:
$ curl -H "Accept:application/json" -X GET \ "https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/report-definitions?size=5" \ -u email:password
A resposta deve ser semelhante a esta (apenas parte da resposta é exibida):
{ "reportDefinition" : [ { "description" : "Test revenue report", "developer" : null, "id" : "1f7fa53b-de5a-431d-9438-62131e1396c5", "lastModified" : "2015-08-27 15:44:03", "mintCriteria" : { "asXorg" : false, "currencyOption" : "LOCAL", "fromDate" : "2015-07-01 00:00:00", "groupBy" : [ "PACKAGE", "PRODUCT", "DEVELOPER", "APPLICATION", "RATEPLAN" ], "monetizationPackageIds" : [ "payment" ], "productIds" : [ "payment" ], "showRevSharePct" : false, "showSummary" : true, "showTxDetail" : true, "showTxType" : false, "toDate" : "2015-08-01 00:05:00", "transactionTypes" : [ "PURCHASE", "CHARGE", "REFUND", "CREDIT", "SETUPFEES", "TERMINATIONFEES", "RECURRINGFEES" ] }, "name" : "Test revenue report", "organization" : { ... }, "type" : "REVENUE" }, { "description" : "June billing report, DEV FIVE", "developer" : null, "id" : "fedac696-ce57-469b-b62c-a77b535fd0eb", "lastModified" : "2015-08-27 17:13:20", "mintCriteria" : { "asXorg" : false, "billingMonth" : "JUNE", "billingYear" : 2015, "currencyOption" : "LOCAL", "showRevSharePct" : false, "showSummary" : false, "showTxDetail" : true, "showTxType" : false }, "name" : "June billing report, DEV FIVE", "organization" : { ... }, "type" : "BILLING" } ], "totalRecords" : 2 }
Para acessar as configurações de relatório de um desenvolvedor específico, emita uma solicitação GET para
/organizations/{org_name}/developers/{dev_id}/report-definitions
, em que
{dev_id}
é a identificação do desenvolvedor. Ao fazer a solicitação, especifique os parâmetros de consulta descritos acima para filtrar e classificar os dados.
Por exemplo, o código a seguir retorna as configurações de relatório de um desenvolvedor específico e classifica a resposta pelo nome do relatório:
$ curl -H "Accept:application/json" -X GET \ "https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/developers/5cTWgdUvdr6JW3xUreport-definitions?sort=name" \ -u email:password
Atualizar uma configuração de relatório usando a API
Para atualizar a configuração de um relatório, emita uma solicitação PUT para /organizations/{org_name}/report-definitions/{report_definition_id}
, em que {report_definition_id}
é a identificação da configuração de relatório específica. Ao fazer a atualização, você precisa especificar no corpo da solicitação os valores de configuração atualizados e o ID da configuração do relatório. Por exemplo, a solicitação a seguir atualiza o relatório para um relatório de resumo (as propriedades atualizadas estão destacadas):
$ curl -H "Content-Type: application/json" -X PUT -d \ '{ "id": "fedac696-ce57-469b-b62c-a77b535fd0eb", "name": "June billing report, DEV FIVE", "description": "June billing report, DEV FIVE", "type": "BILLING", "mintCriteria":{ "billingMonth": "JUNE", "billingYear": 2015, "showTxDetail":false, "showSummary":true } }' \ "https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/report-definitions/fedac696-ce57-469b-b62c-a77b535fd0eb" \ -u email:password
A resposta deve ser semelhante a esta (apenas parte da resposta é exibida):
{ "description" : "June billing report, DEV FIVE", "developer" : null, "id" : "fedac696-ce57-469b-b62c-a77b535fd0eb", "lastModified" : "2015-08-27 17:47:29", "mintCriteria" : { "asXorg" : false, "billingMonth" : "JUNE", "billingYear" : 2015, "showRevSharePct" : false, "showSummary" : true, "showTxDetail" : false, "showTxType" : false }, "name" : "June billing report, DEV FIVE", "organization" : { ... }, "type" : "BILLING" }
Excluir uma configuração de relatório usando a API
Para excluir uma configuração de relatório, emita uma solicitação DELETE para
/organizations/{org_namer}/report-definitions/{report_definition_id}
, em que
{report_definition_id}
é a identificação da configuração de relatório a ser excluída.
Exemplo:
$ curl -H "Accept:application/json" -X DELETE \ "https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/report-definitions/fedac696-ce57-469b-b62c-a77b535fd0eb" \ -u email:password
Como gerar um relatório usando a API
Depois de configurar um relatório, é possível gerá-lo em formato de arquivo de valores separados por vírgulas (CSV) para visualização.
Para gerar um relatório, envie uma solicitação POST para
organizations/{org_id}/{report_type}
, em que {report_type}
especifica o
tipo de relatório que você quer gerar. Os tipos são:
billing-reports
revenue-reports
prepaid-balance-reports
variance-reports
Por exemplo, para gerar um relatório de faturamento, emita uma solicitação POST para
organizations/{org_name}/billing-reports
.
No corpo da solicitação (para qualquer tipo de relatório), especifique os critérios de pesquisa do relatório. Use as propriedades mintCriteria
para especificar os critérios de pesquisa. Consulte Opções de configuração de critérios para mais detalhes.
Por exemplo, a solicitação a seguir procura um relatório de receita com base em vários critérios, como datas de início e término dos relatórios e tipos de transação.
$ curl -H "Content-Type:application/json" -H "Accept: application/octet-stream" -X POST -d \ '{ "fromDate":"2015-07-01 00:00:00", "toDate":"2015-08-01 13:35:00", "showTxDetail":true, "showSummary":true, "transactionTypes":[ "PURCHASE", "CHARGE", "REFUND", "CREDIT", "SETUPFEES", "TERMINATIONFEES", "RECURRINGFEES" ], "currencyOption":"LOCAL", "groupBy":[ "PACKAGE", "PRODUCT", "DEVELOPER", "APPLICATION", "RATEPLAN"] }' \ "https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/revenue-reports" \ -u email:password
Se encontrado, o relatório de receita será gerado no formato de arquivo CSV. Confira a seguir um exemplo de saída do relatório:
Reporting Period:,From:,2015-07-01, To:,2015-07-31 API Product:,All Developer:,All Application:,All Currency:,Local Type of Report:,Summary Revenue Report Monetization Package,Package ID,API Product,Product ID,Developer Name,Developer ID,Application Name,Application ID,Rate Plan,Plan ID,Currency,Transaction Type,Provider Status,Total Volume,Charged Rate, Location,location,foo_product,foo_product,Apigee,QQ7uxeMGf3w9W08B,my_app,my_app,rate_plan_1,location_rate_plan_1,USD,SETUPFEES,SUCCESS,1,15.0000, Location,location,foo_product,foo_product,BarCompany,barcompany,my_app,my_app,rate_plan_1,location_rate_plan_1,USD,SETUPFEES,SUCCESS,1,15.0000, Location,location,foo_product,foo_product,fremont,fremont,my_app,my_app,rate_plan_1,location_rate_plan_1,USD,SETUPFEES,SUCCESS,1,15.0000, Location,location,foo_product,foo_product,Juan's Taco Shack,juan-s-taco-sha,my_app,my_app,rate_plan_1,location_rate_plan_1,USD,SETUPFEES,SUCCESS,1,15.0000,
Como incluir atributos personalizados do desenvolvedor em relatórios de receita usando a API
Somente para relatórios de receita, você pode incluir atributos personalizados no relatório, se o atributo personalizado estiver definido para o desenvolvedor. Você define atributos personalizados ao adicionar desenvolvedores à sua organização, conforme descrito em Como gerenciar desenvolvedores de apps.
Para incluir atributos personalizados em um relatório de receita, emita uma solicitação POST para
organizations/{org_name}/revenue-reports
e inclua a
matriz devCustomAttributes
no corpo da solicitação:
"devCustomAttributes": [ "custom_attribute1", "custom_attribute2", ... ]
Observação:não especifique os atributos predefinidos MINT_*
e
ADMIN_*
na matriz devCustomAttributes
.
Por exemplo, o exemplo a seguir inclui três atributos personalizados, BILLING_TYPE
, SFID
e ORG_EXT
, no relatório (se definido para o desenvolvedor):
$ curl -H "Content-Type:application/json" -H "Accept: application/octet-stream" -X POST -d \ '{ "fromDate":"2015-07-01 00:00:00", "toDate":"2015-08-01 13:35:00", "showTxDetail":true, "showSummary":true, "transactionTypes":[ "PURCHASE", "CHARGE", "REFUND", "CREDIT", "SETUPFEES", "TERMINATIONFEES", "RECURRINGFEES" ], "currencyOption":"LOCAL", "groupBy":[ "PACKAGE", "PRODUCT", "DEVELOPER", "APPLICATION", "RATEPLAN" ], "devCustomAttributes": [ "BILLING_TYPE", "SFID", "ORG_EXT" ] }' \ "https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/revenue-reports" \ -u email:password
Confira a seguir um exemplo de saída do relatório que inclui valores para os dois atributos personalizados:
Reporting Period:,From:,2015-07-01, To:,2015-07-31 API Product:,All Developer:,All Application:,All Currency:,Local Type of Report:,Summary Revenue Report Monetization Package,Package ID,API Product,Product ID,Developer Name,Developer ID,Application Name,Application ID,Rate Plan,Plan ID,Currency,Transaction Type,Provider Status,Total Volume,Charged Rate,BILLING_TYPE,SFID,ORG_EXT Location,location,foo_product,foo_product,Apigee,QQ7uxeMGf3w9W08B,my_app,my_app,rate_plan_1,location_rate_plan_1,USD,SETUPFEES,SUCCESS,1,15.0000,PREPAID,123,3AA, Location,location,foo_product,foo_product,BarCompany,barcompany,my_app,my_app,rate_plan_1,location_rate_plan_1,USD,SETUPFEES,SUCCESS,1,15.0000,PREPAID,123,3AA, Location,location,foo_product,foo_product,fremont,fremont,my_app,my_app,rate_plan_1,location_rate_plan_1,USD,SETUPFEES,SUCCESS,1,15.0000,PREPAID,123,3AA, Location,location,foo_product,foo_product,Juan's Taco Shack,juan-s-taco-sha,my_app,my_app,rate_plan_1,location_rate_plan_1,USD,SETUPFEES,SUCCESS,1,15.0000,PREPAID,123,3AA,
Como gerar relatórios de atividades de transações usando a API
É possível ver a atividade de transação de uma organização emitindo uma solicitação POST para
/organizations/{org_name}/transaction-search
. Ao fazer a solicitação, você precisa
especificar critérios para a recuperação. Você pode especificar alguns critérios:
- ID de um ou mais produtos de API que tiveram as transações emitidas.
- Mês e ano das transações.
- São os desenvolvedores que emitiram a transação.
- Tipo da transação, como compras e taxas de configuração.
- Status da transação, como sucesso e falha.
Consulte a lista completa de critérios em Opções de configuração de critérios.
Por exemplo, as seguintes transações de devolução emitidas por um desenvolvedor específico para o mês de faturamento junho de 2015:
$ curl -H "Content-Type:application/json" -X POST -d \ '{ "billingMonth": "JUNE", "billingYear": 2015, "devCriteria": [{ "id": "RtHAeZ6LtkSbEH56", "orgId":"myorg"}], "transactionTypes": ["PURCHASE", "CHARGE", "SETUPFEES"], "transactionStatus": ["SUCCESS", "FAILED"] }' "https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/transaction-search \ -u email:password
Também é possível determinar quais aplicativos, desenvolvedores, pacotes de produtos de API ou produtos de API tiveram atividade de transação em um determinado período. Essas informações são mostradas separadamente para cada tipo de objeto. Por exemplo, é possível consultar informações específicas sobre aplicativos que acessam APIs nos seus pacotes de produtos de API monetizados em uma data de início e término específicas.
Para ver informações sobre a atividade de transação, emita uma solicitação GET para um dos seguintes recursos:
Recurso | Retorna |
---|---|
/organizations/{org_name}/applications-with-transactions |
Aplicativos com transações |
/organizations/{org_name}/developers-with-transactions |
Desenvolvedores com transações |
/organizations/{org_name}/products-with-transactions |
Produtos com transações |
/organizations/{org_name}/packages-with-transactions |
Pacotes de produtos de API (ou pacotes de API) com transações |
Ao emitir a solicitação, você precisa especificar como parâmetros de consulta uma data de início e uma data de término para o período. Por exemplo, a solicitação a seguir retorna desenvolvedores com transações durante o mês de agosto de 2015.
$ curl -H "Accept:application/json" -X GET \ "https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/developers-with-transactions?START_DATE=2015-08-01&END_DATE=2015-08-31" \ -u email:password
A resposta deve ser semelhante a esta (apenas parte da resposta é exibida):
{ "developer" : [ { "address" : [ { "address1" : "Dev Five Address", "city" : "Pleasanton", "country" : "US", "id" : "0917f15f-9521-4e69-9376-07aa7b7b32ca", "isPrimary" : true, "state" : "CA", "zip" : "94588" } ], "approxTaxRate" : 0.0900, "billingType" : "POSTPAID", "broker" : false, "developerRole" : [ ], "email" : "dev5@myorg.com", "hasSelfBilling" : false, "id" : "tJZG6broTpGGGeLV", "legalName" : "DEV FIVE", "name" : "Dev Five", "organization" : { ... }, "registrationId" : "dev5", "status" : "ACTIVE", "type" : "UNTRUSTED" }, { "address" : [ { "address1" : "Dev Seven Address", "city" : "Pleasanton", "country" : "US", "id" : "f86d8c9f-6ed1-4323-b050-6adf494096c9", "isPrimary" : true, "state" : "CA", "zip" : "94588" } ], "approxTaxRate" : 0.0900, "billingType" : "POSTPAID", "broker" : false, "developerRole" : [ ], "email" : "dev7@myorg.com", "hasSelfBilling" : false, "id" : "VI3l8m8IPAvJTvjS", "legalName" : "DEV SEVEN", "name" : "Dev Seven", "organization" : { ... }, "registrationId" : "dev7", "status" : "ACTIVE", "type" : "UNTRUSTED" }, ... ] }
Opções de configuração de relatórios para a API
As seguintes opções de configuração de relatório estão disponíveis para a API:
Nome | Descrição | Padrão | Obrigatório? |
---|---|---|---|
name |
O nome do relatório. |
N/A | Sim |
description |
Uma descrição do relatório. |
N/A | Não |
mintCriteria |
Os critérios para configurar um relatório. Consulte Opções de configuração de critérios para mais detalhes. |
N/A | Não |
type |
O tipo do relatório. O papel pode ser um dos seguintes:
|
N/A | Sim |
Opções de configuração de critérios
As opções de configuração a seguir estão disponíveis para relatórios com a propriedade mintCriteria
:
Nome | Descrição | Padrão | Obrigatório? |
---|---|---|---|
appCriteria |
ID e organização de um aplicativo específico a ser incluído no relatório. Se essa propriedade não for especificada, todos os aplicativos serão incluídos no relatório. |
N/A | Não |
billingMonth |
Observação:esta propriedade não é válida para relatórios de receita. Mês de faturamento do relatório, como JULHO. |
N/A | Sim |
billingYear |
Observação:esta propriedade não é válida para relatórios de receita. Ano de faturamento do relatório, como 2015. |
N/A | Sim |
currCriteria |
ID e organização de uma moeda específica a ser incluída no relatório. Se essa propriedade não for especificada, todas as moedas compatíveis serão incluídas no relatório. |
N/A | Não |
currencyOption |
Moeda do relatório. Valores válidos:
|
N/A | Não |
devCriteria |
O ID do desenvolvedor (endereço de e-mail) e o nome da organização de um desenvolvedor específico a ser incluído no relatório. Se essa propriedade não for especificada, todos os desenvolvedores serão incluídos no relatório. Exemplo: "devCriteria":[{ "id":"RtHAeZ6LtkSbEH56", "orgId":"my_org"} ] |
N/A | Não |
devCustomAttributes |
Observação:essa propriedade se aplica somente aos relatórios de receita. Atributos personalizados a serem incluídos no relatório, se definidos para um desenvolvedor. Por exemplo: "devCustomAttributes": [ "custom_attribute1", "custom_attribute2", ... ] Observação:não especifique os atributos predefinidos |
N/A | Não |
fromDate |
Observação:essa propriedade se aplica somente a relatórios de receita, variação e atividade de transação. Data de início do relatório em UTC. |
N/A | Obrigatório para relatórios de receita. Não é necessário para outros tipos de relatório. |
groupBy |
Ordem na qual as colunas são agrupadas no relatório. Valores válidos:
|
N/A | Não |
monetizationPackageId |
É o ID de um ou mais pacotes de produtos da API a serem incluídos no relatório. Se essa propriedade não for especificada, todos os pacotes de produtos da API serão incluídos no relatório. Observação : essa propriedade não é válida ao visualizar a atividade de transação ( |
N/A | Não |
pkgCriteria |
ID e organização de um pacote de produtos de API específico a ser incluído no relatório. Se essa propriedade não for especificada, todos os pacotes de produtos da API serão incluídos no relatório. Essa propriedade pode ser especificada em vez da propriedade Observação : essa propriedade não é válida ao visualizar a atividade de transação ( |
N/A | Não |
prevFromDate |
Observação:essa propriedade se aplica somente aos relatórios de variação. Data de início de um período anterior em UTC. Usado para criar um relatório de um período anterior e comparar com um atual. |
N/A | Não |
prevToDate |
Observação:essa propriedade se aplica somente aos relatórios de variação. Data de término de um período anterior em UTC. Usado para criar um relatório de um período anterior e comparar com um atual. |
N/A | Não |
prodCriteria |
ID e organização de um produto de API específico a ser incluído no relatório. Se essa propriedade não for especificada, todos os produtos da API serão incluídos no relatório. Essa propriedade pode ser especificada em vez da propriedade Observação : essa propriedade não é válida ao visualizar a atividade de transação ( |
N/A | Não |
productIds |
ID de um ou mais produtos da API a serem incluídos no relatório. Se essa propriedade não for especificada, todos os produtos da API serão incluídos no relatório. Os IDs dos produtos da API precisam ser especificados como |
N/A | Não |
pricingTypes |
Tipo de preço do plano de tarifa a ser incluído no relatório. Valores válidos:
Se essa propriedade não for especificada, os planos de tarifas de todos os tipos de preços serão incluídos no relatório. |
N/A | Não |
ratePlanLevels |
Tipo de plano de preços a ser incluído no relatório. Valores válidos:
Se essa propriedade não for especificada, os planos de tarifa padrão e específico do desenvolvedor serão incluídos no relatório. |
N/A | Não |
showRevSharePct |
Sinalização que especifica se o relatório mostra porcentagens de participação na receita. Os valores válidos incluem:
|
N/A | Não |
showSummary |
Sinalização que especifica se o relatório é um resumo. Valores válidos:
|
N/A | Não |
showTxDetail |
Observação:essa propriedade se aplica somente aos relatórios de receita. Sinalização que especifica se o relatório mostra detalhes no nível da transação. Os valores válidos incluem:
|
N/A | Não |
showTxType |
Sinalização que especifica se o relatório mostra o tipo de cada transação. Os valores válidos incluem:
|
N/A | Não |
toDate |
Observação:essa propriedade se aplica somente a relatórios de receita, variação e atividade de transação. Data de término do relatório em UTC. O relatório inclui os dados coletados até o fim do dia antes da data especificada. Os dados coletados na data de término especificada serão excluídos do relatório. Se você quiser expirar um plano de tarifas em 31 de dezembro de 2016, por exemplo, defina o valor de toDate como 01/01/2017. Nesse caso, o relatório incluirá dados até o final do dia, em 31 de dezembro de 2016, e os dados de 1o de janeiro de 2017 serão excluídos. |
N/A | Obrigatório para relatórios de receita. Não é necessário para outros tipos de relatório. |
transactionStatus |
Status das transações a serem incluídas no relatório. Valores válidos:
|
N/A | Não |
transactionCustomAttributes |
Atributos de transação personalizados a serem incluídos nos relatórios resumidos de receita. É necessário ativar esse recurso na sua organização. Consulte Como incluir atributos personalizados de transação em relatórios de resumo de receita. |
N/A | Não |
transactionTypes |
É o tipo de transação a ser incluído no relatório. Valores válidos:
Se essa propriedade não for especificada, todos os tipos de transação serão incluídos no relatório. |
N/A | Não |