Visi Partner API

Поток ваших объявлений машиночитаемо. Версия 1, база https://api.visi.su/api/v1

API отдаёт те же объявления, которые приходят вам в Telegram: новинки по вашим поискам и снижения цены. Telegram-уведомления при этом продолжают работать — API их не заменяет, а дополняет.

Быстрый старт: где взять ключ

1. Откройте бота Visi — в Telegram или в MAX.
2. Включите тариф с API: Пробный (бесплатно, 24 часа, 1 поиск) или API — команда /subscribe.
3. Добавьте поиск: пришлите боту ссылку на страницу поиска Авито, ЦИАН, Домклик, Дром или Авто.ру.
4. Откройте 👤 Личный кабинет (команда /cabinet) и нажмите 🔑 Получить API-ключ. Ключ придёт отдельным сообщением. Потеряли — там же кнопка 🔑 Показать ключ.
5. Проверьте:

   curl -H "X-API-Key: visi_xxx" "https://api.visi.su/api/v1/events?limit=5"

   Пустой список events — это нормально: события появятся с первым новым объявлением по вашему поиску.

Не хотите писать код — подключите вебхук: ключ для него не нужен, адрес задаётся в том же личном кабинете. Коротко обо всём этом в самом боте — команда /api.

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

Аутентификация

Ключ выдаёт бот: 👤 Личный кабинет → 🔑 Получить API-ключ (подробно — быстрый старт). Передавайте его любым из двух заголовков:

Authorization: Bearer visi_xxxxxxxxxxxxxxxxxxxx
X-API-Key: visi_xxxxxxxxxxxxxxxxxxxx

Ключ = доступ ко всей вашей выдаче. Не публикуйте его и не кладите в репозиторий. Утёк — перевыпустите в личном кабинете: старый перестанет работать сразу.

GET /events

Возвращает события строго после курсора, по возрастанию.

Пример

curl -H "Authorization: Bearer visi_xxx" \
  "https://api.visi.su/api/v1/events?since=0&limit=50"

Ответ

{
  "events": [
    {
      "event_id": 12345,
      "type": "new_listing",
      "created_at": "2026-09-08T12:34:56Z",
      "search_id": "6f1e...",
      "search_label": "Ноутбуки Asus Москва",
      "listing": {
        "id": "9c02...",
        "source": "avito_goods",
        "title": "Ноутбук ASUS TUF Gaming A15",
        "price": 45000,
        "old_price": null,
        "url": "https://www.avito.ru/...",
        "address": "Москва, Хорошевский",
        "description": "...",
        "photo_urls": ["https://...", "https://..."],
        "seller": {
          "id": "/brands/i99145353",
          "name": "Николай",
          "type": "private",
          "url": "https://www.avito.ru/brands/i99145353",
          "rating": 5.0,
          "reviews_count": 40,
          "closed_count": 28,
          "reliable": true
        },
        "area": null, "floor": null, "floors_total": null,
        "year": null, "mileage": null,
        "engine_type": null, "transmission": null,
        "specs": [
          {"id": 110392, "name": "Состояние", "value": "Хорошее"},
          {"id": 122027, "name": "Процессор", "value": "AMD Ryzen 7 3750H"},
          {"id": 122031, "name": "Оперативная память", "value": "16 ГБ"}
        ],
        "condition": "Хорошее",
        "market_price": "below",
        "delivery": true
      }
    }
  ],
  "next_cursor": 12345
}

Курсор

Храните next_cursor у себя и передавайте его в since следующим запросом. Курсор — монотонный номер события, а не время: он не теряет события, пришедшие в одну секунду, и переживает любой перезапуск вашего бота. Если новых событий нет, events пуст, а next_cursor равен переданному since.

Типы событий

Снижений цены по одному объявлению может быть несколько — каждое приходит отдельным событием. Связывать их между собой удобно по listing.id: он не меняется.

Поля объявления

