> ## Documentation Index > Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt > Use this file to discover all available pages before exploring further. # Medidores > Transforme eventos de uso brutos em quantidades faturáveis com agregação e filtragem. Os medidores convertem eventos brutos em quantidades faturáveis. Eles filtram eventos e aplicam funções de agregação (Count, Sum, Max, Last) para calcular o uso por cliente. Interface de criação de medidor mostrando o nome do evento, tipo de agregação e opções de filtragem ## Recursos da API Crie medidores programaticamente via API. Recupere todos os medidores em sua conta. Obtenha detalhes de um medidor específico por ID. Arquive um medidor para parar de rastrear o uso. Restaure um medidor arquivado para retomar o rastreamento. ## Criando um Medidor Nome descritivo (por exemplo, "API Requests", "Token Usage") Nome exato do evento para corresponder (diferencia maiúsculas/minúsculas). Exemplos: `api.call`, `image.generated` Escolha como os eventos são agregados: * **Count**: Número total de eventos (chamadas de API, uploads) * **Sum**: Some valores numéricos (tokens, bytes) * **Max**: Maior valor no período (usuários máximos) * **Last**: Valor mais recente Chave de metadados para agregar (obrigatória para todos os tipos, exceto Count). Exemplos: `tokens`, `bytes`, `duration_ms` Rótulo da unidade para faturas. Exemplos: `calls`, `tokens`, `GB`, `hours` Filtragem de eventos Adicione condições para filtrar quais eventos são contados: * **Lógica AND**: Todas as condições devem corresponder * **Lógica OR**: Qualquer condição pode corresponder **Comparadores**: igual, diferente, maior que, menor que, contém Ative a filtragem, escolha a lógica, adicione condições com chave de propriedade, comparador e valor. Revise a configuração e clique em **Create Meter**. ## Visualizando Análises Análise de medidor Seu painel de medidores mostra: * **Visão Geral**: Uso total e gráfico de uso * **Eventos**: Eventos individuais recebidos * **Clientes**: Uso e cobranças por cliente ## Cobrança em Créditos em vez de Moeda Por padrão, os medidores cobram os clientes por unidade em dólares (ou na sua moeda configurada). Você pode configurar um medidor para **deduzir de um saldo de créditos** - assim o uso consome créditos em vez de gerar uma cobrança monetária. A dedução baseada em créditos exige um [Credit Entitlement](/features/credit-based-billing) vinculado ao mesmo produto. Crie seu crédito primeiro e, em seguida, vincule-o ao medidor. ### Quando usar dedução baseada em créditos | Cenário | Padrão (moeda) | Baseado em Créditos | | ----------------------------------------------------------------------- | ----------------------------------- | ---------------------------------------------------------- | | Precificação simples por unidade (\$0,01/chamada) | ✅ Melhor opção | Sobrecarga desnecessária | | Pacotes de crédito pré-pagos (compre 10K tokens, use ao longo do tempo) | ❌ Não é possível expressar | ✅ Melhor opção | | Uso incluído em assinatura (plano Pro inclui 100K chamadas) | Possível com limite gratuito | ✅ Melhor – créditos acumulam, expiram e aparecem no portal | | Produtos com múltiplos medidores compartilhando um pool de créditos | ❌ Cada medidor fatura separadamente | ✅ Todos os medidores deduzem de um único saldo | ### Configurando um medidor para deduzir créditos Primeiro, crie um crédito em **Products → Credits**. Defina a unidade (por exemplo, "API Calls", "Tokens"), a precisão e as configurações de ciclo de vida (expiração, rollover, excedente). Consulte o [guia de Faturamento Baseado em Créditos](/features/credit-based-billing) para obter instruções detalhadas. Acesse seu produto baseado em uso e abra a seção de configuração do **Meter**. Clique no botão **+** para anexar um medidor. Configure o nome do evento, o tipo de agregação e a unidade de medição como de costume. Ative **Cobrar uso em Créditos** na configuração do medidor. Isso revela as configurações de crédito: Configuração de medidor com cobrança de uso em créditos ativada Selecione de qual Credit Entitlement este medidor deve deduzir. O número de unidades de uso necessárias para deduzir 1 crédito. Por exemplo: * `1` = cada evento do medidor deduz 1 crédito * `100` = 100 eventos do medidor deduzem 1 crédito * `1000` = 1.000 chamadas de API consomem 1 crédito O **Limite Gratuito** ainda se aplica - eventos abaixo desse limite não deduzem créditos. **Exemplo**: Com um limite gratuito de 1.000 e unidades de medidor por crédito igual a 1: * O cliente usa 2.500 chamadas de API * As primeiras 1.000 são gratuitas * As 1.500 restantes deduzem 1.500 créditos do saldo dele ### Como a dedução de créditos funciona Uma vez configurado, o pipeline de dedução é executado automaticamente: 1. **Os eventos chegam** - Sua aplicação envia eventos de uso por meio da [Event Ingestion API](/features/usage-based-billing/event-ingestion) 2. **O medidor agrega** - os eventos são agregados de acordo com a configuração do medidor (Count, Sum, Max, Last) 3. **Processamento por worker em background** - a cada minuto, um worker busca novos eventos desde o último checkpoint 4. **Créditos são deduzidos** - o uso agregado é convertido em créditos usando a taxa `meter_units_per_credit` e deduzido seguindo a **ordem FIFO** (as concessões mais antigas são consumidas primeiro) 5. **Excesso é monitorado** - se o saldo atingir zero e o excedente estiver ativado, o uso continua e o excedente é tratado conforme o comportamento configurado (perdoado no reset, cobrado na próxima fatura ou levado como déficit) ```mermaid theme={null} flowchart LR A[Usage Event] --> B[Meter Aggregation] B --> C{Credits Available?} C -->|Yes| D[Deduct from Balance] C -->|No| E{Overage Enabled?} E -->|Yes| F[Track Overage] E -->|No| G[Block Usage] D --> H[Update Ledger] F --> H ``` A dedução de créditos é executada de forma assíncrona (a cada \~1 minuto). Pode haver um pequeno atraso entre a ingestão do evento e a dedução no saldo. Projete sua aplicação para lidar com esse atraso - não dependa de verificações de saldo em tempo real para controle de acesso em requisições individuais. ### Vários medidores, um pool de créditos Você pode vincular múltiplos medidores no mesmo produto ao **mesmo Credit Entitlement**. Todos os medidores deduzem de um único saldo compartilhado. **Exemplo**: Uma plataforma de IA com dois medidores: * `text.generation` - 1 crédito por 1.000 tokens * `image.generation` - 10 créditos por imagem Ambos deduzem do mesmo pool "AI Credits". O cliente vê um único saldo unificado em seu portal. Use diferentes taxas `meter_units_per_credit` entre os medidores para expressar custos relativos. Operações caras (geração de imagens) exigem menos unidades de medidor por crédito do que operações baratas (completação de texto). Veja o histórico completo de dedução de créditos de um cliente. Verifique o saldo atual de créditos de um cliente via API. ## Solução de problemas * O nome do evento deve coincidir exatamente (considerando maiúsculas e minúsculas) * Verifique se os filtros do medidor não estão excluindo os eventos * Verifique se os IDs dos clientes existem * Desative temporariamente os filtros para testar * Verifique se a Over Property corresponde exatamente à chave de metadata * Use números, não strings: `tokens: 150` não `"150"` * Inclua as propriedades obrigatórias em todos os eventos * Combine exatamente as maiúsculas e minúsculas * Use os operadores corretos para o tipo de dado * Garanta que os eventos incluam as propriedades filtradas * Verifique a aba Eventos para contar os eventos reais recebidos * Verifique o tipo de agregação (Count vs Sum) * Garanta que os valores sejam numéricos para Sum/Max ## Próximos passos Comece a enviar eventos de uso da sua aplicação para os seus medidores. Use configurações prontas de medidores para casos de uso comuns.