Guia de Integração de Cobrança Baseada em Uso

Referência da API - Ingestão de Eventos

Acesse a documentação completa da API para ingestão de eventos de uso e teste interativamente solicitações e respostas de ingestão de eventos.

Referência da API - Criação de Medidores

Explore a documentação completa da API para criar medidores e teste interativamente solicitações e respostas de criação de medidores.

Criando um Medidor

Os medidores definem como seus eventos de uso são agregados e medidos para fins de cobrança. Antes de criar um medidor, planeje sua estratégia de rastreamento de uso:

Identifique quais eventos de uso você deseja rastrear
Determine como os eventos devem ser agregados (contagem, soma, etc.)
Defina quaisquer requisitos de filtragem para casos de uso específicos

Passo a Passo para Criação de Medidores

Siga este guia abrangente para configurar seu medidor de uso:

Configurar Informações Básicas

Configure os detalhes fundamentais para seu medidor.

Nome do Medidor

string

obrigatório

Escolha um nome claro e descritivo que identifique o que este medidor rastreia.Exemplos: “Tokens”, “Chamadas de API”, “Uso de Armazenamento”, “Horas de Computação”

Descrição

string

Forneça uma explicação detalhada do que este medidor mede.Exemplo: “Conta cada solicitação POST /v1/orders feita pelo cliente”

Nome do Evento

string

obrigatório

Especifique o identificador do evento que acionará este medidor.Exemplos: “token”, “api.call”, “storage.usage”, “compute.session”

O nome do evento deve corresponder exatamente ao que você envia em seus eventos de uso. Os nomes dos eventos são sensíveis a maiúsculas e minúsculas.

Configurar Configurações de Agregação

Defina como o medidor calcula o uso a partir de seus eventos.

Tipo de Agregação

string

obrigatório

Selecione como os eventos devem ser agregados:

Contagem
Soma
Máximo
Último

Simplesmente conta o número de eventos recebidos.Caso de uso: chamadas de API, visualizações de página, uploads de arquivosCálculo: Total de eventos

Sobre a Propriedade

string

O nome da propriedade dos metadados do evento para agregar.

Este campo é obrigatório ao usar os tipos de agregação Soma, Máximo ou Último.

Unidade de Medida

string

obrigatório

Defina o rótulo da unidade para exibição em relatórios e cobrança.Exemplos: “chamadas”, “GB”, “horas”, “tokens”

Configurar Filtragem de Eventos (Opcional)

Configure critérios para controlar quais eventos estão incluídos no medidor.

A filtragem de eventos permite que você crie regras sofisticadas que determinam quais eventos contribuem para seus cálculos de uso. Isso é útil para excluir eventos de teste, filtrar por níveis de usuários ou focar em ações específicas.

Ativar Filtragem de EventosAtive Ativar Filtragem de Eventos para ativar o processamento condicional de eventos.Escolher Lógica de FiltroSelecione como várias condições são avaliadas:

Lógica AND
Lógica OR

Todas as condições devem ser verdadeiras para que um evento seja contado. Use isso quando precisar que os eventos atendam a vários critérios rigorosos simultaneamente.Exemplo: Contar chamadas de API onde user_tier = "premium" E endpoint = "/api/v2/users"

Pelo menos uma condição deve ser verdadeira para que um evento seja contado. Use isso quando quiser incluir eventos que atendam a qualquer um de vários critérios.Exemplo: Contar eventos onde method = "POST" OU method = "PUT" OU method = "DELETE"

Configurando Condições de Filtro

Adicionar Condição

Clique em Adicionar condição para criar uma nova regra de filtro.

Configurar Chave de Propriedade

Especifique o nome da propriedade dos metadados do seu evento.

Selecionar Comparador

Escolha entre os operadores disponíveis:

equals - Correspondência exata
not equals - Filtro de exclusão
greater than - Comparação numérica
greater than or equals - Comparação numérica (inclusiva)
less than - Comparação numérica
less than or equals - Comparação numérica (inclusiva)
contains - String contém substring
does not contain - Filtro de exclusão de string

Definir Valor de Comparação

Defina o valor alvo para comparação.

Adicionar Grupos

Use Adicionar Grupo para criar grupos de condições adicionais para lógica complexa.

As propriedades filtradas devem estar incluídas nos metadados do seu evento para que as condições funcionem corretamente. Eventos que não possuem as propriedades necessárias serão excluídos da contagem.

