403 PRODUCT_NOT_ENABLED.Cómo encajan las piezas
- Medidor: una acción con nombre y contable:
ai_tokens,api_request,storage_gb. Define elevent_nameque envían tus sistemas y la agregación (SUM,COUNToLAST). Un medidor no tiene precio propio, como máximo undefault_priceen USD que los planes pueden heredar. Consulta El objeto Meter. - Precio medido: el medidor asociado a un plan: cuántas unidades se incluyen por ciclo (
credits) y cuánto cuesta cada unidad adicional (price_per_credit, opcionalmente por país). Un plan puede tener cualquier cantidad de precios medidos junto a su precio fijo. Consulta El objeto Metered Price. - Suscripción: se crea en ese plan como de costumbre. Hereda todos los precios medidos; nada cambia en Crear suscripción.
- Eventos de uso: una llamada por unidad de trabajo, con el
event_name, elsubscription_id, unvaluey tu propioevent_idpara la idempotencia. Consulta Reportar evento de uso. - Renovación: al final del ciclo de facturación, Yuno calcula la cantidad facturable (
max(0, usage − credits)) y sumabillable × price_per_credital cargo de renovación de la suscripción.
unit_label / plural_unit_label del medidor son las etiquetas con las que se muestra el uso.Inicio rápido
El ejemplo crea un plan “Max” de $200 al mes que incluye 10,000 tokens de IA y cobra $0.002 por cada token adicional. Las solicitudes usan los encabezados estándarpublic-api-key / private-secret-key. X-Idempotency-Key se acepta en todas las solicitudes, como en el resto de la API de Yuno, pero los eventos de uso tienen su propia clave de deduplicación dedicada: consulta Idempotencia y marcas de tiempo.
Crea el medidor
event_name que enviarán tus sistemas (minúsculas, se permiten _ y .) y la agregación. default_price es opcional y debe estar en USD; te evita repetir el precio unitario en cada plan en USD.201 con el medidor, siempre ACTIVE. Conserva su id: lo necesitas para asociar el medidor a un plan.Asócialo a un plan
meter_id, credits (unidades incluidas por ciclo), pricing_strategy y, si no se hereda, price_per_credit.price_per_credit: el plan es en USD y el medidor tiene un default_price, por lo que se aplica $0.002 y el precio medido se devuelve con price_per_credit: null. La respuesta del plan y Consultar plan ahora incluyen el precio medido en meters[] (un arreglo vacío en los planes sin medidores).credits. Enviar { "meters": [ ... ] } a PATCH /subscriptions/plans/{plan_id} hace lo mismo para varios medidores a la vez, de forma atómica (si una entrada es incorrecta, no se asocia ninguna), e ignora todos los demás campos del plan.Suscribe a tus clientes al plan
plan_id. La suscripción hereda los precios medidos del plan. Guarda el id de la suscripción: todos los eventos de uso lo referencian.Reporta el uso a medida que ocurre
event_id es tu clave de idempotencia; value es obligatorio para los medidores SUM y LAST, y su valor predeterminado es 1 para COUNT. La suscripción debe estar ACTIVE, TRIALING o PAST_DUE.201 confirma que el evento se validó y se almacenó:event_id) devuelve esta misma respuesta y nunca cuenta los 1,500 tokens dos veces: aunque el reintento lleve un value distinto, se conserva el original.Cómo elegir una agregación
La agregación se fija al crear el medidor y determina qué significa la cantidad de un ciclo:- SUM: consumo
- COUNT: por llamada
- LAST: medición puntual
value de cada evento. Reporta la cantidad consumida por cada unidad de trabajo.Cómo fijar el precio de un medidor en un plan
Un precio medido tiene tres parámetros de precio:credits: las unidades incluidas en el plan en cada ciclo de facturación. Piénsalo como una “cuota”: las primerascreditsunidades quedan cubiertas por el precio fijo del plan.0factura todas las unidades.creditsse mide en la unidad del medidor (tokens, solicitudes, GB) y se reinicia en cada ciclo: no es un saldo prepagado ni una billetera.price_per_credit: el precio de cada unidad que superacredits, en la moneda base del plan. En un plan en USD puedes omitirlo si el medidor tiene undefault_price; entonces se aplica el valor predeterminado del medidor y el precio medido se devuelve conprice_per_credit: null. En un plan que no está en USD, o cuando el medidor no tiene valor predeterminado, es obligatorio. La moneda siempre debe coincidir con la moneda debase_amountdel plan.country_prices: precios por unidad opcionales según el país del suscriptor (una entrada por país), con la misma forma que loscountry_pricesdel propio plan. Un suscriptor cuyo país no figura en la lista pagaprice_per_credit. El país del suscriptor proviene de la suscripción (los eventos de uso no llevancountryniaccount_id), por lo quecountry_pricesse resuelve automáticamente por suscriptor.
pricing_strategy define cómo se tarifica el excedente, y cada estrategia tiene sus propios campos de configuración al momento de asociar:
- PER_UNIT: tarifa fija
- PACKAGE: paquetes
- TIERED: escalonado
price_per_credit (o la entrada de country_prices del suscriptor). La opción predeterminada para tokens, solicitudes y minutos.PER_UNIT, el medidor debe tener precio en cada moneda que admite el plan: se rechaza un plan con country_prices en monedas que el precio medido no cubre (PLAN_METER_MISSING_CURRENCY), y cada moneda con precio debe coincidir con una que el plan realmente use (PLAN_METER_BASE_CURRENCY_MISMATCH). Todos los montos de uso calculados (con cualquier estrategia) se redondean half-up a 4 decimales.
Qué ocurre en la renovación
- Cantidad: los eventos cuyo
occurred_atcae dentro del ciclo se agregan con laaggregationdel medidor (SUM / COUNT / LAST). - Unidades facturables:
max(0, quantity − credits). Los créditos sin usar no se acumulan. - Monto:
billable × price_per_credit(o la entrada decountry_pricesdel suscriptor). - Cargo: el monto se suma al cargo de renovación de la suscripción junto con el precio fijo del plan. Un cargo, un pago, como hasta ahora. Una suscripción con un uso inferior a sus créditos paga solo el precio fijo.
Idempotencia y marcas de tiempo
event_ides obligatorio y es tu clave de idempotencia. Hazlo único por evento (un UUID, o el id de la solicitud, respuesta o tarea de la que proviene) y reutilízalo en cada reintento. Yuno almacena el primer evento con ese id y responde a cada repetición con la misma respuesta, incluido elvalueoriginal (unvaluedistinto en el reintento se descarta). El uso nunca se cuenta dos veces, sin importar cuántas veces reintentes. Una solicitud sinevent_idse rechaza con400.- Reporta lo más cerca posible del tiempo real, aunque puedes registrar eventos con fecha anterior.
occurred_attoma por defecto la hora de recepción (devuelta comoreceived_at) y puede ser hasta 35 días anterior; los eventos más antiguos se rechazan con400.occurred_at(no la hora de recepción) decide en qué ciclo de facturación cae el evento. X-Idempotency-Keyse acepta, como en el resto de la API de Yuno (misma clave + mismo cuerpo → misma respuesta), pero aquí es opcional y no es lo que deduplica el uso:event_ides el mecanismo que protege la facturación, y es el único obligatorio.- Un evento por solicitud. Agrega en tu lado si generas muchos eventos pequeños (por ejemplo, suma los tokens por respuesta en lugar de por token): un medidor
SUMestá pensado para eso. - La suscripción debe estar activa. Las suscripciones
ACTIVE,TRIALINGyPAST_DUEaceptan uso (una suscripción en reintentos de pago sigue midiendo); los eventos de una suscripciónPAUSED,CANCELEDoCOMPLETEDse rechazan con400 SUBSCRIPTION_NOT_ACTIVEy no se cuenta nada.
Manejo de errores
La validación es síncrona: un evento rechazado devuelve400 de inmediato (los fallos de búsqueda también son 400, nunca 404) y no se cuenta, así que trata cualquier respuesta distinta de 201 como “no registrado” y reintenta con el mismo event_id después de corregir la solicitud. Los códigos que encontrarás con más frecuencia:
Preguntas frecuentes
¿Necesito un plan nuevo para agregar precios por uso a uno existente?
¿Necesito un plan nuevo para agregar precios por uso a uno existente?
PATCH /subscriptions/plans/{plan_id} solo de asociación con meters[]). El precio fijo y el monto base de los suscriptores existentes no cambian; el uso que supere credits empieza a facturarse en su siguiente renovación.¿Un plan puede tener varios medidores?
¿Un plan puede tener varios medidores?
SUM) más solicitudes a la API (COUNT) más almacenamiento (LAST), cada uno con sus propios credits y precio unitario. Cada medidor se puede asociar una sola vez a un plan determinado.¿Los créditos se comparten entre suscripciones o entre medidores?
¿Los créditos se comparten entre suscripciones o entre medidores?
credits se aplica por suscripción, por medidor y por ciclo de facturación. Dos suscriptores del mismo plan reciben cada uno la cuota completa; los créditos sin usar no se acumulan.¿Qué pasa si reporto uso de una suscripción que no está en un plan con ese medidor?
¿Qué pasa si reporto uso de una suscripción que no está en un plan con ese medidor?
meters[] del plan si el uso no aparece en la renovación.¿Puedo cambiar el event_name o la agregación de un medidor?
¿Puedo cambiar el event_name o la agregación de un medidor?
event_name nuevo: los nombres quedan reservados incluso después de archivar) y archiva el anterior con Actualizar medidor (status: INACTIVE). Los medidores archivados rechazan eventos nuevos con 400 METER_NOT_FOUND, no se pueden asociar a planes y sus precios medidos existentes quedan congelados; puedes reactivar uno en cualquier momento con status: ACTIVE.¿Puedo quitar un precio medido de un plan?
¿Puedo quitar un precio medido de un plan?
credits para que no se facture excedente.¿Puedo fijar el precio del medidor en una moneda distinta de USD?
¿Puedo fijar el precio del medidor en una moneda distinta de USD?
default_price del medidor es solo en USD, pero un precio medido en un plan en BRL recibe price_per_credit en BRL (obligatorio: no se hereda nada en los planes que no están en USD), y country_prices te permite fijar precios unitarios por país en la moneda de cada país.¿Qué pasa si reporto uso de una suscripción pausada o cancelada?
¿Qué pasa si reporto uso de una suscripción pausada o cancelada?
400 SUBSCRIPTION_NOT_ACTIVE y no se cuenta nada: solo las suscripciones ACTIVE, TRIALING y PAST_DUE aceptan uso. Reanuda primero la suscripción (Reanudar suscripción) y luego reporta el uso; puedes registrar occurred_at con fecha anterior hasta 35 días.¿Puedo medir el uso sin una suscripción?
¿Puedo medir el uso sin una suscripción?
subscription_id; el uso se factura en la renovación de esa suscripción.Leer el uso
Llama a Consultar uso de la suscripción para leer lo que una suscripción ha acumulado en su período de facturación actual antes de que la renovación lo tarife: un elemento por medidor, con la cantidad facturable, el precio unitario y el monto resultante, además de un total del período. Una suscripción cuyo plan no tiene medidores devuelve un arregloitems vacío y un total de cero. El reporte de uso es asíncrono, por lo que una lectura realizada poco después de reportar un evento puede ir por detrás.