Avito Ads MCP

Показывает, готов ли сервер работать: заданы ли AVITO_ADS_CLIENT_ID, AVITO_ADS_CLIENT_SECRET и AVITO_ADS_ACCOUNT_ID, нет ли среди них испорченного значения, какое окружение выбрано (production или sandbox) и какой адрес API используется. Ничего не отправляет в сеть и не возвращает ни client secret, ни токен. Вызовите это первым, если инструменты отвечают, что учётных данных нет или что аккаунт не найден: ответ называет конкретную переменную и что с ней не так, вместо повторения одной и той же ошибки на каждом вызове.

Takes no parameters.

Возвращает юридические реквизиты рекламного аккаунта, к которому привязан сервер: inn, kpp, ogrn, shortName, longName, legalAddress, actualAddress и блоки contact / manager. Аргументов не принимает — аккаунт задан в AVITO_ADS_ACCOUNT_ID и не выбирается для отдельного вызова. Денежных сумм не содержит (для них get_balance), данных кампаний тоже. Как и у всех инструментов здесь, в ответе есть apiPointBalance: остаток баллов API на текущую неделю (квота пополняется по понедельникам в 00:00 UTC).

Takes no parameters.

Возвращает текущий баланс настроенного рекламного аккаунта в рублях: balance (реальные деньги) и bonusBalance (бонусные рубли, которые можно тратить только на рекламу). Аргументов не принимает. Это срез на текущий момент, а не история — расход за период дают инструменты статистики. Аккаунт не пополняет.

Takes no parameters.

ТОЛЬКО ПЕСОЧНИЦА: создаёт тестовый аккаунт рекламодателя и возвращает его accountID. Сервер отклоняет вызов, если не задано AVITO_ADS_ENVIRONMENT=sandbox, и такой отказ не стоит балла API. contact — непустой объект, например {"name":"Иван Иванов","email":"[email protected]","phone":"+79001234567"}; пустой отклоняется до отправки запроса. Два вызова создают два аккаунта. Изменить или удалить аккаунт нельзя, а сервер продолжает работать с AVITO_ADS_ACCOUNT_ID: новый id сам не подхватывается, для работы с ним его нужно прописать в конфигурации.

Перечисляет дочерние (суб-)аккаунты настроенного агентского аккаунта. Каждая запись — {account:{id,shortName}, contract}. Балансов здесь НЕТ, для них есть list_child_accounts_with_balances. Возвращает всех дочерних за один вызов: без постраничной выдачи, фильтров и поиска. `apiPointBalance` в любом ответе этого сервера — остаток баллов API на текущую неделю (квота пополняется по понедельникам в 00:00 UTC); по нему и стоит рассчитывать частоту вызовов.

Takes no parameters.

Тот же список, что и list_child_accounts, плюс баланс каждого дочернего аккаунта: {balance, bonusBalance} в рублях и бонусных рублях. Позволяет увидеть, у кого кончились деньги, перед transfer_funds / transfer_bonus и убедиться, что перевод дошёл. Показывает только балансы дочерних аккаунтов — баланс родительского даёт get_balance.

Takes no parameters.

Создаёт дочерний аккаунт без права оплаты под настроенным агентским аккаунтом и возвращает {accountID, clientKey, clientSecret} — собственные учётные данные API нового аккаунта, которые выдаются только здесь, поэтому сохранить их нужно сразу. Без права оплаты означает, что аккаунт не может пополнить свой баланс сам: деньги приходят из родительского через transfer_funds. Создать аккаунт с правом оплаты, переименовать или удалить аккаунт, а также прочитать секрет заново нельзя. Два вызова создают два аккаунта.

Переводит РЕАЛЬНЫЕ ДЕНЬГИ с настроенного аккаунта на другой (обычно на один из дочерних): `amount` рублей, минимум 1. Через этот API перевод необратим — нет ни отмены, ни отката, ни журнала переводов; вернуть деньги можно только встречным переводом, а для него аккаунт-получатель должен уметь отправлять средства. При успехе возвращается пустой объект data: любой ответ без ошибки означает, что перевод выполнен, и повторять вызов нельзя. После сетевой или серверной ошибки исход неизвестен — прежде чем повторять, следует проверить list_child_accounts_with_balances, иначе деньги уйдут дважды.

Переводит бонусные рубли (`bonusBalance` — промо-средства, которыми можно оплачивать рекламу, но нельзя вывести деньгами) с настроенного аккаунта на другой: `amount` бонусных рублей, минимум 1. Правила те же, что у transfer_funds: через этот API перевод необратим, пустой объект data означает, что он прошёл, а после сетевой или серверной ошибки следует проверить list_child_accounts_with_balances, а не повторять вызов. Переводит только бонусы — реальные деньги идут через transfer_funds.

