Saltar al contenido principal

Referencia de API - Ingesta de Eventos

Accede a la documentación completa de la API para la ingesta de eventos de uso y prueba interactivamente las solicitudes y respuestas de ingesta de eventos.

Referencia de API - Creación de Medidores

Explora la documentación completa de la API para crear medidores y prueba interactivamente las solicitudes y respuestas de creación de medidores.

​
Creando un Medidor

Los medidores definen cómo se agregan y miden tus eventos de uso para fines de facturación. Antes de crear un medidor, planifica tu estrategia de seguimiento de uso:
  • Identifica qué eventos de uso deseas rastrear
  • Determina cómo deben agregarse los eventos (conteo, suma, etc.)
  • Define cualquier requisito de filtrado para casos de uso específicos

​
Proceso de Creación de Medidores Paso a Paso

Sigue esta guía completa para configurar tu medidor de uso:
1

Configurar Información Básica

Configura los detalles fundamentales para tu medidor.
​
Nombre del Medidor
string
requerido
Elige un nombre claro y descriptivo que identifique lo que este medidor rastrea.Ejemplos: “Tokens”, “Llamadas a la API”, “Uso de Almacenamiento”, “Horas de Cómputo”
​
Descripción
string
Proporciona una explicación detallada de lo que mide este medidor.Ejemplo: “Cuenta cada solicitud POST /v1/orders realizada por el cliente”
​
Nombre del Evento
string
requerido
Especifica el identificador del evento que activará este medidor.Ejemplos: “token”, “api.call”, “storage.usage”, “compute.session”
El nombre del evento debe coincidir exactamente con lo que envías en tus eventos de uso. Los nombres de los eventos son sensibles a mayúsculas y minúsculas.
2

Configurar Ajustes de Agregación

Define cómo el medidor calcula el uso a partir de tus eventos.
​
Tipo de Agregación
string
requerido
Selecciona cómo deben agregarse los eventos:
Simplemente cuenta el número de eventos recibidos.Caso de uso: llamadas a la API, vistas de página, cargas de archivosCálculo: Número total de eventos
​
Sobre la Propiedad
string
El nombre de la propiedad de los metadatos del evento sobre la que se agregará.
Este campo es obligatorio cuando se utilizan tipos de agregación Suma, Máx o Último.
​
Unidad de Medida
string
requerido
Define la etiqueta de unidad para fines de visualización en informes y facturación.Ejemplos: “llamadas”, “GB”, “horas”, “tokens”
3

Configurar Filtrado de Eventos (Opcional)

Configura criterios para controlar qué eventos se incluyen en el medidor.
El filtrado de eventos te permite crear reglas sofisticadas que determinan qué eventos contribuyen a tus cálculos de uso. Esto es útil para excluir eventos de prueba, filtrar por niveles de usuario o enfocarse en acciones específicas.
Habilitar Filtrado de EventosActiva Habilitar Filtrado de Eventos para activar el procesamiento condicional de eventos.Elegir Lógica de FiltradoSelecciona cómo se evalúan múltiples condiciones:
Todas las condiciones deben ser verdaderas para que un evento sea contado. Usa esto cuando necesites que los eventos cumplan múltiples criterios estrictos simultáneamente.Ejemplo: Contar llamadas a la API donde user_tier = "premium" Y endpoint = "/api/v2/users"
Configurando Condiciones de Filtrado
1

Agregar Condición

Haz clic en Agregar condición para crear una nueva regla de filtrado.
2

Configurar Clave de Propiedad

Especifica el nombre de la propiedad de los metadatos de tu evento.
3

Seleccionar Comparador

Elige entre los operadores disponibles:
  • equals - Coincidencia exacta
  • not equals - Filtro de exclusión
  • greater than - Comparación numérica
  • greater than or equals - Comparación numérica (inclusiva)
  • less than - Comparación numérica
  • less than or equals - Comparación numérica (inclusiva)
  • contains - La cadena contiene subcadena
  • does not contain - Filtro de exclusión de cadena
4

Establecer Valor de Comparación

Establece el valor objetivo para la comparación.
5

Agregar Grupos

Usa Agregar Grupo para crear grupos de condiciones adicionales para lógica compleja.
Las propiedades filtradas deben estar incluidas en los metadatos de tu evento para que las condiciones funcionen correctamente. Los eventos que faltan propiedades requeridas serán excluidos del conteo.
4

Crear Medidor

Revisa la configuración de tu medidor y haz clic en Crear Medidor.
Tu medidor ahora está listo para recibir y agregar eventos de uso.

​
Vinculando el Medidor a un Producto