Набор ключей одинаков для всех площадок. Неприменимые к категории поля равны null: у квартиры не будет mileage, у ноутбука — floor.

Характеристики

Блок «Характеристики» со страницы объявления — тот же, что видит человек на сайте: состояние, процессор, память, диагональ. Плоский список, в том же порядке, что на площадке.

Три состояния поля, и они разные: null — характеристики ещё не приехали, их не удалось прочитать или объявление не с Авито; [] — страницу прочитали, блока у объявления нет; список — характеристики.

В выдаче площадки характеристик нет — они есть только на странице самого объявления, и мы идём за ней после того, как отдали объявление: само объявление ждать их не должно. Обычно на это уходит 1–3 секунды, примерно у трети объявлений 4–10 секунд, а когда новых объявлений приходит сразу много, до пары минут.

Когда характеристики приехали, приходит отдельное событие listing_specs с тем же listing.id: обновите у себя карточку объявления с этим id. Новым объявлением или снижением цены оно не является. Обрабатывайте listing_specs обязательно — иначе объявления останутся у вас без характеристик. Если вы опрашиваете ленту редко, исходное событие может прийти уже с характеристиками, а listing_specs следом их просто повторит.

Характеристики есть только у объявлений Авито (avito, avito_goods, avito_tech, avito_auto). У остальных площадок поле всегда null.

Состояние

condition — состояние товара так, как его указал продавец: «Новое», «Отличное», «Хорошее», «Удовлетворительное», «Требуется ремонт», «Б/у» и т.п. Оно же первой строкой лежит в specs под названием «Состояние»; отдельным полем — потому что id этой характеристики в каждой категории свой (у телефонов один, у ноутбуков другой), и фильтровать по нему неудобно.

Приезжает вместе с specs: null, пока их нет, и обновляется тем же событием listing_specs. null при непустом specs — продавец состояние не указал или у категории его нет (недвижимость).

Оценка цены

market_price — оценка цены объявления, которую ставит сам Авито: below — «Цена ниже рыночной», market — «Рыночная цена», above — «Цена выше рыночной», null — Авито цену не оценил (или оценка ещё не приехала, см. ниже).

below и market Авито показывает прямо в выдаче — они есть сразу в событии new_listing. above бывает только на странице объявления, поэтому приезжает позже, вместе с характеристиками, событием listing_specs. До него у дорогого объявления null — это «пока неизвестно», а не «дёшево».

Только у товаров и техники Авито (avito_goods, avito_tech); у остальных площадок всегда null. Чаще всего оценка есть у телефонов, телевизоров, ноутбуков и видеокарт, в части категорий Авито её не ставит вовсе.

Доставка

delivery — true, если продавец отправляет Авито Доставкой, false — если нет, null — ещё не известно. Как и above, есть только на странице объявления и приезжает событием listing_specs. Только объявления Авито.

Продавец

Репутация продавца (rating, reviews_count, closed_count, reliable) есть только у объявлений Авито и обычно сразу в new_listing. Бывает, что Авито не показывает в выдаче профиль продавца: тогда id и name равны null, а рейтинг и отзывы всё равно есть.

id и url сейчас есть только у объявлений Авито, и не у всех: площадка не всегда показывает продавца в выдаче. Если продавец неизвестен, поле равно null. Для фильтрации используйте id, а не name: имена повторяются.

Скрыть продавца можно и в Telegram-боте (кнопка «🚫 Скрыть продавца» под объявлением). Скрытые там продавцы в API тоже не попадают.

Шлюз: выдача и карточка по запросу

Лента /events отдаёт то, что нашли мы по вашим поискам. Шлюз — наоборот: вы сами говорите, какую страницу и когда скачать, и получаете ответ сразу. Ссылку не нужно заводить поиском в боте. Входит в тарифы API, отдельно не оплачивается. На Пробном тарифе шлюз тоже работает — 50 запросов на весь пробный период, чтобы проверить интеграцию.

GET /gate/search — выдача по ссылке

