Skip to main content
Eventos são a base da cobrança baseada em uso. Envie eventos quando ações cobradas ocorrerem, e medidores os agregam em cobranças.

API Reference — Events Ingestion

Documentação completa da API com exemplos e códigos de resposta.

Estrutura do Evento

string
obrigatório
Um identificador exclusivo para o evento, usado para detectar eventos duplicados durante novas tentativas. Derive-o da ação, por exemplo, ID do cliente + ação + timestamp, para que um evento repetido mantenha o mesmo ID. Um UUID aleatório novo a cada tentativa permite que o mesmo evento seja contabilizado duas vezes.
string
obrigatório
O ID do cliente da Dodo Payments. Deve ser um cliente existente válido.
string
obrigatório
O tipo de evento que corresponde ao nome do evento do seu meter (diferencia maiúsculas de minúsculas). Exemplos: api.call, image.generated.
string
Timestamp ISO 8601 (UTC). Assume como padrão o horário atual do servidor se omitido. Inclua-o para obter uma cobrança precisa com eventos atrasados ou em lote. Timestamps com mais de 1 hora ou mais de 5 minutos no futuro são rejeitados.
object
Propriedades adicionais para agregação e filtragem. Até 50 chaves; cada chave pode ter até 100 caracteres e cada valor, até 500 caracteres.
  • Valores numéricos: bytes, tokens, duration_ms
  • Filtros: endpoint, method, quality

Enviando Eventos

Envie até 1.000 eventos por solicitação para obter melhor desempenho. A API impõe um limite rígido de 1.000 eventos por solicitação.

Modelos de Ingestão

Padrões de eventos prontos para casos de uso comuns. Comece com um modelo comprovado em vez de construir do zero.

LLM Blueprint

Acompanhe o uso de tokens de IA em OpenAI, Anthropic, Groq, Gemini e mais.

API Gateway Blueprint

Controle requisições da API com filtragem de endpoints e suporte a limitação de taxa.

Object Storage Blueprint

Acompanhe envios de arquivos e consumo de armazenamento para serviços de nuvem.

Stream Blueprint

Meça largura de banda de streaming para vídeo, áudio e dados em tempo real.

Time Range Blueprint

Cobrança por tempo decorrido para funções serverless e instâncias de computação.

View All Blueprints

Veja todos os blueprints disponíveis com guias detalhados de implementação.

Melhores Práticas

Use IDs determinísticos para evitar duplicatas: ${customerId}_${action}_${timestamp}.
Tente novamente em erros 5xx e 429 usando recuo exponencial. Não tente novamente em outros erros 4xx.
Omita os timestamps para eventos em tempo real. Inclua-os para eventos atrasados ou em lote para garantir a precisão.
Acompanhe taxas de sucesso e enfileire eventos com falha para reenvio.

Resolução de Problemas

  • O nome do evento deve corresponder exatamente ao meter (diferencia maiúsculas de minúsculas)
  • O ID do cliente deve existir na sua conta
  • Verifique se os filtros do meter não estão excluindo eventos
  • Verifique se os timestamps são recentes
Verifique se a chave da API está correta e use o formato: Bearer YOUR_API_KEY.
Certifique-se de que todos os campos obrigatórios estejam presentes: event_id, customer_id, event_name.
  • As chaves de metadados devem corresponder exatamente a “Over Property” do meter
  • Use números, não strings: tokens: 150, não tokens: "150"

Próximos Passos

Create Meters

Defina como seus eventos são agregados em quantidades faturáveis com filtros e funções de agregação.

Ingestion Blueprints

Use blueprints prontos para casos comuns como rastreamento de LLM, gateways de API e armazenamento.

Complete Tutorial

Construa um gerador completo de imagens de IA com faturamento baseado em uso do zero.

API Reference

Documentação completa da API com todos os parâmetros, códigos de resposta e testes interativos.
Última modificação em 26 de setembro de 2026