Criar Medidor

Revise sua configuração de medidor e clique em Criar Medidor.

Seu medidor agora está pronto para receber e agregar eventos de uso.

Vinculando Medidor a um Produto

Depois de criar seu medidor, você precisa vinculá-lo a um produto para habilitar a cobrança baseada em uso. Este processo conecta os dados de uso do seu medidor às regras de preços para a cobrança do cliente. Vincular medidores a produtos estabelece a conexão entre rastreamento de uso e cobrança:

Produtos definem regras de preços e comportamento de cobrança
Medidores fornecem dados de uso para cálculos de cobrança
Vários medidores podem ser vinculados a um único produto para cenários de cobrança complexos

Processo de Configuração do Produto

Transforme seus dados de uso em cobranças faturáveis configurando corretamente as configurações do seu produto:

Escolher Tipo de Produto Baseado em Uso

Navegue até sua página de criação ou edição de produto e selecione Baseado em Uso como o tipo de produto.

Selecionar Medidor Associado

Clique em Medidor Associado para abrir o painel de seleção de medidores na lateral.Este painel permite que você configure quais medidores rastrearão o uso para este produto.

Adicionar Seu Medidor

No painel de seleção de medidores:

Clique em Adicionar Medidores para visualizar os medidores disponíveis
Selecione o medidor que você criou na lista suspensa
O medidor selecionado aparecerá na configuração do seu produto

Configurar Preço por Unidade

Defina o preço para cada unidade de uso rastreada pelo seu medidor.

Preço por Unidade

number

obrigatório

Defina quanto cobrar por cada unidade medida pelo seu medidor.Exemplo: Definir $0.50 por unidade significa:

1.000 unidades consumidas = 1.000 × R $0,50 = R$ 500,00 cobrados
500 unidades consumidas = 500 × R $0,50 = R$ 250,00 cobrados
100 unidades consumidas = 100 × R $0,50 = R$ 50,00 cobrados

Definir Limite Gratuito (Opcional)

Configure uma cota de uso gratuita antes que a cobrança comece.

Limite Gratuito

number

Número de unidades que os clientes podem consumir sem cobrança antes que o cálculo de uso pago comece.Como funciona:

Limite gratuito: 100 unidades
Preço por unidade: $0,50
Uso do cliente: 250 unidades
Cálculo: (250 - 100) × $0,50 = **$ 75,00** cobrados

Limites gratuitos são ideais para modelos freemium, períodos de teste ou para fornecer aos clientes uma cota base incluída em seu plano.

O limite gratuito se aplica a cada ciclo de cobrança, dando aos clientes novas cotas mensalmente ou de acordo com seu cronograma de cobrança.

Salvar Configuração

Revise sua configuração de medidor e preços, em seguida clique em Salvar Alterações para finalizar a configuração.

Seu produto agora está configurado para cobrança baseada em uso e cobrará automaticamente os clientes com base em seu consumo medido.

O que acontece a seguir:

Eventos de uso enviados ao seu medidor serão rastreados e agregados
Cálculos de cobrança aplicarão suas regras de preços automaticamente
Os clientes serão cobrados com base no consumo real durante cada ciclo de cobrança

Lembre-se de que você pode adicionar até 10 medidores por produto, permitindo rastreamento sofisticado de uso em várias dimensões, como chamadas de API, armazenamento, tempo de computação e métricas personalizadas.

Enviando Eventos de Uso

Uma vez que seu medidor esteja configurado, você pode começar a enviar eventos de uso de sua aplicação para rastrear o uso do cliente.

Estrutura do Evento

Cada evento de uso deve incluir estes campos obrigatórios:

event_id

string

obrigatório

Identificador único para este evento específico. Deve ser único entre todos os eventos.

customer_id

string

obrigatório

O ID do cliente Dodo Payments ao qual este uso deve ser atribuído.

event_name

string

obrigatório

O nome do evento que corresponde à sua configuração de medidor. Nomes de eventos acionam o medidor apropriado.

timestamp

string

Timestamp ISO 8601 quando o evento ocorreu. Padrão para o horário atual se não fornecido.

metadata

object

Propriedades adicionais para filtragem e agregação. Inclua quaisquer valores referenciados na “Sobre a Propriedade” do seu medidor ou nas condições de filtragem.

Exemplos da API de Eventos de Uso

