Метрики
Где в админке
- Список и карточка метрики:
/billable-metric/*. - Журнал событий:
/metric-events/*.
Типы метрик (логика API)
| Тип | Назначение |
|---|---|
| Limit metered | Лимит потребления по подписке; при превышении новое событие может быть отклонено |
| Charge metered | Учёт usage; стоимость считается по тарифу на плане (фикс за единицу или ступени) |
| Charge recurring | Начисления по метрике в логике цикла (в т.ч. особые режимы агрегации, например max per day) |
Точные числовые константы типов в коде API — в пакете метрик бэкенда; в документации для интеграции важнее семантика и привязка к плану.
Создание метрики
- Создайте метрику в админке или через API (
metricNew). - Укажите имя, описание, тип агрегации (сумма, последнее значение, максимум и т.д. — в зависимости от доступных полей в UI).
- При необходимости задайте скрипт постобработки (см. Шаблоны и скрипты).
Привязка к плану
На карточке плана задайте:
- лимиты — какая метрика и какой потолок;
- metered charge — цена за единицу или ступенчатый тариф (
graduated); - recurring charge — правила рекуррентного начисления по метрике.
Данные сериализуются в структуру плана (поле уровня metricCharge в модели плана).
Отправка событий с вашего бэкенда
Используйте Merchant API metricNewEvent (или эквивалент в вашей версии клиента):
- идентификатор метрики;
- пользователь и контекст подписки;
- значение инкремента / свойства агрегации;
- при необходимости внешний идемпотентный ключ события.
События попадают в журнал; накопленное значение участвует в расчёте счёта.
Ограничения
- Для лимитных метрик соблюдайте лимит до отправки тяжёлых операций у себя, иначе API вернёт ошибку при превышении.
- Частота событий и пики нагрузки — согласуйте с лимитами облака (см. Ошибки и dunning).
Если вам нужны ограничения без отправки usage в BillBill (например, retention или feature flags), используйте Policy-квоты, а не metered-метрики.