Страница выдачи по ссылке на поиск или каталог — в том же формате объявления, что в /events. Площадки — те же, что у бота:

Набор ключей объявления один на все площадки. У недвижимости заполнены area, floor, floors_total, у авто — year, mileage, engine_type, transmission; чего у площадки нет — null.

curl -G -H "X-API-Key: visi_xxx" \
  --data-urlencode "url=https://www.avito.ru/moskva/telefony?q=iphone+15&s=104" \
  "https://api.visi.su/api/v1/gate/search"

{
  "fetched_at": "2026-10-19T12:00:05Z",
  "url": "https://www.avito.ru/moskva/telefony?q=iphone+15&s=104",
  "source": "avito_tech",
  "page": 1,
  "has_next": true,
  "count": 50,
  "items": [ { "id": "8544830284", "title": "iPhone 15 128 ГБ", "price": 52000, ... } ],
  "cached": false,
  "daily_remaining": 1499
}

Страницы

По умолчанию — первая страница. Следующие — параметром page (1–100) или ссылкой со страницы N, как она открыта в браузере (p=3 на Авито и ЦИАН, page=3 на auto.ru, /page3/ на Дроме, offset=40 на Домклике). Каждая страница — один запрос к лимитам, как первая. У недвижимости Авито пока только первая страница (400 на остальные).

curl -G -H "X-API-Key: visi_xxx"   --data-urlencode "url=https://www.avito.ru/moskva/noutbuki?s=104"   --data "page=2"   "https://api.visi.su/api/v1/gate/search"

has_next: true — страница полная, следующая, скорее всего, есть. Листайте, пока не придёт has_next: false или пустой items. Пока вы листаете, выдача живёт: новые объявления сдвигают страницы, и на стыках возможны повторы и пропуски — склеивайте по id. Глубина у площадок ограничена; большую категорию надёжнее резать на узкие ссылки (ценовые диапазоны, подкатегории, города) и листать каждую.

Отличие от ленты одно: id здесь — номер объявления на площадке (тот, что в ссылке на него), а не наш идентификатор. specs и condition в выдаче всегда null — характеристики есть только на странице объявления, за ними — /gate/item.

Порядок объявлений на Авито и auto.ru — как в ссылке; нужны свежие сверху — добавьте в ссылку сортировку по дате, как в браузере (на Авито — s=104). ЦИАН, Домклик и Дром — всегда сначала новые.

Ссылку на объявление /gate/search не принимает (400, за ней — /gate/item); поиск по карте ЦИАН — тоже, нужна ссылка со списка.

GET /gate/item — карточка объявления

Ссылка на одно объявление — тех же площадок, что у выдачи: avito.ru, cian.ru, domclick.ru (кроме новостроек), auto.drom.ru, auto.ru. Карточка у всех одного вида; чего у площадки нет — null.

curl -G -H "X-API-Key: visi_xxx" \
  --data-urlencode "url=https://www.avito.ru/moskva/telefony/iphone_15_8544830284" \
  "https://api.visi.su/api/v1/gate/item"

{
  "fetched_at": "2026-10-19T12:00:07Z",
  "source": "avito_tech",
  "item": {
    "id": "8544830284",
    "url": "https://www.avito.ru/moskva/telefony/iphone_15_8544830284",
    "title": "iPhone 15 128 ГБ",
    "price": 52000,
    "description": "Полный текст описания",
    "address": "Москва, ул. Тверская, 1",
    "location": {"name": "Москва", "lat": 55.75, "lng": 37.61},
    "category": {"id": 84, "slug": "telefony"},
    "photo_urls": ["https://..."],
    "seller": {"id": "/brands/xxx", "name": "Магазин", "type": "shop",
               "url": "https://www.avito.ru/brands/xxx",
               "rating": 4.9, "reviews": 74},
    "specs": [{"id": 110392, "name": "Состояние", "value": "Хорошее"}],
    "condition": "Хорошее",
    "published": "сегодня в 07:07",
    "active": true
  },
  "cached": false,
  "daily_remaining": 1498
}

