API Reference — Events Ingestion
Estructura del Evento
Required Fields
Required Fields
string
requerido
Un identificador único para el evento, utilizado para detectar eventos duplicados al reintentar. Derívalo de la acción, por ejemplo, ID de cliente + acción + marca de tiempo, para que un evento reintentado conserve el mismo ID. Un UUID aleatorio nuevo en cada reintento permite que el mismo evento se contabilice dos veces.
string
requerido
El ID de cliente de Dodo Payments. Debe corresponder a un cliente existente válido.
string
requerido
El tipo de evento que coincide con el nombre del evento de tu medidor (distingue entre mayúsculas y minúsculas). Ejemplos:
api.call, image.generated.Optional Fields
Optional Fields
string
Marca de tiempo ISO 8601 (UTC). Si se omite, se utiliza de forma predeterminada la hora actual del servidor. Inclúyela para una facturación precisa con eventos retrasados o por lotes. Se rechazan las marcas de tiempo con más de 1 hora de antigüedad o más de 5 minutos en el futuro.
object
Propiedades adicionales para la agregación y el filtrado. Hasta 50 claves; cada clave puede tener hasta 100 caracteres y cada valor, hasta 500 caracteres.
- Valores numéricos:
bytes,tokens,duration_ms - Filtros:
endpoint,method,quality
Envío de Eventos
Plantillas de Ingesta
Patrones de eventos listos para casos de uso comunes. Comienza con una plantilla probada en lugar de construir desde cero.LLM Blueprint
API Gateway Blueprint
Object Storage Blueprint
Stream Blueprint
Time Range Blueprint
View All Blueprints
Mejores Prácticas
Use Unique Event IDs
Use Unique Event IDs
Usa ID deterministas para evitar duplicados:
${customerId}_${action}_${timestamp}.Implement Retries
Implement Retries
Reintenta ante errores 5xx y errores
429 con retroceso exponencial. No reintentes otros errores 4xx.Include Timestamps
Include Timestamps
Omite las marcas de tiempo para eventos en tiempo real. Inclúyelas para eventos retrasados o por lotes para mayor precisión.
Monitor Delivery
Monitor Delivery
Monitoree las tasas de éxito y encole eventos fallidos para reintentos.
Solución de Problemas
Events not appearing
Events not appearing
- El nombre del evento debe coincidir exactamente con el del medidor (distingue entre mayúsculas y minúsculas)
- El ID de cliente debe existir en tu cuenta
- Comprueba que los filtros del medidor no estén excluyendo eventos
- Verifica que las marcas de tiempo sean recientes
Authentication errors (401)
Authentication errors (401)
Verifica que la clave de API sea correcta y utiliza el formato:
Bearer YOUR_API_KEY.Validation errors (400)
Validation errors (400)
Asegúrate de que estén presentes todos los campos obligatorios:
event_id, customer_id, event_name.Metadata not aggregating
Metadata not aggregating
- Las claves de Metadata deben coincidir exactamente con “Over Property” del medidor
- Usa números, no cadenas:
tokens: 150, notokens: "150"