Pular para o conteúdo principal

API Reference - Events Ingestion

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

API Reference - Meters Creation

Explore a documentação completa da API para criar medidores e teste interativamente as 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:
1

Configure Basic Information

Configure os detalhes fundamentais do seu medidor.
​
Meter Name
string
obrigatório
Escolha um nome claro e descritivo que identifique o que esse medidor monitora.Exemplos: “Tokens”, “Chamadas de API”, “Uso de Armazenamento”, “Horas de Computação”
​
Description
string
Forneça uma explicação detalhada do que esse medidor mede.Exemplo: “Conta cada requisição POST /v1/orders feita pelo cliente”
​
Event Name
string
obrigatório
Especifique o identificador de evento que acionará esse 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 de eventos diferenciam maiúsculas de minúsculas.
2

Configure Aggregation Settings

Defina como o medidor calcula o uso com base em seus eventos.
​
Aggregation Type
string
obrigatório
Selecione como os eventos devem ser agregados:
Conta simplesmente o número de eventos recebidos.Caso de uso: chamadas de API, visualizações de página, uploads de arquivosCálculo: Número total de eventos
​
Over Property
string
O nome da propriedade nos metadados do evento para agregar.
Este campo é obrigatório ao usar os tipos de agregação Soma, Máximo ou Último.
​
Measurement Unit
string
obrigatório
Defina o rótulo da unidade para exibição em relatórios e faturamento.Exemplos: “chamadas”, “GB”, “horas”, “tokens”
3

Configure Event Filtering (Optional)

Configure critérios para controlar quais eventos são incluídos no medidor.
O filtro de eventos permite criar 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ário 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:
Todas as condições devem ser verdadeiras para que um evento seja contado. Use isso quando precisar que eventos satisfaçam vários critérios rigorosos simultaneamente.Exemplo: Conte chamadas de API onde user_tier = "premium" E endpoint = "/api/v2/users"
Configurando Condições de Filtro
1

Add Condition

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

Configure Property Key

Especifique o nome da propriedade nos metadados do seu evento.
3

Select Comparator

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
4

Set Comparison Value

Defina o valor alvo para comparação.
5

Add Groups

Use Adicionar grupo para criar grupos adicionais de condições para lógica complexa.
Propriedades filtradas devem estar incluídas nos metadados do seu evento para que as condições funcionem corretamente. Eventos sem as propriedades obrigatórias serão excluídos da contagem.
4

Create Meter

Revise a configuração do seu 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:
1

Choose Usage-Based Billing Product Type

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

Select Associated Meter

Clique em Medidor Associado para abrir o painel de seleção de medidores na lateral.Este painel permite configurar quais medidores acompanharão o uso deste produto.
3

Add Your Meter

No painel de seleção de medidores:
  1. Clique em Adicionar Medidores para visualizar os medidores disponíveis
  2. Selecione o medidor que você criou na lista suspensa
  3. O medidor selecionado aparecerá na configuração do seu produto
4

Configure Price Per Unit

Defina o preço para cada unidade de uso monitorada pelo seu medidor.
​
Price Per Unit
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 × 0,50=0,50 = 500,00 cobrados
  • 500 unidades consumidas = 500 × 0,50=0,50 = 250,00 cobrados
  • 100 unidades consumidas = 100 × 0,50=0,50 = 50,00 cobrados
5

Set Free Threshold (Optional)

Configure uma franquia de uso gratuita antes de iniciar o faturamento.
​
Free Threshold
number
Número de unidades que os clientes podem consumir sem custo antes de o cálculo de uso pago começar.Como funciona:
  • Limite gratuito: 100 unidades
  • Preço por unidade: $0,50
  • Uso do cliente: 250 unidades
  • Cálculo: (250 - 100) × 0,50=∗∗0,50 = **75,00** cobrados
Limites gratuitos são ideais para modelos freemium, períodos de avaliação ou fornecer aos clientes uma franquia base incluída em seu plano.
O limite gratuito se aplica a cada ciclo de faturamento, dando aos clientes franquias renovadas mensalmente ou conforme seu cronograma de cobrança.
6

Save Configuration

Revise a configuração do medidor e dos preços, depois 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 para seu medidor serão rastreados e agregados
  • Os cálculos de cobrança aplicarão automaticamente suas regras de preço
  • Os clientes serão cobrados com base no consumo real em cada ciclo de faturamento
