API Reference — Events Ingestion
Documentação completa da API com exemplos e códigos de resposta.
Estrutura do Evento
Required Fields
Required Fields
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.Campos Opcionais
Campos Opcionais
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
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 Unique Event IDs
Use Unique Event IDs
Use IDs determinísticos para evitar duplicatas:
${customerId}_${action}_${timestamp}.Implement Retries
Implement Retries
Tente novamente em erros 5xx e
429 usando recuo exponencial. Não tente novamente em outros erros 4xx.Include Timestamps
Include Timestamps
Omita os timestamps para eventos em tempo real. Inclua-os para eventos atrasados ou em lote para garantir a precisão.
Monitor Delivery
Monitor Delivery
Acompanhe taxas de sucesso e enfileire eventos com falha para reenvio.
Resolução de Problemas
Events not appearing
Events not appearing
- 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
Authentication errors (401)
Authentication errors (401)
Verifique se a chave da API está correta e use o formato:
Bearer YOUR_API_KEY.Validation errors (400)
Validation errors (400)
Certifique-se de que todos os campos obrigatórios estejam presentes:
event_id, customer_id, event_name.Metadata not aggregating
Metadata not aggregating
- As chaves de metadados devem corresponder exatamente a “Over Property” do meter
- Use números, não strings:
tokens: 150, nãotokens: "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.