Ссылка на выдачу в /gate/item — 400, за ней — /gate/search. Новостройки Домклика (sale__new_flat__…) пока не поддерживаются — 400.

Лимиты шлюза

• Выдача: до 6 запросов в минуту, карточки: до 12 в минуту, подряд без пауз — до 3. Превышение — 429 с Retry-After.
• В сутки: 1500 запросов шлюза вместе (сутки по UTC). Остаток — daily_remaining в каждом ответе. На Пробном — 50 запросов на весь пробный период; daily_remaining показывает остаток пробника.
• Повторы одной ссылки: в пределах 20 с отдаём тот же ответ (cached: true) — площадки обновляют выдачу не чаще.
• 503 — сейчас нет места, повторите через Retry-After секунд. 502 — страницу получить не удалось, повторите позже. За оба лимит суток не списывается. 404 — площадка говорит, что такой страницы или объявления нет. 400 — ссылка не на поддерживаемую площадку или не того вида (поиск вместо объявления и наоборот).

Для постоянного слежения за поиском шлюз не нужен: заведите поиск в боте, и новинки будут приходить в /events сами, быстрее и без лимитов шлюза.

Лимиты

• Частота: до 2 запросов в секунду (один раз в 0.5 с). Превышение — 429 с заголовком Retry-After: 1.
• Окно хранения: 7 дней. События старше удаляются; курсор при этом остаётся валидным.
• Задержка: событие появляется в ленте в тот же момент, когда объявление уходит вам в Telegram, и отдаётся первым же запросом.

Коды ответа

Как опрашивать

1. При первом запуске: since=0 — получите всё, что накопилось за окно.
2. Сохраните next_cursor в своём хранилище.
3. Запрашивайте с сохранённым since — не чаще раза в 0.5 секунды.
4. Курсор двигайте только после того, как обработали батч: упали на середине — следующий запрос отдаст его снова.
5. На 429 — подождать Retry-After; на 5xx — повторить с тем же курсором.

Вебхук: события приходят к вам сами

Если у вас нет своего кода, который опрашивал бы /events, — подключите вебхук. Мы сами отправим каждое событие на ваш адрес. Так подключаются Albato, Make, n8n, CRM и любой сервис, который умеет принимать входящий вебхук. Ключ API для этого не нужен.

Albato: подключение по шагам

Ничего программировать не нужно. Понадобятся два окна: Albato в браузере и бот Visi (в Telegram или в MAX). Займёт около десяти минут.

Шаг 1. Получите адрес в Albato

1. Откройте Albato и войдите в свой кабинет.
2. В меню слева нажмите «Подключения», затем кнопку «Добавить подключение».
3. В поиске наберите Вебхук и выберите его.
4. Название можно оставить как есть. Остальные поля не заполняйте. Нажмите «Далее».
5. Albato покажет длинный адрес, он начинается с https://. Скопируйте его целиком — выделите и нажмите Ctrl+C (или кнопку копирования рядом с адресом). Нужен именно адрес из самого окна, обычно он выглядит как https://h.albato.ru/wh/…. Ссылка из адресной строки браузера (наверху окна) не подойдёт.

Шаг 2. Вставьте адрес в Visi

1. Откройте бота Visi и нажмите «👤 Личный кабинет».
2. Нажмите «🔗 Вебхук (Albato и др.)» — откроется окно с одним полем.
3. Вставьте адрес в поле (Ctrl+V, на телефоне — долгое нажатие → «Вставить») и нажмите синюю кнопку справа от поля.
4. Появится зелёная надпись «Вебхук подключён». Это окно пока не закрывайте.

Шаг 3. Создайте связку в Albato