Регистрирует рекламодателя (контрагента ОРД) под аккаунтом и возвращает {id} плюс apiPointBalance (остаток недельных баллов API). На этот id ссылаются кампании и договоры. Юридические реквизиты должны совпадать с госреестром: inn (10 цифр для ul, 12 для ip), ogrn и оба адреса; kpp — только для юрлиц (ul). legalRole задаёт роль по ОРД: rd (рекламодатель), ra (агентство), rr (распространитель). Эндпоинтов изменения и удаления нет: ошибочного рекламодателя можно только заместить новым, поэтому сначала стоит поискать готовую запись через list_advertisers.

Возвращает одну страницу рекламодателей, зарегистрированных под аккаунтом: {total, items, page, limit, hasNextPage} плюс apiPointBalance (остаток недельных баллов API). В каждом элементе id, shortName, longName, inn, ogrn, kpp, legalAddress, actualAddress, legalType (ul|ip) и legalRole (rd|ra|rr). Сузить выдачу можно через filter.ids / filter.inns / filter.roles; полнотекстового поиска нет, совпадения по названиям придётся искать самостоятельно. limit — 1..100 (по умолчанию 20); нумерация page с 1.

Регистрирует договор ОРД между аккаунтом и рекламодателем и возвращает {id} плюс apiPointBalance (остаток недельных баллов API). Набор обязательных полей зависит от type: service требует subject, isReportingRequired, date и number (cid отклоняется); intermediary — всё то же плюс object и isFundsAllocationToPrincipal (cid отклоняется); external — только cid (parentId отклоняется). Юридические реквизиты исполнителя передаются в intermediary — они обязательны, если не задан parentId; с parentId запись становится дополнительным соглашением к тому договору, и intermediary в ней быть не должно. Эндпоинтов изменения и удаления нет, поэтому ошибочный договор остаётся на аккаунте навсегда.

Возвращает одну страницу договоров, зарегистрированных под аккаунтом: {total, items, page, limit, hasNextPage} плюс apiPointBalance (остаток недельных баллов API). В каждом элементе id, type, number, date, subject, object (действие по договору), cid, description (тип контрагента), parentId (заполнен у дополнительных соглашений) и юридические реквизиты клиента и исполнителя. Сузить выдачу можно через filter.ids / filter.numbers / filter.clients (id рекламодателей) / filter.contractors. limit — 1..100 (по умолчанию 20); нумерация page с 1.

Перечисляет рекламные кампании аккаунта постранично. Возвращает {total, items, page, limit, hasNextPage} плюс apiPointBalance — остаток недельных баллов API, которые пополняются по понедельникам в 00:00 UTC. У каждой кампании есть id, name, status, budget (рубли), paymentModel (CPM/CPC), campaignType, startDate/endDate, advertiserId, contractId, managerID и отметки времени. Поля фильтра объединяются по И, и каждый список оставляет только перечисленные в нём значения. Через этот API нельзя создать, изменить, приостановить, возобновить, заархивировать или удалить кампанию и нельзя тронуть её таргетинг — единственные доступные где-либо изменения это change_group_budget и change_group_price для группы объявлений.

Перечисляет группы объявлений аккаунта постранично. Возвращает {total, items, page, limit, hasNextPage} плюс apiPointBalance (остаток недельных баллов API). Группа — тот уровень, на котором лежат деньги: в каждом элементе id, name, campaignID, status, budget и price (ставка) в рублях, paymentModel, campaignType, advertiserID, haveCreative и отметки времени. Эти два числа меняют change_group_budget / change_group_price — других изменяемых полей во всём дереве рекламных объектов нет. Создать, переименовать, приостановить, возобновить или удалить группу здесь нельзя, таргетинг групп не выведен.

Перечисляет креативы аккаунта — сами объявления — постранично. Возвращает {total, items, page, limit, hasNextPage} плюс apiPointBalance (остаток недельных баллов API). У каждого креатива есть id, name, title, description, buttonText, link, status, groupID, campaignID, advertiserID, paymentModel, campaignType и legalInfo (данные рекламного реестра / ERID). Только чтение: загрузить, изменить, отправить на модерацию, приостановить или удалить креатив через этот API нельзя — изменять можно только бюджет и ставку группы объявлений.

Задаёт бюджет одной группы объявлений в рублях (не меньше 1). Значение заменяет текущий бюджет, а не прибавляется к нему, поэтому повторный вызов безопасен. Принимают его только группы с ручным управлением ставками, остальным API отказывает. Возвращает подтверждение API плюс apiPointBalance. Изменить бюджет кампании, ставку (для неё есть change_group_price) или статус группы нельзя — приостановить, возобновить или удалить группу этот API вообще не умеет. Текущий бюджет стоит сначала посмотреть через list_groups.

Задаёт ставку одной группы объявлений (в API она называется price) в рублях (не меньше 1). Единица зависит от paymentModel группы: рубли за 1000 показов при CPM, рубли за клик при CPC. Значение заменяет текущую ставку, а не прибавляется к ней, поэтому повторный вызов безопасен. Принимают его только группы с ручным управлением ставками. Возвращает подтверждение API плюс apiPointBalance. Изменить бюджет (для него есть change_group_budget) или статус группы нельзя — приостановить, возобновить или удалить группу этот API вообще не умеет. Текущую ставку показывает поле price в list_groups.

