# Каталог в Telegram Mini App: архитектура API, фильтры и подписки

> Каталог в Mini App строится на трёх частях: API с фильтрами и пагинацией, проверка пользователя по initData и воркер подписок, который сопоставляет новые объекты с сохранёнными критериями и шлёт уведомления через бота. Одна база и один API питают и сайт, и Mini App.

Дата: 2026-10-30 · Источник: https://oneswitch.ru/blog/katalog-v-telegram-mini-app-arhitektura/

Каталог внутри Telegram удобен тем, что пользователь не покидает мессенджер: ищет, сохраняет поиск и получает уведомления о новинках. Разберём архитектуру, на которой работает такой каталог, на примере аренды жилья и билетов.

## Три части системы

1. **API каталога:** отдаёт объекты по фильтрам.
2. **Авторизация:** определяет пользователя по подписанным данным Mini App.
3. **Воркер подписок:** сопоставляет новые объекты с сохранёнными критериями и отправляет уведомления.

Данные лежат в одной базе, поэтому каталог на сайте и в Mini App всегда одинаковый, а обновления видны сразу.

## API каталога

Минимальный набор методов:

| Метод | Назначение |
|---|---|
| `GET /api/items` | Список с фильтрами, сортировкой и пагинацией |
| `GET /api/items/{id}` | Карточка объекта: фото, описание, карта, контакт |
| `GET /api/places` | Подсказки для ввода района, города или направления |
| `POST /api/subscriptions` | Сохранить критерии поиска и включить уведомления |
| `GET /api/subscriptions` | Список подписок пользователя |
| `DELETE /api/subscriptions/{id}` | Отключить подписку |

Советы:
- **Пагинация по курсору,** а не по номеру страницы: список не «прыгает», когда появляются новые объекты.
- **Фильтры в параметрах запроса:** район, тип, диапазон цены, сортировка. Валидируйте значения на сервере.
- **Индексы в базе** по полям фильтров и сортировки. Без них каталог с тысячами записей начнёт тормозить.
- **Миниатюры вместо оригиналов.** Фото в списке должны быть лёгкими, оригиналы грузятся в карточке.
- **Кэш** для частых запросов: популярные фильтры можно хранить на минуты.

## Авторизация

Любой запрос, который работает с пользователем (подписки, избранное), должен нести подписанные данные Mini App, которые сервер проверяет. Подробный разбор с кодом: [как проверить initData в Python](/blog/proverka-initdata-telegram-mini-app-python/). Публичные методы каталога могут работать без авторизации.

## Подписки по критериям

Пользователь сохраняет поиск: район, тип, диапазон цены. Критерии удобно хранить как JSON рядом с идентификатором пользователя:

```sql
CREATE TABLE subscriptions (
    id          bigserial PRIMARY KEY,
    user_id     bigint NOT NULL,
    criteria    jsonb  NOT NULL,   -- {"district": "Son Tra", "type": "studio", "price_max": 10000000}
    active      boolean NOT NULL DEFAULT true,
    last_notified_item bigint NOT NULL DEFAULT 0
);
```

Воркер запускается по расписанию или по событию «появился новый объект». Для каждого нового объекта он находит подходящие подписки, отправляет сообщение и запоминает последний уведомлённый объект, чтобы не слать повторы.

Принципы:
- **Не дублируйте уведомления.** Храните, что уже отправлено каждому пользователю.
- **Группируйте.** Если появилось много объектов, отправьте один дайджест, а не десять сообщений.
- **Давайте простой выход.** В каждом уведомлении должна быть кнопка отключения подписки.
- **Соблюдайте лимиты Telegram** и обрабатывайте ошибки доставки: пользователь мог заблокировать бота.

## Уведомление с переходом в приложение

Сообщение отправляется ботом, а кнопка с `web_app` открывает карточку нового объекта в Mini App. Как отправить такую кнопку, описано в статье про [кнопки и меню бота на n8n](/blog/telegram-bot-n8n-knopki-menu-mini-app/).

## Что показывать и как обновлять

- **Свежесть данных важна.** В нашем каталоге аренды в Дананге база обновляется автоматически каждые 15 секунд, а новые объявления попадают в каталог и группу без ручной работы.
- **Показывайте дату добавления** и отметку «сегодня» для новых объектов.
- **Сохраняйте состояние интерфейса:** выбранные фильтры лучше запоминать, чтобы пользователь возвращался к тому же поиску.

## Что получилось у нас

По этой схеме построены Mini App в проектах [Da Nang House](/raboty/danang-house/) (каталог жилья с подписками) и [HotTrip](/raboty/hottrip/) (горящие билеты с радаром цен). Если нужен каталог в Telegram под вашу нишу, смотрите услугу [«Telegram-боты и Mini App»](/uslugi/telegram-boty-i-mini-app/) и [«Веб-приложения»](/uslugi/veb-prilozheniya/).

## Частые вопросы

### Нужен ли отдельный сайт, если есть Mini App?

Желательно да: сайт нужен для поиска в Google и Яндексе, а Mini App удерживает пользователей и присылает уведомления. Данные при этом общие.

### Сколько объектов выдержит такой каталог?

Тысячи объектов обслуживаются без проблем при правильных индексах, пагинации и миниатюрах. В нашем каталоге аренды их больше трёх тысяч.

### Как обновлять каталог автоматически?

Источники данных подключаются к базе по расписанию или через вебхуки, а новые записи сразу попадают в API и в воркер подписок.

### Можно ли делать подписки без Mini App, только в боте?

Можно, но в Mini App удобнее выбирать критерии и управлять подписками. Бот при этом остаётся каналом уведомлений.