Envie eventos de uso para seus medidores configurados usando a API de Eventos:

const response = await fetch('https://test.dodopayments.com/events/ingest', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.DODO_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    events: [
      {
        event_id: "api_call_1234",
        customer_id: "cus_atXa1lklCRRzMicTqfiw2", 
        event_name: "api.call",
        timestamp: new Date().toISOString(),
        metadata: {
          endpoint: "/v1/orders",
          method: "POST",
          response_size: 1024
        }
      }
    ]
  })
});

Análise de Cobrança Baseada em Uso

Monitore e analise seus dados de cobrança baseada em uso com um painel de análise abrangente. Rastreie padrões de consumo dos clientes, desempenho dos medidores e tendências de cobrança para otimizar sua estratégia de preços e entender comportamentos de uso.

Análise Geral

A aba Geral fornece uma visão abrangente do desempenho da sua cobrança baseada em uso:

Métricas de Atividade

Rastreie estatísticas de uso chave em diferentes períodos de tempo:

Mês Atual

metric

Mostra a atividade de uso para o período de cobrança atual, ajudando você a entender os padrões de consumo mensal.

Todo o Tempo

metric

Exibe estatísticas cumulativas de uso desde que você começou a rastrear, fornecendo insights de crescimento a longo prazo.

Use o seletor de período de tempo para comparar o uso em diferentes meses e identificar tendências sazonais ou padrões de crescimento.

Gráfico de Quantidades de Medidores

O gráfico de quantidades de medidores visualiza tendências de uso ao longo do tempo com os seguintes recursos:

Visualização de séries temporais: Rastreie padrões de uso ao longo de dias, semanas ou meses
Suporte a múltiplos medidores: Veja dados de diferentes medidores simultaneamente
Análise de tendências: Identifique picos de uso, padrões e trajetórias de crescimento

O gráfico se ajusta automaticamente com base no seu volume de uso e no intervalo de tempo selecionado, proporcionando visibilidade clara tanto em pequenas flutuações quanto em grandes mudanças de uso.

Análise de Eventos

Tabela de eventos mostrando nomes de eventos, IDs e controles de paginação para análise detalhada de eventos

A aba de Eventos fornece visibilidade granular sobre eventos de uso individuais:

Exibição de Informações do Evento

A tabela de eventos fornece uma visão clara dos eventos de uso individuais com as seguintes colunas:

Nome do Evento: A ação ou gatilho específico que gerou o evento de uso
ID do Evento: Identificador único para cada instância de evento
ID do Cliente: O cliente associado ao evento
Timestamp: Quando o evento ocorreu

Esta visualização permite que você rastreie e monitore eventos de uso individuais em sua base de clientes, proporcionando transparência nos cálculos de cobrança e padrões de uso.

Análise de Clientes

A aba de Clientes fornece uma tabela detalhada dos dados de uso dos clientes com as seguintes informações:

Colunas de Dados Disponíveis

Email do Cliente

string

Endereço de e-mail do cliente para identificação.

ID da Assinatura

string

Identificador único para a assinatura do cliente.

Limite Gratuito

number

Número de unidades gratuitas incluídas no plano do cliente antes que as cobranças se apliquem.

Preço por Unidade

currency

O custo por unidade para uso além do limite gratuito.

Último Evento

timestamp

Timestamp do evento de uso mais recente do cliente.

Preço Total

currency

Valor total cobrado ao cliente pela cobrança baseada em uso.

Unidades Consumidas

number

Número total de unidades que o cliente consumiu.

Unidades Cobráveis

number

Número de unidades que excedem o limite gratuito e estão sendo cobradas.

Recursos da Tabela

Filtragem de Colunas: Use o recurso “Editar Colunas” para mostrar/ocultar colunas de dados específicas
Atualizações em Tempo Real: Os dados de uso refletem as métricas de consumo mais atuais

Exemplos de Agregação

Aqui estão exemplos práticos de como diferentes tipos de agregação funcionam:

Entendendo Tipos de Agregação

Diferentes tipos de agregação atendem a diferentes cenários de cobrança. Escolha o tipo certo com base em como você deseja medir e cobrar pelo uso.

Exemplos de Implementação Prática

Estes exemplos demonstram aplicações do mundo real de cada tipo de agregação com eventos de exemplo e resultados esperados.

Agregação de Contagem - Chamadas de API

Cenário: Rastrear o número total de solicitações de APIConfiguração do Medidor:

Nome do Evento: api.call
Tipo de Agregação: Contar
Unidade de Medida: calls

Eventos de Exemplo:

{
  "events": [
    {"event_id": "call_1", "customer_id": "cus_123", "event_name": "api.call"},
    {"event_id": "call_2", "customer_id": "cus_123", "event_name": "api.call"},
    {"event_id": "call_3", "customer_id": "cus_123", "event_name": "api.call"}
  ]
}

Resultado: 3 chamadas cobradas ao cliente

Agregação de Soma - Transferência de Dados

Cenário: Cobrar com base no total de bytes transferidosConfiguração do Medidor:

Nome do Evento: data.transfer
Tipo de Agregação: Soma
Sobre a Propriedade: bytes
Unidade de Medida: GB

Eventos de Exemplo:

{
  "events": [
    {
      "event_id": "transfer_1",
      "customer_id": "cus_123", 
      "event_name": "data.transfer",
      "metadata": {"bytes": 1073741824}
    },
    {
      "event_id": "transfer_2",
      "customer_id": "cus_123",
      "event_name": "data.transfer", 
      "metadata": {"bytes": 536870912}
    }
  ]
}

Resultado: 1,5 GB de transferência total cobrados ao cliente

Agregação de Máximo - Usuários Simultâneos Máximos

Cenário: Cobrar com base na contagem máxima de usuários simultâneosConfiguração do Medidor:

Nome do Evento: concurrent.users
Tipo de Agregação: Máx
Sobre a Propriedade: count
Unidade de Medida: users

Eventos de Exemplo:

{
  "events": [
    {
      "event_id": "peak_1",
      "customer_id": "cus_123",
      "event_name": "concurrent.users", 
      "metadata": {"count": 15}
    },
    {
      "event_id": "peak_2",
      "customer_id": "cus_123",
      "event_name": "concurrent.users",
      "metadata": {"count": 23}
    },
    {
      "event_id": "peak_3",
      "customer_id": "cus_123",
      "event_name": "concurrent.users",
      "metadata": {"count": 18}
    }
  ]
}

Resultado: 23 usuários simultâneos máximos cobrados ao cliente

Exemplos de Filtragem de Eventos

Filtrar por Endpoint de API
Filtrar por Faixa de Valores
Filtros Complexos de Múltiplas Condições

Contar apenas chamadas de API para endpoints específicos:Configuração do Filtro:

Propriedade: endpoint
Comparador: equals
Valor: /v1/orders

Evento de Exemplo:

{
  "event_id": "call_1",
  "customer_id": "cus_123",
  "event_name": "api.call",
  "metadata": {
    "endpoint": "/v1/orders",
    "method": "POST"
  }
}

Resultado: Eventos que correspondem aos critérios de filtro seriam contados. Eventos com endpoints diferentes seriam ignorados.

Contar apenas uploads de arquivos grandes:Configuração do Filtro:

Propriedade: file_size
Comparador: greater_than
Valor: 1048576 (1MB em bytes)

Evento de Exemplo:

{
  "event_id": "upload_1",
  "customer_id": "cus_123", 
  "event_name": "file.upload",
  "metadata": {
    "file_size": 5242880,
    "file_type": "image"
  }
}

Resultado: Arquivos maiores que 1MB seriam contados. Arquivos menores seriam ignorados.

Contar chamadas de API premium durante o horário comercial:Configuração do Filtro (usando lógica AND):

Propriedade: plan_type, Comparador: equals, Valor: premium
Propriedade: hour, Comparador: greater_than_or_equal, Valor: 9
Propriedade: hour, Comparador: less_than, Valor: 17

Evento de Exemplo:

{
  "event_id": "call_1",
  "customer_id": "cus_123",
  "event_name": "api.call",
  "metadata": {
    "plan_type": "premium",
    "hour": 14,
    "endpoint": "/v1/analytics"
  }
}

Resultado: Chamadas de API premium durante o horário comercial (9h - 17h) seriam contadas.

Resolução de Problemas

Resolva problemas comuns com a implementação de cobrança baseada em uso e garanta rastreamento e cobrança precisos.

Problemas Comuns

A maioria dos problemas de cobrança baseada em uso se enquadra nas seguintes categorias:

Problemas de entrega e processamento de eventos
Problemas de configuração de medidores
Erros de tipo de dados e formatação
Problemas de ID de cliente e autenticação

