Uso y métricas de cobro

Un cargo de uso necesita una cantidad. Esa cantidad no se escribe a mano: se calcula desde los eventos que tu sistema reporta. Esta página cubre las tres piezas de esa cadena.

De la actividad a la cantidad

1. Evento
2. Métrica de cobro
3. Filtros
4. Agregación
5. Cantidad del período

Eventos de uso

Un evento de uso es un hecho fechado: qué pasó, cuándo, y para qué cliente. Es inmutable — Relvo nunca edita un evento ya ingresado.

El contrato de ingesta

Los eventos se envían por lotes a POST /api/v1/public/metering/usage-events, hasta 500 eventos por llamada.

Campo	Obligatorio	Descripción
event_name	✅	Nombre del evento. Es lo que la métrica selecciona.
timestamp	✅	Momento en que ocurrió el consumo, ISO 8601 en UTC. Determina a qué período pertenece.
idempotency_key	✅	Clave única del evento. Reenviar la misma clave no duplica el consumo.
customer_id	—	UUID interno del cliente. Excluyente con external_customer_id.
external_customer_id	—	Código del cliente en tu sistema. Excluyente con customer_id.
properties	—	Dimensiones y cantidades del evento.

properties es un mapa plano —sin objetos anidados— de strings, enteros y booleanos. Hasta 100 propiedades, con claves de máximo 128 caracteres.

§

Las cantidades fraccionarias van como string

"0.75" como texto, no 0.75 como número. Un decimal en punto flotante pierde exactitud en tránsito, y en facturación esa pérdida termina en un monto incorrecto. Relvo rechaza el formato ambiguo antes de aceptarlo, no después de facturarlo.

La respuesta es 202, no 201

La ingesta es asíncrona: Relvo acepta el lote en una bandeja de entrada idempotente y lo procesa después. La respuesta te dice exactamente qué pasó con cada evento:

Campo	Significado
queued	Eventos aceptados y encolados
duplicate	Eventos cuya idempotency_key ya estaba en la bandeja. No se re-encolan, y no es un error
event_ids	Recibos de ingesta de los eventos nuevos
validation_failed	Eventos rechazados, con el motivo por cada uno

Un lote puede tener resultados mixtos: 480 encolados, 15 duplicados y 5 rechazados. Revisa validation_failed en cada respuesta — un 202 no significa que los 500 eventos entraron.

Ejemplo

Reintento seguro tras un timeout

Tu proceso envía 500 eventos, la conexión se corta y no sabes si llegaron. Reenvías el mismo lote con las mismas idempotency_key.

{ "queued": 0, "duplicate": 500, "event_ids": [], "validation_failed": [] }

Ningún consumo se duplicó. Ésta es exactamente la razón por la que idempotency_key es obligatoria y no opcional.

Origen y estado

Cada evento conserva de dónde vino (api, manual o csv) y en qué estado está:

Estado	Significado
ACTIVE	Cuenta para el cálculo
VOIDED	Anulado por una corrección. Ya no cuenta
SUPERSEDED	Reemplazado por un evento posterior. Ya no cuenta

Correcciones

Un evento no se edita: se corrige con POST /api/v1/public/metering/usage-events/{id}/corrections, con dos operaciones posibles.

Operación	Efecto	Cuándo usarla
VOID	Retira el evento (pasa a VOIDED)	El consumo nunca ocurrió
REPLACE	Lo sustituye por un evento nuevo (el original pasa a SUPERSEDED)	El consumo ocurrió, pero con otros datos

La corrección registra reason_code y reason_detail, y la respuesta te dice qué consecuencias tiene:

• rerating_required — el período afectado debe recalcularse.
• adjustment_required — el período ya se facturó, así que la corrección no puede cambiar el documento emitido y necesita una nota de crédito o débito.

!

Corregir consumo ya facturado no reescribe la factura

Una factura emitida es un registro financiero inmutable. Si la corrección afecta un período ya facturado, Relvo te lo indica con adjustment_required y la diferencia se resuelve con una nota de crédito o débito. Nunca alterando el documento original.

Métricas de cobro

Una métrica de cobro convierte una pila de eventos en un número. Define tres cosas: qué eventos selecciona, qué propiedad mide y cómo los combina.

Se pueden definir de dos formas:

Modo	Para quién	Qué permite
Guiado	Operaciones y RevOps	Elegir evento, propiedad, método de agregación y filtros desde la interfaz
SQL	Equipos de datos	Escribir la consulta cuando la lógica no cabe en el modo guiado

Ambos modos producen una métrica equivalente aguas abajo: el cargo no sabe cómo fue autorizada.

Métodos de agregación

El modo guiado ofrece:

Método	Qué calcula	Ejemplo
count_agg	Cuenta eventos	Número de llamadas a la API
sum_agg	Suma una propiedad	GB transferidos
avg_agg	Promedio de una propiedad	Latencia media
max_agg	Máximo del período	Peak de conexiones concurrentes
min_agg	Mínimo del período	Piso de capacidad usada
unique_count_agg	Valores distintos	Usuarios activos únicos
latest_agg	Último valor observado	Almacenamiento al cierre

Dos métodos adicionales existen a nivel de motor pero no se autorizan desde el modo guiado: weighted_sum_agg (suma ponderada por el tiempo que cada valor estuvo vigente) y custom_agg.

§

`latest_agg` no sirve como base de un porcentaje

latest_agg devuelve una foto puntual, no una serie de cantidades: no hay un valor transado sobre el cual aplicar una tasa. Relvo rechaza la combinación con percentage y graduated_percentage al crear el cargo, no al facturar, para que el error aparezca cuando aún es barato corregirlo.

Filtros

Un filtro restringe la métrica a un subconjunto de eventos según sus propiedades. Un mismo evento puede alimentar varias métricas filtradas de forma distinta.

Ejemplo

Un evento, tres cargos

Tu sistema emite un solo evento api_request con properties.region. Con filtros, ese mismo flujo alimenta tres cargos con precios distintos:

Métrica	Filtro	Cargo
Requests LATAM	region = latam	USD 0,04 / request
Requests US	region = us-east	USD 0,06 / request
Requests total	(sin filtro)	Mínimo mensual

No hace falta cambiar la instrumentación: se cambia la métrica.

Cómo se cierra el período

Al cerrar el período, Relvo agrega los eventos ACTIVE cuyo timestamp cae dentro de la ventana, aplica los filtros de la métrica y entrega la cantidad al modelo de precio del cargo. Un evento que llega tarde, con timestamp de un período ya facturado, no reescribe esa factura: activa el mismo camino de ajuste que una corrección.

SiguienteCargos y pricingQué hace el modelo de precio con la cantidad que produjo la métrica.RelacionadoCargos por asientoCantidades resueltas desde asientos en vez de eventos reportados.RelacionadoIntegraciones operativasCómo conectar tu sistema para reportar consumo.APIIdempotenciaEl contrato de reintentos en toda la API pública.