Una vez que hayas creado tu medidor, necesitas vincularlo a un producto para habilitar la facturación basada en el uso. Este proceso conecta los datos de uso de tu medidor con las reglas de precios para la facturación del cliente. Vincular medidores a productos establece la conexión entre el seguimiento de uso y la facturación:
  • Los productos definen las reglas de precios y el comportamiento de facturación
  • Los medidores proporcionan datos de uso para los cálculos de facturación
  • Se pueden vincular múltiples medidores a un solo producto para escenarios de facturación complejos

​
Proceso de Configuración del Producto

Transforma tus datos de uso en cargos facturables configurando correctamente los ajustes de tu producto:
1

Elegir Tipo de Producto de Facturación Basada en el Uso

Navega a tu página de creación o edición de productos y selecciona Basada en el Uso como el tipo de producto.
2

Seleccionar Medidor Asociado

Haz clic en Medidor Asociado para abrir el panel de selección de medidores desde el lado.Este panel te permite configurar qué medidores rastrearán el uso para este producto.
3

Agregar Tu Medidor

En el panel de selección de medidores:
  1. Haz clic en Agregar Medidores para ver los medidores disponibles
  2. Selecciona el medidor que creaste de la lista desplegable
  3. El medidor seleccionado aparecerá en la configuración de tu producto
4

Configurar Precio por Unidad

Establece el precio para cada unidad de uso rastreada por tu medidor.
​
Precio por Unidad
number
requerido
Define cuánto cobrar por cada unidad medida por tu medidor.Ejemplo: Establecer $0.50 por unidad significa:
  • 1,000 unidades consumidas = 1,000 × $0.50 = 500.00 cargados
  • 500 unidades consumidas = 500 × $0.50 = 250.00 cargados
  • 100 unidades consumidas = 100 × $0.50 = 50.00 cargados
5

Establecer Umbral Gratuito (Opcional)

Configura una asignación de uso gratuito antes de que comience la facturación.
​
Umbral Gratuito
number
Número de unidades que los clientes pueden consumir sin cargo antes de que comience el cálculo de uso pagado.Cómo funciona:
  • Umbral gratuito: 100 unidades
  • Precio por unidad: $0.50
  • Uso del cliente: 250 unidades
  • Cálculo: (250 - 100) × 0.50=∗∗0.50 = **75.00** cargados
Los umbrales gratuitos son ideales para modelos freemium, períodos de prueba o para proporcionar a los clientes una asignación base incluida en su plan.
El umbral gratuito se aplica a cada ciclo de facturación, dando a los clientes nuevas asignaciones mensualmente o de acuerdo con tu calendario de facturación.
6

Guardar Configuración

Revisa la configuración de tu medidor y precios, luego haz clic en Guardar Cambios para finalizar la configuración.
Tu producto ahora está configurado para la facturación basada en el uso y cobrará automáticamente a los clientes según su consumo medido.
Qué sucede a continuación:
  • Los eventos de uso enviados a tu medidor serán rastreados y agregados
  • Los cálculos de facturación aplicarán automáticamente tus reglas de precios
  • Los clientes serán cobrados según el consumo real durante cada ciclo de facturación
Recuerda que puedes agregar hasta 10 medidores por producto, lo que permite un seguimiento de uso sofisticado a través de múltiples dimensiones como llamadas a la API, almacenamiento, tiempo de cómputo y métricas personalizadas.

​
Enviando Eventos de Uso

Una vez que tu medidor esté configurado, puedes comenzar a enviar eventos de uso desde tu aplicación para rastrear el uso del cliente.

​
Estructura del Evento

Cada evento de uso debe incluir estos campos requeridos:
​
event_id
string
requerido
Identificador único para este evento específico. Debe ser único entre todos los eventos.
​
customer_id
string
requerido
El ID de cliente de Dodo Payments al que debe atribuirse este uso.
​
event_name
string
requerido
El nombre del evento que coincide con la configuración de tu medidor. Los nombres de los eventos activan el medidor apropiado.
​
timestamp
string
Marca de tiempo ISO 8601 cuando ocurrió el evento. Por defecto es la hora actual si no se proporciona.
​
metadata
object
Propiedades adicionales para filtrado y agregación. Incluye cualquier valor referenciado en la “Sobre Propiedad” de tu medidor o condiciones de filtrado.

​
Ejemplos de API de Eventos de Uso

Envía eventos de uso a tus medidores configurados utilizando la API de Eventos: 
const response = await fetch('https://test.dodopayments.com/events/ingest', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.DODO_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    events: [
      {
        event_id: "api_call_1234",
        customer_id: "cus_atXa1lklCRRzMicTqfiw2", 
        event_name: "api.call",
        timestamp: new Date().toISOString(),
        metadata: {
          endpoint: "/v1/orders",
          method: "POST",
          response_size: 1024
        }
      }
    ]
  })
});

