MeterFlow Empieza aquí: la visión general
MeterFlow responde a una sola pregunta sobre tu producto: “¿quién usó cuánto de qué — y cuánto le cuesta?” Todo lo que ves en el panel existe para responder a esa pregunta.
user-842 o un email).Cómo encajan las piezas
¿Por qué algunos botones de “Crear” están desactivados?
Cada diálogo desactiva su botón de confirmación hasta que todos los campos obligatorios (marcados con *) estén rellenos — p. ej. “Create plan” sigue desactivado hasta que el plan tenga un Nombre. Si un botón parece atascado, busca un campo obligatorio vacío más arriba.
Nueva organización contenedor
El contenedor más externo — normalmente tu empresa. Todo lo demás (proyectos, meters, planes…) vive dentro de una organización. Recibiste una automáticamente al registrarte.
📍 Dashboard → el botón “New organization” (también se ofrece en el primer inicio de sesión, cuando aún no tienes ninguna)
- Name *
El nombre de tu empresa o equipo. Es solo una etiqueta — puedes cambiarla más adelante.
- Billing email
Adónde irían las facturas y avisos de facturación de tu cuenta de MeterFlow. Opcional; se valida el formato, pero no se envía nada para verificarlo.
finance@acme.dev. Sus dos productos se convertirán en dos proyectos dentro de ella.Nuevo proyecto contenedor
Un proyecto = un producto o entorno que quieres medir. Cada meter, plan, clave API, saldo de cliente y evento de uso pertenece a exactamente un proyecto — los proyectos nunca ven los datos de los demás.
📍 Dashboard → el botón “New project” en la cabecera de la tabla Projects
- Organization *
A qué organización pertenece el proyecto. Preseleccionada si ya tienes una activa.
- Name *
El nombre del producto, p. ej. “PixelForge AI”. Se muestra por todo el panel y en el selector de proyectos.
- Description
Texto libre para tu propia referencia.
Generar clave API acceso
La credencial que tu aplicación usa para hablar con MeterFlow. Tu backend se la pasa al SDK; cada evento de uso, operación de créditos y llamada de suscripciones se autentica — y se limita a un solo proyecto — mediante esta clave.
📍 Abre un proyecto → API Keys → el botón en la cabecera de la tabla
- Key name *
Una etiqueta para recordar dónde se usa la clave — “Backend de producción”, “Staging”, “Tests de CI”. Sin efecto técnico.
- Environment
Las claves Live empiezan por
mf_live_, las Test pormf_test_— y acceden a dos conjuntos de datos totalmente separados dentro del mismo proyecto. Las suscripciones, créditos y uso creados con una clave Test son invisibles para las claves Live (y viceversa), mientras que tus meters y planes se comparten: las pruebas siempre corren contra tu configuración de facturación real. Usa claves Test para desarrollo, staging y CI; las Live solo para el tráfico real de producción.
mf_live_a1b2… una sola vez y la pones en las variables de entorno de tu servidor: new MeterFlow({ apiKey: process.env.METERFLOW_KEY }). La lista del panel mostrará para siempre solo el prefijo y los últimos 4 caracteres.Nuevo meter concepto clave
Un meter es la definición de un contador con nombre: declara una cosa de tu producto que merece medirse, y cómo los eventos en bruto deben convertirse en un número. Piénsalo como crear una nueva columna en un informe de uso antes de que existan los datos.
📍 Abre un proyecto → Meters → el botón en la cabecera de la tabla
- Name *
La etiqueta legible que se muestra en el panel — “Imágenes generadas”, “Segundos de render de vídeo”. Solo para ojos humanos.
- Event name *
La clave para máquinas — y sí, se guarda en la base de datos y se compara de forma exacta. Cuando tu aplicación reporta uso, envía un nombre de evento; MeterFlow busca en ese proyecto el meter activo cuyo
event_namecoincide exactamente, mayúsculas y minúsculas incluidas. Si no existe ninguno, el evento se rechaza con un error 404 (“No active meter found for event …”) y no se registra nada. Cada nombre de evento es único dentro de un proyecto. Convención: minúsculas con puntos, p. ej.image.generated. - Aggregation type
Cómo se combinan muchos eventos individuales en un solo número en los resúmenes de uso. Mira la tabla de abajo — es el corazón del meter.
- Aggregation field
Obligatorio para todos los tipos salvo Count. Indica qué campo numérico del evento lleva la cantidad que se agrega — responde a “¿suma de qué?”. En la práctica tu app envía el número en el campo
valuedel evento, y eso es lo que se agrega; el aggregation field documenta qué significa ese valor (p. ej.seconds,tokens,megabytes) para que quien lea el meter conozca la unidad. Para Count es irrelevante — contar solo necesita que el evento exista. - Description
Texto libre para tu equipo.
Los tipos de agregación, con un ejemplo
Supón que el cliente user-842 dispara 4 eventos este mes con valores 3, 10, 2, 10. Se reporta un número por meter — cuál, depende del tipo de agregación:
| Tipo | Qué pregunta responde | Resultado para 3, 10, 2, 10 | Uso típico |
|---|---|---|---|
| Count | ¿Cuántas veces ocurrió? (valores ignorados) | 4 | Imágenes generadas, llamadas API, exportaciones |
| Sum | ¿Cuánto en total? | 25 | Segundos renderizados, tokens consumidos, GB transferidos |
| Max | ¿Cuál fue el mayor valor? | 10 | Pico de trabajos simultáneos, subida más grande |
| Min | ¿Cuál fue el menor valor? | 2 | Rara vez para facturar — más bien diagnóstico |
| Unique count | ¿Cuántos valores distintos aparecieron? | 3 (3, 10, 2) | Días activos distintos, documentos distintos tocados |
video.rendered · Agregación Sum · Aggregation field seconds.Tu app termina de renderizar un clip de 42 segundos para
user-842 y reporta el evento video.rendered con valor 42. Hazlo unas cuantas veces y la página de uso del cliente mostrará una línea: Video render seconds — 3 eventos — 117.¿El nombre de evento tiene que coincidir con lo que envía mi app? ¿Qué pasa con una errata?
Sí — exactamente, mayúsculas incluidas. El nombre de evento del meter se guarda en la base de datos y actúa como la etiqueta de dirección de los eventos entrantes. Si tu app envía video.render pero el meter dice video.rendered, la API responde 404 “No active meter found for event 'video.render' in this project” y el evento no se guarda. Es deliberado: una errata silenciosa filtraría para siempre uso sin facturar. Crea primero el meter y luego empieza a enviar eventos con el mismo nombre.
¿Puedo cambiar el tipo de agregación más adelante?
No — tras la creación solo se pueden editar el nombre, la descripción y el estado activo. La agregación define qué significa el histórico guardado, así que cambiarla retroactivamente reescribiría el pasado. Si necesitas otro cálculo, crea un meter nuevo con un nombre de evento nuevo.
¿Por qué “Aggregation field” es opcional en el formulario si dice que es obligatorio?
El formulario permite dejarlo en blanco porque solo es obligatorio para los tipos distintos de Count — el servidor valida esa regla. Si eliges Sum/Max/Min/Unique count y lo dejas vacío, la creación se rechaza con un error de validación claro; con Count puedes ignorar el campo por completo.
Nuevo plan concepto clave
Un plan es un nivel de precios — “Free”, “Pro a 29 $/mes”… Combina un precio recurrente con un conjunto de límites de meter que dicen cuánto de cada función medida está incluido y qué pasa más allá. Los clientes se vinculan a un plan mediante una suscripción.
📍 Abre un proyecto → Plans → el botón en la cabecera de la tabla
- Name *
El nombre del nivel — “Free”, “Pro”, “Enterprise”. Obligatorio; el botón de crear sigue desactivado hasta que se rellena.
- Description
Texto libre, p. ej. el eslogan de marketing del nivel.
- Price / Currency / Billing period
La cuota recurrente de la suscripción: Price es el importe (0 vale para un nivel gratuito), Currency un código como
USD, y Billing period la frecuencia — mensual, anual, semanal o pago único. Fijos tras la creación — editar el plan después no puede cambiarlos (crea un plan nuevo en su lugar, para que las condiciones de los suscriptores actuales no cambien en silencio). - Trial days
Días gratis al inicio de cada nueva suscripción. Con
14, un nuevo suscriptor pasa 2 semanas en estado “trialing” antes de que empiece el periodo de pago.0= sin prueba. - Public
Si el plan es visible para tu aplicación a través de la lista de planes del SDK (p. ej. para pintar tu página de precios). Sin marcar = interno/oculto — útil para acuerdos enterprise a medida o planes aún en borrador.
Límites de meter — la sección “+ Add limit”
Cada fila de límite conecta este plan con un meter y responde: ¿cuánto de esa cosa está incluido, y qué pasa más allá?
- Meter *
A qué magnitud medida se aplica este límite. El desplegable lista los meters que creaste en este proyecto — ni más, ni menos. No es un catálogo fijo: cualquier nueva capacidad del producto solo necesita antes un meter nuevo, y aparece aquí de inmediato.
- Included units
La cantidad incluida en el precio del plan, por periodo de facturación. “Pro incluye 500 imágenes al mes” →
500. - Overage rate
El precio en créditos por unidad cuando el cliente supera las unidades incluidas.
0.5significa que cada unidad extra cuesta medio crédito del saldo del cliente. Solo tiene sentido con el tipo de límite Metered. - Limit type
Hard (bloquear) — el uso más allá de las unidades incluidas debe rechazarse; el cliente choca con un muro. Soft (avisar) — el uso continúa, pero se te avisa para que animes al cliente a mejorar de plan. Metered (cobrar) — el uso continúa y cada unidad extra se cobra automáticamente del saldo de créditos del cliente a la tarifa de exceso. Metered es la opción “pago por uso” y la única que mueve dinero (créditos) por sí sola.
USD · Mensual · 14 días de prueba · Public ✓Límite 1: meter Imágenes generadas, incluidas 500, tipo Hard → tras 500 imágenes, la generación se bloquea hasta el mes siguiente o una mejora de plan.
Límite 2: meter Segundos de render de vídeo, incluidos 1 000, exceso 0,02, tipo Metered → pasados los 1 000 segundos, cada segundo extra cuesta en silencio 0,02 créditos del monedero del cliente.
¿Por qué “+ Add limit” está desactivado?
Porque el proyecto aún no tiene meters — un límite siempre es un tope sobre un meter, así que con cero meters no hay nada a lo que asociarlo. El diálogo muestra la pista “Create meters first to attach limits to this plan.” Ve a Meters → New meter, crea al menos uno y vuelve a abrir este diálogo.
¿Por qué el desplegable de Meter muestra solo unas pocas opciones? ¿Y si mi producto tiene algo nuevo?
El desplegable es simplemente tus propios meters del proyecto seleccionado. En los datos de demostración resultan ser “Upscales processed”, “Video render seconds” e “Images generated” — pero esa lista es tuya y puede crecer. No restringe lo que los clientes pueden hacer: los clientes nunca eligen meters; tú defines meters para lo que sea que haga tu producto. ¿Una función nueva mañana? Crea un meter para ella y aparecerá aquí.
¿Por qué no puedo editar el precio o los límites de un plan existente?
Es por diseño: los suscriptores actuales contrataron bajo esas condiciones, así que el precio, la moneda, el periodo de facturación y los límites de meter quedan congelados al crear. Editar un plan solo puede cambiar su nombre, descripción, días de prueba, visibilidad y estado activo. Para cambiar precios, crea un plan nuevo (p. ej. “Pro 2026”) y lleva allí a los nuevos clientes.
Nueva suscripción vincula cliente ⇄ plan
Una suscripción vincula a uno de tus clientes con un plan. Desde ese momento su uso se juzga contra los límites de meter de ese plan. En producción, tu backend normalmente la crea vía SDK en el instante en que alguien elige un nivel al pagar — el diálogo hace lo mismo a mano.
📍 Abre un proyecto → Subscriptions → el botón en la cabecera de la tabla
- Customer ID *
Tu propio identificador del cliente final — cualquier cadena que elijas: un ID de usuario de tu base de datos (
user-842), un email, un slug de tenant. MeterFlow nunca lo valida contra nada; lo que envíes es a quien pertenece la suscripción. Usa el mismo ID en todas partes (suscripciones, créditos, uso) o las piezas no conectarán. - Plan *
En qué nivel de precios está — el desplegable lista los planes de este proyecto. Si el plan tiene días de prueba, la suscripción empieza en “trialing”; si no, en “active”.
user-842 pulsa “Mejorar a Pro” en tu app → tu backend llama a subscriptions.create({ customer_external_id: 'user-842', plan_id: … }). Cada evento de uso de user-842 se contrasta ahora con los límites de Pro.¿Y si un cliente no tiene suscripción — se pierden sus eventos?
No. Los eventos siempre se guardan y siempre aparecen en los resúmenes de uso. Pero sin una suscripción activa no hay límites de plan que aplicar, así que nada se bloquea y nada se cobra — el uso simplemente se registra. La lógica de facturación se enciende en el momento en que existe una suscripción.
Abonar / Deducir créditos el monedero
Los créditos son un saldo prepagado por cliente (por proyecto) — piensa en un monedero o una tarjeta recargable. Tú decides cuánto vale un crédito en tus precios. El exceso “metered” se descuenta de este monedero automáticamente; los dos diálogos mueven créditos a mano.
📍 Abre un proyecto → Credits → busca un cliente → “Grant” / “Deduct”
- Amount *
Cuántos créditos añadir (Grant) o quitar (Deduct). Debe ser mayor que cero — la dirección la decide el botón que abrió el diálogo, no un signo menos.
- Description
Una nota opcional guardada en la línea del registro — “Bono de bienvenida”, “Reembolso por la incidencia”, “Cortesía de soporte”. Tu yo del futuro te lo agradecerá.
user-842 recibe un abono de 100 (“Bono de bienvenida”). Renderiza 2 500 segundos de vídeo en un plan con 1 000 incluidos y exceso metered de 0,02 → 1 500 × 0,02 = 30 créditos deducidos automáticamente. Saldo: 70.Registrar evento de uso concepto clave
Un evento de uso = “este cliente acaba de hacer esta cosa, en esta cantidad.” En producción, tu aplicación los envía por el SDK automáticamente, miles de veces al día; el diálogo existe para inyectar uno a mano, para pruebas y demostraciones.
📍 Abre un proyecto → Usage → busca un cliente → “Record event”
- Event name *
Debe coincidir exactamente con el nombre de evento de un meter existente y activo en este proyecto (distingue mayúsculas). Esa coincidencia es cómo MeterFlow sabe a qué contador alimenta este evento. Sin meter coincidente → la API rechaza el evento con un 404 y no se guarda nada. Consulta la página Meters para la grafía exacta.
- Customer ID *
Cuál de tus clientes lo hizo — la misma cadena de ID libre usada en suscripciones y créditos. La coherencia lo es todo:
user-842yUSER-842son dos clientes distintos. - Value
La cantidad, por defecto
1. Su significado depende de la agregación del meter: para un meter Count el valor se ignora (cada evento cuenta como una ocurrencia); para Sum es la cantidad a añadir (42 segundos, 1 300 tokens); para Max/Min es la medida a comparar; para Unique count es la cosa cuyos valores distintos se cuentan.
video.rendered → “Video render seconds”. 2. El evento se guarda permanentemente (en bruto — la agregación ocurre después, al leer). 3. En segundo plano, MeterFlow comprueba si el cliente tiene una suscripción activa y si ese plan tiene un límite sobre este meter. 4. Si el límite es Metered con tarifa de exceso, el cargo (valor × tarifa) se deduce del saldo de créditos del cliente y se escribe una línea en el registro. 5. El resumen de uso que ves en esta página se recalcula desde los eventos en bruto usando el tipo de agregación del meter.Registré un evento y recibí un error — ¿por qué?
Casi siempre es el nombre de evento: no coincide exactamente con ningún meter activo de este proyecto. El error lo dice literalmente — “No active meter found for event '…' in this project.” Copia el nombre de evento desde la página Meters en lugar de reescribirlo. Recuerda también que los meters son por proyecto: un meter de otro proyecto no cuenta.
Si mi app reintenta una petición, ¿el evento se contará dos veces?
No, si usas el SDK correctamente: cada escritura acepta una clave de idempotencia — una etiqueta única para “esta acción concreta”. Si la misma clave llega dos veces (un reintento tras un fallo de red), MeterFlow la reconoce y devuelve el resultado original en lugar de guardar un duplicado. El diálogo manual no la envía, así que pulsar Record dos veces a mano sí crea dos eventos.
Invitar miembro acceso del equipo
Añade a un compañero a tu organización para que pueda ver (o gestionar) sus proyectos en este panel. La persona ya debe tener una cuenta de MeterFlow — primero el registro, luego la invitación.
📍 Dashboard → tabla Organizations → acción de fila “Invite member”
- Email *
El email con el que está registrada su cuenta de MeterFlow.
- Role
Admin — gestión completa: proyectos, meters, planes, claves, miembros. Member — operaciones del día a día. Viewer — solo lectura. Fíjate en que deliberadamente no hay opción “owner”: la propiedad no puede repartirse mediante invitación.
dana@acme.dev como Viewer para que el equipo de finanzas pueda observar el uso y los saldos sin poder cambiar los precios.