Lembre-se de que você pode adicionar até 10 medidores por produto, permitindo um acompanhamento 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 em todos os eventos.
​
customer_id
string
obrigatório
O ID de cliente da Dodo Payments ao qual este uso deve ser atribuído.
​
event_name
string
obrigatório
O nome do evento que corresponde à configuração do seu medidor. Nomes de evento acionam o medidor apropriado.
​
timestamp
string
Timestamp ISO 8601 quando o evento ocorreu. O padrão é o horário atual se não fornecido.
​
metadata
object
Propriedades adicionais para filtragem e agregação. Inclua quaisquer valores referenciados em seu “Over Property” ou nas condições de filtro do medidor.

​
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_PAYMENTS_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:
​
Current Month
metric
Mostra a atividade de uso para o período de cobrança atual, ajudando você a entender os padrões mensais de consumo.
​
All Time
metric
Exibe estatísticas cumulativas de uso desde que você começou a rastrear, fornecendo insights de crescimento em 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

Gráfico de quantidades do medidor mostrando tendências de uso ao longo do tempo com visualização em gradiente roxo
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 volume de uso e no período de tempo selecionado, proporcionando visibilidade clara tanto para pequenas flutuações quanto para 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
Essa visualização permite rastrear e monitorar eventos de uso individuais em toda a base de clientes, proporcionando transparência nos cálculos de faturamento e nos 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

​
Customer Email
string
Endereço de e-mail do cliente para identificação.
​
Subscription ID
string
Identificador único da assinatura do cliente.
​
Free Threshold
number
Número de unidades gratuitas incluídas no plano do cliente antes que as cobranças sejam aplicadas.
​
Price Per Unit
currency
O custo por unidade para uso além do limite gratuito.
​
Last Event
timestamp
Timestamp do evento de uso mais recente do cliente.
​
Total Price
currency
Valor total cobrado do cliente pelo faturamento baseado em uso.
​
Consumed Units
number
Número total de unidades que o cliente consumiu.
​
Chargeable Units
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.
Cenário: Acompanhar o número total de solicitações de APIConfiguração do medidor:
  • Nome do evento: api.call
  • Tipo de agregação: Count
  • 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 do cliente
Cenário: Cobrar com base no total de bytes transferidosConfiguração do medidor:
  • Nome do evento: data.transfer
  • Tipo de agregação: Sum
  • 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 do cliente
Cenário: Cobrar com base na maior contagem de usuários simultâneosConfiguração do medidor:
  • Nome do evento: concurrent.users
  • Tipo de agregação: Max
  • 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 do cliente

​
Exemplos de Filtragem de Eventos

Conte 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 do filtro seriam contados. Eventos com outros endpoints seriam ignorados.

​
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:
  1. Verifique a entrega de eventos na aba de análise de Eventos
  2. Verifique se a configuração do medidor corresponde à estrutura do seu evento
  3. Valide IDs de clientes e autenticação da API
  4. Revise as condições de filtragem e configurações de agregação

​
Soluções e Correções

Causas comuns:
  • O nome do evento não corresponde exatamente à configuração do medidor
  • As condições de filtragem do evento estão excluindo seus eventos
  • O ID de cliente não existe na sua conta Dodo Payments
  • O timestamp do evento está fora do período atual de cobrança
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 estão recentes e corretamente formatados
Causas comuns:
  • O nome da Over Property não corresponde às chaves dos metadados do evento
  • Valores de metadados estão com o tipo de dado incorreto (string vs número)
  • Faltando propriedades de metadados obrigatórias
Soluções:
  • Garanta que as chaves dos metadados correspondam exatamente à configuração Over Property
  • Converta strings numéricas em números reais nos seus eventos
  • Inclua todas as propriedades obrigatórias em cada evento
Causas comuns:
  • Nomes das propriedades de filtro não correspondem aos metadados do evento
  • Comparador incorreto para o tipo de dado (string vs número)
  • Sensibilidade a maiúsculas/minúsculas em comparações de string
Soluções:
  • Verifique novamente se os nomes das propriedades correspondem exatamente
  • Use comparadores apropriados para seus tipos de dados
  • Considere a sensibilidade a maiúsculas/minúsculas ao filtrar strings