Обновлено: 23.09.2026

Достижения

Ачивки программы лояльности: каталог достижений клуба с условиями выдачи, прогресс болельщика, статистика выдач и таблица лидеров. Сами достижения и их условия настраиваются в админ-панели клуба — через API они доступны на чтение, чтобы показать знаки и прогресс в приложении или на сайте.

Обзор методов

Метод	Путь	Описание
`GET`	`/achievements`	Каталог достижений
`GET`	`/achievements/{id}`	Карточка достижения
`GET`	`/achievements/{id}/stats`	Статистика выдач
`GET`	`/achievements/leaderboard`	Таблица лидеров
`GET`	`/users/{user_id}/achievements`	Достижения болельщика

Каталог достижений

Эндпоинт

GET /achievements

Список достижений клуба с условиями выдачи, наградой и минимальным уровнем лояльности. Выключенные достижения возвращаются только с is_active=false.

Параметры

Параметр	Где	Тип	Обязателен	Описание
`is_active`	`query`	boolean	нет	Только активные (true) или только выключенные (false). По умолчанию возвращаются все.
`limit`	`query`	integer	нет	Размер страницы, от 1 до 100. По умолчанию — 20.

Запрос

curl "https://api.virazh.io/v1/achievements?is_active=true" \
  -H "Authorization: Bearer sk_test_51H..."

Ответ

{
  "data": [
    {
      "id": "ach_3f10",
      "name": "Свой на трибуне",
      "description": "Десять домашних матчей подряд без пропусков",
      "image": "https://cdn.virazh.io/ach/3f10.png",
      "image_back": "https://cdn.virazh.io/ach/3f10-back.png",
      "points": 500,
      "xp": 150,
      "min_loyalty_status": "silver",
      "is_active": true,
      "conditions": [
        { "rule": "attendance_streak", "target_value": 10 }
      ]
    }
  ],
  "has_more": false
}

Поля ответа

Поле	Тип	Описание
`data`	`array<Achievement>`	Достижения с полями id, name, description, image, image_back, points, xp, min_loyalty_status, is_active.
`data[].conditions`	`array<Condition>`	Условия выдачи: rule и target_value. Достижение выдаётся, когда выполнены все условия.
`has_more`	`boolean`	Есть ли следующая страница.

Карточка достижения

Эндпоинт

GET /achievements/{id}

Одно достижение с условиями и счётчиком выдач. Правила условий: registration, tickets_bought_total, season_tickets_bought, playoff_tickets_bought, tickets_per_match, early_bird_days, match_day_purchase, subscriptions_bought, subscription_renewal, matches_attended_total, home_matches_attended, attendance_streak, no_show, birthday_attendance, season_spend_total, merch_spend_total, merch_purchases, merch_unique_skus, loyalty_status_reached.

Параметры

Параметр	Где	Тип	Обязателен	Описание
`id`	`путь`	string	да	Идентификатор достижения, например ach_3f10.

Запрос

curl https://api.virazh.io/v1/achievements/ach_3f10 \
  -H "Authorization: Bearer sk_test_51H..."

Ответ

{
  "id": "ach_3f10",
  "name": "Свой на трибуне",
  "points": 500,
  "xp": 150,
  "min_loyalty_status": "silver",
  "conditions": [
    { "rule": "attendance_streak", "target_value": 10 }
  ],
  "awarded_count": 348
}

Поля ответа

Поле	Тип	Описание
`id`	`string`	Идентификатор достижения.
`points`	`integer`	Баллы на бонусный счёт при выдаче.
`xp`	`integer`	Опыт для перехода по уровням лояльности — отдельный от баллов счётчик.
`min_loyalty_status`	`string \| null`	Уровень, ниже которого достижение не выдаётся.
`conditions`	`array<Condition>`	Правило (rule) и порог (target_value) каждого условия.
`awarded_count`	`integer`	Сколько болельщиков уже получили достижение.

Статистика выдач

Эндпоинт

GET /achievements/{id}/stats

Выдачи достижения по неделям за выбранный период вместе с матчами клуба на той же оси — чтобы видеть, что всплеск дала домашняя серия, а не рассылка.

Параметры

Параметр	Где	Тип	Обязателен	Описание
`id`	`путь`	string	да	Идентификатор достижения.
`period`	`query`	string	нет	Период: last_7_days, last_30_days, current_season, all_time. По умолчанию — current_season.

Запрос

curl "https://api.virazh.io/v1/achievements/ach_3f10/stats?period=current_season" \
  -H "Authorization: Bearer sk_test_51H..."

Ответ

{
  "awarded_total": 128,
  "weeks": [
    { "week_start": "2026-09-01", "awarded": 12 },
    { "week_start": "2026-09-08", "awarded": 41 }
  ],
  "events": [
    { "date": "2026-09-10", "opponent": "Авангард", "is_home": true }
  ]
}

Поля ответа

Поле	Тип	Описание
`awarded_total`	`integer`	Всего выдач за период.
`weeks`	`array<Week>`	Недели периода с полями week_start и awarded.
`events`	`array<Event>`	Матчи клуба внутри периода: date, opponent, is_home.

Таблица лидеров

Эндпоинт

GET /achievements/leaderboard

Болельщики по числу собранных достижений. Фильтруется по уровню лояльности — лидерборд разбирается по статусам, а не листается целиком.

Параметры

Параметр	Где	Тип	Обязателен	Описание
`loyalty_status`	`query`	string	нет	Фильтр по уровню: silver, gold, platinum.
`search`	`query`	string	нет	Поиск по имени или телефону болельщика.
`limit`	`query`	integer	нет	Размер страницы, от 1 до 100. По умолчанию — 20.

Запрос

curl "https://api.virazh.io/v1/achievements/leaderboard?loyalty_status=gold&limit=20" \
  -H "Authorization: Bearer sk_test_51H..."

Ответ

{
  "data": [
    { "rank": 1, "user_id": "usr_8f21c", "name": "Иван Петров", "achievements_count": 14, "loyalty_status": "gold" },
    { "rank": 2, "user_id": "usr_71bd0", "name": "Мария Орлова", "achievements_count": 11, "loyalty_status": "gold" }
  ],
  "has_more": true
}

Поля ответа

Поле	Тип	Описание
`data`	`array<LeaderboardRow>`	Строки с полями rank, user_id, name, achievements_count, loyalty_status.
`has_more`	`boolean`	Есть ли следующая страница.