Авито через API и MCP: 231 метод, семь форм отказа и ловушка со статусами

Обзор

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

За этой парой ключей стоит куда больше, чем принято думать. Это не «выгрузка объявлений»: доступны переписка с покупателями, отзывы и ответы на них, статистика просмотров и контактов, расходы по дням, продвижение с ценой за целевое действие, заказы с доставкой, остатки товара, вакансии с откликами и резюме.

Mira подключает этот API целиком — 231 метод в одиннадцати разделах — и отдаёт его в Claude через MCP. Ниже — что там есть на самом деле, где документация расходится с поведением и почему часть вещей стоит знать до того, как вы начнёте писать интеграцию сами.

Что доступно продавцу

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

Ловушки, которые стоит знать заранее

Это не придирки к документации. Каждый пункт ниже проверен живым вызовом, и каждый способен незаметно испортить ответ.

Список объявлений по умолчанию возвращает не все объявления

У метода GET /core/v1/items есть параметр status, и его значение по умолчанию — active. Снятые, отклонённые и заблокированные объявления в ответ не попадают.

Насколько это важно, видно на живом примере. У продавца с одним объявлением в статусе «снято с публикации» запрос без параметров возвращает пустой список. Тот же запрос со всеми статусами возвращает объявление. Интеграция, не разворачивающая статусы явно, на вопрос «сколько у меня объявлений» ответит «нисколько» — и будет формально права, а по сути нет.

Общего числа в ответе нет

meta содержит только page и per_page. Поля с общим количеством не существует, и единственный признак конца списка — страница короче запрошенной. Пагинация, ждущая total, будет листать вечно.

Заголовка и цены у одного объявления не бывает

Метод списка отдаёт title, price и url. Метод одного объявления — статус, сроки размещения и применённые услуги, но ни заголовка, ни цены. Это не пробел в параметрах, а устройство: за названием надо идти в список.

Деньги то в копейках, то в рублях — общего правила нет

В stats/v2/items расходы приходят в копейках. В соседнем stats/v2/spendings — в рублях, дробным числом. В продвижении и CPA — копейки. В ценах услуг — рубли. У комиссии за сделку своя единица: сотые доли процента, где 150 означает 1,5%.

Единого правила у площадки нет, и вывести его нельзя. Ошибка здесь стоит дорого: расход в сто раз больше настоящего в отчёте выглядит как катастрофа, а комиссия в сто раз больше — это уже реальные деньги.

Отказ приходит в семи разных формах

{"error": {"code", "message"}} в основном контуре, {"message"} в настройке цены целевого действия, {"error": {"message", "slug"}} в иерархии аккаунтов, {"result": {"error": {…}}} в CPA, {"message", "details": []} в продвижении, {"code", "message"} в коллтрекинге, {"errors": []} в тарифах.

Разбор «как в основном контуре» потеряет причину отказа в шести разделах из семи — и человек прочитает «Авито ответил 400» вместо «недостаточно средств на кошельке».

Токен живёт сутки, и обновить его нельзя

Схема выдачи — client_credentials. В ответе нет refresh_token, и это не упущение: в этой схеме его не бывает. Истёкший токен не обновляют, а выпускают заново по той же паре ключей. Интеграция, написанная по привычной схеме «обновить по refresh-токену», проработает ровно 24 часа и остановится.

Отдельная тонкость: на истёкший токен Авито отвечает 403, а не 401, как принято. Код 401 приходит в рекламном контуре. Различить «токен протух» и «не тот доступ» по коду нельзя.

Ограничения частоты различаются в 500 раз

Карточка объявления — 500 запросов в минуту. Список объявлений — 25. Аналитика профиля и расходы — один запрос в минуту. Опрос аналитики в цикле упрётся в предел на втором вызове.

Покупка услуги может пройти, даже если ответ пришёл с ошибкой

Документация метода покупки продвижения говорит об этом прямо: если ответ вернулся без кода ошибки, услуга всё-таки могла быть куплена. Повторять вызов вслепую нельзя — надо перечитать применённые услуги и посмотреть, что получилось.

Создать обычное объявление через API нельзя

Такого метода нет. Публикация идёт только через автозагрузку: продавец формирует XML-фид, Авито забирает его по расписанию или по команде. Вакансии — исключение, у них своя публикация.

Как это выглядит через MCP

MCP — открытый протокол, по которому Claude подключается к внешним данным и действиям. Вместо написания клиента вы подключаете Авито в кабинете Mira двумя полями и спрашиваете обычными словами.

Какие объявления у меня на Авито и в каком они статусе?

Claude вызывает список с развёрнутыми статусами, а не с умолчанием, и отвечает по существу — включая снятые.

Сколько я потратил на продвижение за август и сколько получил контактов?

Расходы и контакты лежат в разных методах с разными единицами измерения. Приведение к рублям делает интеграция, а не модель — значит в ответе не окажется суммы, увеличенной в сто раз.

Есть непрочитанные сообщения от покупателей?

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

Что защищено от случайного действия

В API Авито 231 метод, из них 103 меняют данные, а 27 тратят деньги: покупка продвижения, ставки за целевое действие, комиссия за сделку, публикация вакансии, запрос контактов из резюме, рассылка скидок покупателям.

Все они закрыты барьером записи. Источник, подключённый на чтение, физически не может ничего изменить — запрос не уходит. А чтобы разрешение на запись нельзя было обойти случайно, признак «меняет данные» хранится рядом с адресом метода, а не отдельным списком: разойтись им негде.

Отдельно отмечено то, что видно снаружи. Сообщение покупателю — не «запись в наши данные», а письмо живому человеку от имени продавца. Ответ на отзыв виден всем. Такие действия проходят тот же барьер, что и трата денег.

Что это даёт на практике

Продавцу. Ответ на «что происходит» без захода в кабинет: объявления, просмотры, контакты, расходы, непрочитанные сообщения — одним вопросом. Отзывы, оставшиеся без ответа, находятся сразу, а они влияют на выдачу.

Агентству. Несколько кабинетов клиентов в одном месте, сравнение расходов и отдачи между ними, отчёт без ручного сведения выгрузок.

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

Как подключить

1. Кабинет продавца Авито → Настройки → Avito API → зарегистрировать приложение.
2. Скопировать Client ID и Client Secret.
3. В Mira: проект → источники → Авито → вставить оба ключа.

Проверка подключения сама узнает номер вашего кабинета и сохранит его — вводить вручную ничего не нужно. Дальше Авито доступен и в чате Mira, и через MCP-сервер в Claude, Cursor или другом клиенте с поддержкой протокола.