​
Análisis de Facturación Basada en el Uso

Monitorea y analiza tus datos de facturación basada en el uso con un panel de análisis completo. Rastrea patrones de consumo de clientes, rendimiento de medidores y tendencias de facturación para optimizar tu estrategia de precios y comprender los comportamientos de uso.

​
Análisis General

La pestaña de Resumen proporciona una vista completa de tu rendimiento de facturación basada en el uso:

​
Métricas de Actividad

Rastrea estadísticas clave de uso a través de diferentes períodos de tiempo:
​
Mes Actual
metric
Muestra la actividad de uso para el período de facturación actual, ayudándote a comprender los patrones de consumo mensual.
​
Todo el Tiempo
metric
Muestra estadísticas acumulativas de uso desde que comenzaste a rastrear, proporcionando información sobre el crecimiento a largo plazo.
Utiliza el selector de período de tiempo para comparar el uso a través de diferentes meses e identificar tendencias estacionales o patrones de crecimiento.

​
Gráfico de Cantidades de Medidores

Gráfico de cantidades de medidores que muestra tendencias de uso a lo largo del tiempo con visualización de gradiente púrpura
El gráfico de cantidades de medidores visualiza las tendencias de uso a lo largo del tiempo con las siguientes características:
  • Visualización de series temporales: Rastrea patrones de uso a través de días, semanas o meses
  • Soporte para múltiples medidores: Ver datos de diferentes medidores simultáneamente
  • Análisis de tendencias: Identifica picos de uso, patrones y trayectorias de crecimiento
El gráfico se escala automáticamente según tu volumen de uso y el rango de tiempo seleccionado, proporcionando una visibilidad clara tanto de pequeñas fluctuaciones como de cambios importantes en el uso.

​
Análisis de Eventos

Tabla de eventos que muestra nombres de eventos, IDs y controles de paginación para un análisis detallado de eventos
La pestaña de Eventos proporciona visibilidad granular sobre eventos de uso individuales:

​
Visualización de Información de Eventos

La tabla de eventos proporciona una vista clara de eventos de uso individuales con las siguientes columnas:
  • Nombre del Evento: La acción o desencadenante específico que generó el evento de uso
  • ID del Evento: Identificador único para cada instancia de evento
  • ID del Cliente: El cliente asociado con el evento
  • Marca de Tiempo: Cuándo ocurrió el evento
Esta vista te permite rastrear y monitorear eventos de uso individuales a través de tu base de clientes, proporcionando transparencia en los cálculos de facturación y patrones de uso.

​
Análisis de Clientes

La pestaña de Clientes proporciona una vista de tabla detallada de los datos de uso de los clientes con la siguiente información:

​
Columnas de Datos Disponibles

​
Correo Electrónico del Cliente
string
Dirección de correo electrónico del cliente para identificación.
​
ID de Suscripción
string
Identificador único para la suscripción del cliente.
​
Umbral Gratuito
number
Número de unidades gratuitas incluidas en el plan del cliente antes de que se apliquen cargos.
​
Precio por Unidad
currency
El costo por unidad para el uso más allá del umbral gratuito.
​
Último Evento
timestamp
Marca de tiempo del evento de uso más reciente del cliente.
​
Precio Total
currency
Monto total cobrado al cliente por la facturación basada en el uso.
​
Unidades Consumidas
number
Número total de unidades que el cliente ha consumido.
​
Unidades Cobrables
number
Número de unidades que exceden el umbral gratuito y están siendo cobradas.

​
Características de la Tabla

  • Filtrado de Columnas: Usa la función “Editar Columnas” para mostrar/ocultar columnas de datos específicas
  • Actualizaciones en Tiempo Real: Los datos de uso reflejan las métricas de consumo más actuales

​
Ejemplos de Agregación

Aquí hay ejemplos prácticos de cómo funcionan los diferentes tipos de agregación:

​
Entendiendo los Tipos de Agregación

Diferentes tipos de agregación sirven para diferentes escenarios de facturación. Elige el tipo correcto según cómo desees medir y cobrar por el uso.

​
Ejemplos de Implementación Práctica

Estos ejemplos demuestran aplicaciones del mundo real de cada tipo de agregación con eventos de muestra y resultados esperados.
Escenario: Rastrear el número total de solicitudes a la APIConfiguración del Medidor:
  • Nombre del Evento: api.call
  • Tipo de Agregación: Contar
  • Unidad de Medida: calls
