Loyalty API — Программы лояльности

Обзор модуля лояльности

Модуль лояльности Trigly позволяет создавать балльные программы лояльности с tier-системой (уровнями), автоматическим начислением баллов за покупки и бонусами. 14 эндпоинтов для полного управления программой.

Модели данных:

Модель	Описание
LoyaltyProgram	Программа лояльности организации
LoyaltyMember	Участник программы (связь с Customer)
LoyaltyTransaction	Транзакция баллов (начисление, списание, бонус)

API prefix: /api/v1/loyalty

Программа лояльности

Создание программы

POST /api/v1/loyalty/programs

Тело запроса:

{
  "name": "Бонусная программа",
  "points_per_purchase": 10,
  "currency_per_point": 1.0,
  "min_redeem_points": 100,
  "rules_json": {
    "welcome_bonus": 50,
    "birthday_bonus": 200,
    "referral_bonus": 100,
    "tier_multipliers": {
      "bronze": 1.0,
      "silver": 1.5,
      "gold": 2.0,
      "platinum": 3.0
    }
  }
}

Параметры:

Поле	Тип	Описание
name	string	Название программы
points_per_purchase	integer	Баллов за каждый рубль покупки
currency_per_point	float	Стоимость 1 балла в рублях при списании
min_redeem_points	integer	Минимум баллов для списания
rules_json	object	Правила бонусов и множителей

Правила (rules_json):

• welcome_bonus — количество баллов при регистрации в программе. Начисляются автоматически при вызове POST /enroll.
• birthday_bonus — баллы в день рождения. Начисляются через Flow Builder (триггер: birthday event).
• referral_bonus — баллы за приглашение друга.
• tier_multipliers — множители начисления по уровням. Gold-участник с множителем 2.0 получает вдвое больше баллов за покупку.

Список программ

GET /api/v1/loyalty/programs?page=1&per_page=20

Пагинированный список программ организации.

Получение программы

GET /api/v1/loyalty/programs/{program_id}

Обновление программы

PUT /api/v1/loyalty/programs/{program_id}

Обновляет настройки программы. Изменения применяются к новым транзакциям — ранее начисленные баллы не пересчитываются.

Удаление программы

DELETE /api/v1/loyalty/programs/{program_id}

Удаляет программу и все связанные данные (участники, транзакции). Необратимая операция.

Участники программы

Регистрация участника

POST /api/v1/loyalty/programs/{program_id}/enroll

Тело запроса:

{
  "customer_id": "uuid"
}

Ответ (201):

{
  "id": "uuid",
  "program_id": "uuid",
  "customer_id": "uuid",
  "points_balance": 50,
  "total_points_earned": 50,
  "total_points_redeemed": 0,
  "tier": "bronze",
  "joined_at": "2026-03-11T10:00:00Z"
}

Поведение:

1. Создаёт запись LoyaltyMember с начальным балансом 0
2. Если welcome_bonus > 0 в rules_json — автоматически начисляет приветственные баллы
3. Создаёт транзакцию типа bonus с reference_id = "welcome_bonus"
4. UniqueConstraint(program_id, customer_id) — контакт может быть участником программы только один раз

Список участников

GET /api/v1/loyalty/programs/{program_id}/members?page=1&per_page=20&tier=gold

Параметры фильтрации:

• tier — фильтр по уровню (bronze, silver, gold, platinum)
• min_balance — минимальный баланс баллов
• page, per_page — пагинация

Получение участника

GET /api/v1/loyalty/members/{member_id}

Информация об участнике по customer_id

GET /api/v1/loyalty/programs/{program_id}/members/by-customer/{customer_id}

Транзакции баллов

Начисление баллов

POST /api/v1/loyalty/members/{member_id}/earn

Тело запроса:

{
  "points": 500,
  "reference_id": "order_12345",
  "description": "Покупка на 5000 руб"
}

Поведение:

1. Начисляет баллы с учётом tier-множителя. Gold-участник с множителем 2.0 получит 1000 баллов вместо 500.
2. Обновляет points_balance и total_points_earned
3. Проверяет условия повышения уровня (tier upgrade)
4. Создаёт транзакцию типа earn

Tier-система:

Уровень	Порог (total_points_earned)	Множитель
bronze	0	1.0x
silver	500	1.5x
gold	2000	2.0x
platinum	5000	3.0x

Повышение уровня происходит автоматически при достижении порога total_points_earned. Понижение уровня не предусмотрено.

Списание баллов

POST /api/v1/loyalty/members/{member_id}/redeem

