Pular para o conteúdo principal

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:
1

Configurar Informações Básicas

Configure os detalhes fundamentais para seu medidor.
​
Nome do Medidor
string
required
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
required
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.
2

Configurar Configurações de Agregação

Defina como o medidor calcula o uso a partir de seus eventos.
​
Tipo de Agregação
string
required
Selecione como os eventos devem ser agregados:
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
required
Defina o rótulo da unidade para exibição em relatórios e cobrança.Exemplos: “chamadas”, “GB”, “horas”, “tokens”
3

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:
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"
Configurando Condições de Filtro
1

Adicionar Condição

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

Configurar Chave de Propriedade

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

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
4

Definir Valor de Comparação

Defina o valor alvo para comparação.
5

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.
4

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:
1

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.
2

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.
3

Adicionar Seu Medidor

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

Configurar Preço por Unidade

Defina o preço para cada unidade de uso rastreada pelo seu medidor.
​
Preço por Unidade
number
required
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 = 500,00 cobrados
  • 500 unidades consumidas = 500 × $0,50 = 250,00 cobrados
  • 100 unidades consumidas = 100 × $0,50 = 50,00 cobrados
5

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=∗∗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.
6

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
required
Identificador único para este evento específico. Deve ser único entre todos os eventos.
​
customer_id
string
required
O ID do cliente Dodo Payments ao qual este uso deve ser atribuído.
​
event_name
string
required
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

Gráfico de quantidades de medidores mostrando tendências de uso ao longo do tempo com visualização de 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 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.
Cenário: Rastrear o número total de solicitações de APIConfiguração do Medidor:
  • Nome do Evento: api.call
  • Tipo de Agregação: Contagem
  • 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
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
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áximo
  • 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

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.

​
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 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
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
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