API Reference — Events Ingestion
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
API Gateway Blueprint
Object Storage Blueprint
Stream Blueprint
Time Range Blueprint
View All Blueprints
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"