Eventos de Muestra:
{
  "events": [
    {"event_id": "call_1", "customer_id": "cus_123", "event_name": "api.call"},
    {"event_id": "call_2", "customer_id": "cus_123", "event_name": "api.call"},
    {"event_id": "call_3", "customer_id": "cus_123", "event_name": "api.call"}
  ]
}
Resultado: 3 llamadas cobradas al cliente
Escenario: Cobrar según el total de bytes transferidosConfiguración del Medidor:
  • Nombre del Evento: data.transfer
  • Tipo de Agregación: Suma
  • Sobre Propiedad: bytes
  • Unidad de Medida: GB
Eventos de Muestra:
{
  "events": [
    {
      "event_id": "transfer_1",
      "customer_id": "cus_123", 
      "event_name": "data.transfer",
      "metadata": {"bytes": 1073741824}
    },
    {
      "event_id": "transfer_2",
      "customer_id": "cus_123",
      "event_name": "data.transfer", 
      "metadata": {"bytes": 536870912}
    }
  ]
}
Resultado: 1.5 GB de transferencia total cobrados al cliente
Escenario: Cobrar según el conteo máximo de usuarios concurrentesConfiguración del Medidor:
  • Nombre del Evento: concurrent.users
  • Tipo de Agregación: Máx
  • Sobre Propiedad: count
  • Unidad de Medida: users
Eventos de Muestra:
{
  "events": [
    {
      "event_id": "peak_1",
      "customer_id": "cus_123",
      "event_name": "concurrent.users", 
      "metadata": {"count": 15}
    },
    {
      "event_id": "peak_2",
      "customer_id": "cus_123",
      "event_name": "concurrent.users",
      "metadata": {"count": 23}
    },
    {
      "event_id": "peak_3",
      "customer_id": "cus_123",
      "event_name": "concurrent.users",
      "metadata": {"count": 18}
    }
  ]
}
Resultado: 23 usuarios concurrentes máximos cobrados al cliente

​
Ejemplos de Filtrado de Eventos

Contar solo las llamadas a la API a endpoints específicos:Configuración del Filtro:
  • Propiedad: endpoint
  • Comparador: equals
  • Valor: /v1/orders
Evento de Muestra:
{
  "event_id": "call_1",
  "customer_id": "cus_123",
  "event_name": "api.call",
  "metadata": {
    "endpoint": "/v1/orders",
    "method": "POST"
  }
}
Resultado: Los eventos que coincidan con los criterios de filtrado serían contados. Los eventos con diferentes endpoints serían ignorados.

​
Solución de Problemas

Resuelve problemas comunes con la implementación de facturación basada en el uso y asegura un seguimiento y facturación precisos.

​
Problemas Comunes

La mayoría de los problemas de facturación basada en el uso caen en estas categorías:
  • Problemas de entrega y procesamiento de eventos
  • Problemas de configuración de medidores
  • Errores de tipo de datos y formato
  • Problemas de ID de cliente y autenticación

​
Pasos de Depuración

Al solucionar problemas de facturación basada en el uso:
  1. Verifica la entrega de eventos en la pestaña de análisis de Eventos
  2. Verifica que la configuración del medidor coincida con la estructura de tu evento
  3. Valida los IDs de cliente y la autenticación de la API
  4. Revisa las condiciones de filtrado y los ajustes de agregación

​
Soluciones y Arreglos

Causas comunes:
  • El nombre del evento no coincide exactamente con la configuración del medidor
  • Las condiciones de filtrado de eventos están excluyendo tus eventos
  • El ID del cliente no existe en tu cuenta de Dodo Payments
  • La marca de tiempo del evento está fuera del período de facturación actual
Soluciones:
  • Verifica la ortografía y la sensibilidad a mayúsculas del nombre del evento
  • Revisa y prueba tus condiciones de filtrado
  • Confirma que el ID del cliente sea válido y esté activo
  • Verifica que las marcas de tiempo de los eventos sean recientes y estén correctamente formateadas
Causas comunes:
  • El nombre de la Propiedad sobre no coincide con las claves de metadatos del evento
  • Los valores de metadatos son del tipo de dato incorrecto (cadena vs número)
  • Faltan propiedades de metadatos requeridas
Soluciones:
  • Asegúrate de que las claves de metadatos coincidan exactamente con tu configuración de Propiedad sobre
  • Convierte números en cadena a números reales en tus eventos
  • Incluye todas las propiedades requeridas en cada evento
Causas comunes:
  • Los nombres de las propiedades de filtrado no coinciden con los metadatos del evento
  • Comparador incorrecto para el tipo de dato (cadena vs número)
  • Sensibilidad a mayúsculas y minúsculas en comparaciones de cadenas
Soluciones:
  • Verifica que los nombres de las propiedades coincidan exactamente
  • Usa comparadores apropiados para tus tipos de datos
  • Considera la sensibilidad a mayúsculas y minúsculas al filtrar cadenas