Тело запроса:

{
  "points": 200,
  "reference_id": "order_12346",
  "description": "Скидка на заказ"
}

Поведение:

1. Проверяет, что points >= min_redeem_points (из настроек программы)
2. Проверяет, что points_balance >= points (достаточно баллов)
3. Уменьшает points_balance, увеличивает total_points_redeemed
4. Создаёт транзакцию типа redeem с отрицательным значением points

Ошибки:

• 400 Bad Request — недостаточно баллов для списания
• 400 Bad Request — количество баллов меньше минимума для списания

Корректировка баллов

POST /api/v1/loyalty/members/{member_id}/adjust

Тело запроса:

{
  "points": -100,
  "reason": "Возврат товара по заказу #12345"
}

Ручная корректировка баланса (положительная или отрицательная). Создаёт транзакцию типа adjust. Используется для возвратов, компенсаций, ручных бонусов.

История транзакций

GET /api/v1/loyalty/members/{member_id}/transactions?page=1&per_page=20&type=earn

Параметры фильтрации:

• type — тип транзакции: earn, redeem, expire, adjust, bonus
• page, per_page — пагинация

Ответ:

{
  "items": [
    {
      "id": "uuid",
      "member_id": "uuid",
      "transaction_type": "earn",
      "points": 500,
      "balance_after": 1250,
      "reference_id": "order_12345",
      "created_at": "2026-03-11T10:00:00Z"
    }
  ],
  "total": 45,
  "page": 1,
  "per_page": 20,
  "pages": 3
}

Баланс участника

GET /api/v1/loyalty/members/{member_id}/balance

Ответ:

{
  "points_balance": 1250,
  "total_points_earned": 3500,
  "total_points_redeemed": 2250,
  "tier": "gold",
  "currency_value": 1250.0,
  "next_tier": "platinum",
  "points_to_next_tier": 1500
}

currency_value = points_balance * currency_per_point — денежный эквивалент баланса.

Статистика программы

GET /api/v1/loyalty/programs/{program_id}/stats

Ответ:

{
  "total_members": 5000,
  "active_members_30d": 1200,
  "total_points_issued": 2500000,
  "total_points_redeemed": 1800000,
  "total_points_outstanding": 700000,
  "redemption_rate": 72.0,
  "tier_distribution": {
    "bronze": 3000,
    "silver": 1200,
    "gold": 600,
    "platinum": 200
  },
  "avg_points_per_member": 500.0,
  "avg_transactions_per_member": 12.5
}

Интеграция с другими модулями

CDP (Customer Data Platform)

Участники программы лояльности связаны с контактами CDP через customer_id. Все данные о покупках, активности и предпочтениях доступны для сегментации.

Примеры сегментов:

• «Gold-участники с балансом > 1000 баллов» — для VIP-акций
• «Участники с баллами, истекающими в этом месяце» — для стимулирования списания
• «Bronze-участники с > 3 покупками» — кандидаты на повышение уровня

Campaigns (Кампании)

Используйте данные лояльности в шаблонах кампаний:

• {{ loyalty_balance }} — текущий баланс
• {{ loyalty_tier }} — текущий уровень
• {{ points_to_next_tier }} — баллов до следующего уровня

Flow Builder

Создайте автоматические потоки:

1. Tier Upgrade — поздравление при повышении уровня + бонусные баллы
2. Points Expiring — напоминание об истекающих баллах
3. Inactivity — стимулирование неактивных участников специальным предложением

AI Engine

AI-скоринг учитывает данные лояльности при расчёте ai_score. Участники с высоким балансом и активным списанием получают более высокий скор.

Типы транзакций

Тип	Описание	Значение points
earn	Начисление за покупку	Положительное
redeem	Списание (скидка)	Отрицательное
expire	Сгорание баллов	Отрицательное
adjust	Ручная корректировка	Любое
bonus	Автоматический бонус	Положительное

Рекомендации

1. Простые правила: «1 рубль = 1 балл, 100 баллов = скидка 10 рублей» понятнее сложных формул
2. Welcome bonus: 50-100 баллов при регистрации — стимулирует первую покупку
3. Tier-множители: разница между уровнями должна быть ощутимой (1.0x → 1.5x → 2.0x → 3.0x)
4. Срок действия: настройте expire транзакции для баллов старше 12 месяцев
5. Коммуникация: информируйте о балансе в каждом письме (footer шаблона)
6. Геймификация: покажите прогресс до следующего уровня в профиле клиента