1. В Albato в меню слева нажмите «Мои связки», затем «Создать новую связку».
2. Выберите сервис «Вебхук», событие «Входящий webhook» и подключение, которое создали на шаге 1. Нажмите «Продолжить».
3. Нажмите кнопку «Ожидать вебхук». Albato начнёт ждать первое сообщение от Visi.

Шаг 4. Отправьте тестовое объявление

1. Вернитесь в окно Visi из шага 2 и нажмите «Отправить тестовое событие».
2. В Visi появится зелёная надпись «Тестовое событие принято», а в Albato — список полей объявления. Это выдуманное объявление-образец, по нему Albato узнаёт, какие данные будут приходить.

Шаг 5. Выберите, что делать с объявлением

1. В Albato добавьте действие: куда отправлять объявление — в таблицу, в CRM, в мессенджер.
2. В поля действия подставьте данные объявления из списка. Самые нужные:

   Поле в Albato	Что в нём
   listing.title	название объявления
   listing.price	цена в рублях
   listing.url	ссылка на объявление
   listing.address	адрес
   listing.description	текст объявления
   listing.photo_url	ссылка на первое фото
   listing.seller.name	имя продавца
   search_label	название вашего поиска в Visi
   type	new_listing — новое объявление, price_drop — снизилась цена

3. Сохраните и запустите связку. С этого момента каждое новое объявление по вашим поискам приходит в Albato само.

Важно про расход Albato. Каждое объявление запускает вашу связку один раз, а Albato считает выполненные действия. Если по поиску приходит очень много объявлений, сузьте его фильтрами в боте Visi (стоп-слова, обязательные слова) — фильтры действуют и на вебхук.

Если что-то не получилось

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

Другие сервисы

Make, n8n, CRM, свой сервер — то же самое: получите в своём сервисе адрес входящего вебхука и вставьте его в боте: 👤 Личный кабинет → 🔗 Вебхук. Кнопка «Отправить тестовое событие» пришлёт образец со всеми полями.

Что приходит

POST на ваш адрес, Content-Type: application/json, одно событие в одном запросе. Форма та же, что у элемента events выше, плюс три поля:

{
  "event_id": 12345,
  "type": "new_listing",
  "created_at": "2026-10-05T12:34:56Z",
  "test": false,
  "search_id": "6f1e...",
  "search_label": "Ноутбуки Asus Москва",
  "listing": {
    "id": "9c02...",
    "source": "avito_goods",
    "title": "Ноутбук ASUS TUF Gaming A15",
    "price": 45000,
    "old_price": null,
    "url": "https://www.avito.ru/...",
    "photo_url": "https://...",
    "...": "остальные поля объявления — как в /events"
  }
}

В Albato вложенные поля называются через точку: listing.title, listing.price, listing.url, listing.seller.name.

Правила доставки

• Приходят события new_listing и price_drop, тип — в поле type. Событие listing_specs в вебхук не отправляется, чтобы одно объявление не запускало вашу связку дважды. Поэтому поля со страницы объявления (specs, delivery, market_price = above) в вебхуке приходят, только если успели приехать до отправки, — чаще всего они null.
• Ваш сервис должен ответить кодом 2xx за 10 секунд. Иначе мы повторим то же событие: через 5, 10, 20 секунд и далее, но не реже раза в 5 минут. Следующие события ждут своей очереди — порядок сохраняется.
• Событие старше 6 часов в вебхук уже не уйдёт (в /events оно остаётся все 7 дней).
• При подключении и при смене адреса отправка начинается с новых событий: то, что было раньше, не досылается.
• Изредка событие может прийти дважды (ваш сервис принял его, но ответ до нас не дошёл). Отличить повтор можно по event_id.
• Адрес — только https://, один на аккаунт. Фильтры из бота действуют и здесь. Уведомления в Telegram остаются.

Чего API не делает

Только чтение. Поиски добавляются, приостанавливаются и удаляются в Telegram-боте — там же настраиваются фильтры (стоп-слова, обязательные слова, скрытые продавцы). Фильтры применяются и к API: отсеянное ими в ленту не попадает.