Статистика ОДНОЙ кампании за период дат с разбивкой по группам и креативам: {campaign, groups[], creatives[]}. У каждой сущности есть data[] (по строке на день, с отметкой timestamp) и totalData (итог за период). Метрики в строке: views (показы), clicks (клики), ctr, spend (расход), spendBonus, cpm, cpc, а для видеокампаний ещё videoViews25/50/75/100, q25/q50/q75 и vtr; деньги в рублях, коэффициенты передаются как есть. Период включает обе границы, формат YYYY-MM-DD, длительность не больше 100 дней. Сводить несколько кампаний вместе не умеет, гранулярности мельче дня нет; campaignId даёт list_campaigns. Тратит недельные баллы API; apiPointBalance в ответе — остаток до пополнения квоты в понедельник в 00:00 UTC, поэтому один широкий период предпочтительнее многих узких вызовов.

Статистика по перечисленным группам одной кампании: плоский массив, по записи на группу объявлений ({id, name, paymentModel, campaignType, data[] по дням, totalData за период}). Метрики те же, что у campaign_stats — views (показы), clicks (клики), ctr, spend (расход), spendBonus, cpm, cpc, квартили видео, vtr, — деньги в рублях. Поле groupIds обязательно: инструмент сужает выборку, а не перечисляет её. Период включает обе границы, формат YYYY-MM-DD, длительность не больше 100 дней. Итогов по кампании не возвращает; чтобы охватить все группы кампании, есть campaign_stats с той же разбивкой. Тратит недельные баллы API; apiPointBalance в ответе — остаток до пополнения квоты в понедельник в 00:00 UTC, поэтому один широкий период предпочтительнее многих узких вызовов.

Статистика по перечисленным креативам одной кампании: плоский массив, по записи на креатив ({id, name, groupId, paymentModel, campaignType, data[] по дням, totalData за период}). Метрики те же, что у campaign_stats — views (показы), clicks (клики), ctr, spend (расход), spendBonus, cpm, cpc, квартили видео, vtr, — деньги в рублях. Поле creativeIds обязательно: инструмент сужает выборку, а не перечисляет её. Период включает обе границы, формат YYYY-MM-DD, длительность не больше 100 дней. Итогов по кампании не возвращает; чтобы охватить все креативы кампании, есть campaign_stats с той же разбивкой. Тратит недельные баллы API; apiPointBalance в ответе — остаток до пополнения квоты в понедельник в 00:00 UTC, поэтому один широкий период предпочтительнее многих узких вызовов.

Перечисляет пользователей с доступом к рекламному аккаунту — по одной записи {id, role, hasLoggedIn} на пользователя, где role это admin или viewer, а hasLoggedIn показывает, входил ли приглашённый хоть раз. Эти id принимают set_user_role и delete_user. Работает в пределах настроенного аккаунта: пользователей дочернего аккаунта не покажет. Вместе с данными возвращает apiPointBalance (остаток недельных баллов).

Takes no parameters.

Выдаёт существующему пользователю Авито доступ к рекламному аккаунту с указанной ролью. userId — числовой id пользователя Авито; пригласить по почте или телефону и создать аккаунт Авито этот инструмент не может. Если доступ уже есть, роль меняется через set_user_role. Возвращает подтверждение API плюс apiPointBalance.

Меняет роль пользователя, у которого уже есть доступ к рекламному аккаунту. Назначение той же роли, что стоит сейчас, ничего не меняет. Доступ не выдаёт (для этого add_user) и не отзывает (для этого delete_user). Возвращает подтверждение API плюс apiPointBalance.

Отзывает доступ пользователя к рекламному аккаунту. Операция разрушительная: вернуть доступ можно только через add_user с явно указанной ролью. Аккаунт Авито этого человека, его кампании и историю расходов не удаляет. Возвращает подтверждение API плюс apiPointBalance.

Универсальный запрос к любому пути API Авито Рекламы — для эндпоинтов, у которых нет отдельного инструмента, например GET "v1/account/{accountID}/balance" или POST "v1/account/{accountID}/campaigns". Пути задаются относительно базы API и привязаны к аккаунту: подстановка {accountID} заменяется на настроенный id аккаунта, путь с другим аккаунтом отклоняется, как и путь, выходящий за базу API. `body` отправляется как JSON. Через него доступны все пишущие эндпоинты — funds-transfer, bonus-transfer, delete-user и create-*, — причём без клиентских проверок, которые делают отдельные инструменты, и ничего из этого не отменить; когда специальный инструмент есть, лучше взять его: transfer_funds / delete_user / create_*. confirmWrite=true — явное подтверждение того, что путь может писать, поэтому перед установкой флага путь стоит проверить: POST используется и для безобидных чтений — списков и статистики, — которым флаг тоже нужен. GET выполняется без ограничений. Возвращает сырой ответ плюс apiPointBalance (остаток недельных баллов).