Passos de Depuração

Ao solucionar problemas de cobrança baseada em uso:

Verifique a entrega de eventos na aba de análise de Eventos
Verifique se a configuração do medidor corresponde à estrutura do seu evento
Valide IDs de clientes e autenticação da API
Revise as condições de filtragem e configurações de agregação

Soluções e Correções

Eventos não aparecendo no medidor

Causas comuns:

O nome do evento não corresponde exatamente à configuração do medidor
As condições de filtragem de eventos estão excluindo seus eventos
O ID do cliente não existe na sua conta Dodo Payments
O timestamp do evento está fora do período de cobrança atual

Soluções:

Verifique a ortografia e a sensibilidade a maiúsculas do nome do evento
Revise e teste suas condições de filtragem
Confirme se o ID do cliente é válido e ativo
Verifique se os timestamps dos eventos são recentes e estão formatados corretamente

Agregação não funcionando como esperado

Causas comuns:

O nome da Propriedade não corresponde às chaves dos metadados do evento
Os valores dos metadados estão com o tipo de dado errado (string vs número)
Propriedades de metadados obrigatórias estão faltando

Soluções:

Certifique-se de que as chaves dos metadados correspondam exatamente à sua configuração de Sobre a Propriedade
Converta números em string para números reais em seus eventos
Inclua todas as propriedades necessárias em cada evento

Filtragem não funcionando

Causas comuns:

Os nomes das propriedades de filtro não correspondem aos metadados do evento
Comparador errado para o tipo de dado (string vs número)
Sensibilidade a maiúsculas e minúsculas em comparações de strings

Soluções:

Verifique se os nomes das propriedades correspondem exatamente
Use comparadores apropriados para seus tipos de dados
Considere a sensibilidade a maiúsculas e minúsculas ao filtrar strings

Integration Guides

Cookbooks

Guia de Integração de Cobrança Baseada em Uso

Referência da API - Ingestão de Eventos

Referência da API - Criação de Medidores

Criando um Medidor

Passo a Passo para Criação de Medidores

Vinculando Medidor a um Produto

Processo de Configuração do Produto

Enviando Eventos de Uso

Estrutura do Evento

Exemplos da API de Eventos de Uso

Análise de Cobrança Baseada em Uso

Análise Geral

Métricas de Atividade

Gráfico de Quantidades de Medidores

Análise de Eventos

Exibição de Informações do Evento

Análise de Clientes

Colunas de Dados Disponíveis

Recursos da Tabela

Exemplos de Agregação

Entendendo Tipos de Agregação

Exemplos de Implementação Prática

Exemplos de Filtragem de Eventos

Resolução de Problemas

Problemas Comuns

Passos de Depuração

Soluções e Correções

Integration Guides

Cookbooks

Referência da API - Ingestão de Eventos

Referência da API - Criação de Medidores

​Criando um Medidor

​Passo a Passo para Criação de Medidores

​Vinculando Medidor a um Produto

​Processo de Configuração do Produto

​Enviando Eventos de Uso

​Estrutura do Evento

​Exemplos da API de Eventos de Uso

​Análise de Cobrança Baseada em Uso

​Análise Geral

​Métricas de Atividade

​Gráfico de Quantidades de Medidores

​Análise de Eventos

​Exibição de Informações do Evento

​Análise de Clientes

​Colunas de Dados Disponíveis

​Recursos da Tabela

​Exemplos de Agregação

​Entendendo Tipos de Agregação

​Exemplos de Implementação Prática

​Exemplos de Filtragem de Eventos

​Resolução de Problemas

​Problemas Comuns

​Passos de Depuração

​Soluções e Correções

Criando um Medidor

Passo a Passo para Criação de Medidores

Vinculando Medidor a um Produto

Processo de Configuração do Produto

Enviando Eventos de Uso

Estrutura do Evento

Exemplos da API de Eventos de Uso

Análise de Cobrança Baseada em Uso

Análise Geral

Métricas de Atividade

Gráfico de Quantidades de Medidores

Análise de Eventos

Exibição de Informações do Evento

Análise de Clientes

Colunas de Dados Disponíveis

Recursos da Tabela

Exemplos de Agregação

Entendendo Tipos de Agregação

Exemplos de Implementação Prática

Exemplos de Filtragem de Eventos

Resolução de Problemas

Problemas Comuns

Passos de Depuração

Soluções e Correções