/yandex-direct

Подключение к API Директа

Для работы нужны три вещи: OAuth-приложение, одобренная заявка этого приложения на доступ к API Директа и токен пользователя, которому доступен рекламный кабинет. Регистрация приложения и заявка — отдельные шаги; одного токена недостаточно.

Если подключение уже настроено, начните с проверки из README.md. Файл с токеном открывать и выводить не нужно. Если используете уже одобренное приложение, повторная заявка не нужна: переходите к получению своего токена.

1. Создайте OAuth-приложение

Войдите под Яндекс-аккаунтом владельца приложения и откройте создание приложения. Если начинаете с главной страницы OAuth, выберите «Для доступа к API или отладки».

Разрешение passport:business нужно для авторизации от имени организации в Яндекс ID. Для обычного подключения пользовательским токеном достаточно direct:api. Отдельный Wordstat API требует своего доступа.

После создания сохраните ClientID: это идентификатор приложения для заявки и получения токена. Для выбранного типа приложения адрес возврата уже задан Яндексом; настраивать свой сайт для получения токена вручную не требуется. Порядок регистрации: Яндекс OAuth, права Директа: документация Директа.

2. Подайте заявку в Директе

Под тем же аккаунтом откройте «Мои заявки» в настройках API. Если страница недоступна, проверьте наличие кабинета: Яндекс требует хотя бы одну созданную кампанию для доступа к настройкам API. Само подключение скилла не требует запуска показов. Условия подачи заявки.

При первом входе нажмите «Получить доступ к API» и примите соглашение, затем откройте «Мои заявки».

Создайте новую заявку, выберите ClientID своего приложения, укажите почту и сведения о программе, примите соглашение и отправьте форму. Если форма предлагает уровень доступа, выбирайте полный — для работы с настоящими кампаниями.

Ниже — заготовки для сведений о программе. Замените значения в квадратных скобках и оставьте только то, что соответствует вашему использованию. Названия полей формы могут отличаться; эти блоки объясняют содержание ответа.

Кто использует программу:

Локальный скилл для ИИ-ассистента. Его используют [владелец бизнеса / сотрудники компании / специалисты агентства] для работы с [собственным кабинетом / кабинетами клиентов]. Планируется [число] пользователей и [число] рекламных кабинетов.

Что делает программа:

Приложение помогает вести рекламу в Яндекс Директе по запросам пользователя. Оно выгружает статистику по выбранным целям, проверяет настройки и готовит изменения кампаний, объявлений, фраз и ставок. Перед записью показывает «было → станет», выполняет разрешённую пользователем задачу, затем перечитывает данные и показывает фактический результат. Токен хранится локально и не выводится. Финансовые операции не выполняются.

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

3. Техническое описание для заявки

Программа использует Python 3.11 или новее, JSON и стандартную библиотеку Python. Основной адрес — https://api.direct.yandex.com/json/v501/; API Live v4 используется для отдельных методов без подходящего аналога в v5. Скилл обращается к настоящему кабинету, поэтому проверку подключения выполняют командами чтения.

Частота зависит от числа кабинетов и задач: при подготовке заявки укажите свою ожидаемую нагрузку, не придумывая фиксированное число запросов. Кэш сокращает повторные чтения. Перечень методов сверьте с установленной версией скилла.

Дополните описание порядком обработки запросов:

• последовательность изменения: чтение → подготовка → проверка ограничений → «было → станет» → запись в пределах разрешённой задачи → перечитывание и сверка;
• обработку общей ошибки и ошибок отдельных объектов; частичный успех показывается отдельно;
• повторы временно неудавшихся чтений с задержкой; запись автоматически не повторяется после неопределённого результата, чтобы не создать дубли;
• постраничное чтение по LimitedBy, соблюдение размеров пакетов и остатка баллов Units;
• ожидание отчётов с учётом заголовка retryIn;
• хранение токена вне Git и отсутствие токенов, паролей и cookies в выводе и журнале.

Если форма требует спецификацию, приложите это описание отдельным документом. Такой состав технического описания приведён в официальном руководстве Директа.

Статус и замечания проверяйте на странице «Мои заявки». Яндекс указывает срок рассмотрения до семи дней. Если заявку отклонили, исправьте замечания и отправьте повторно. Заявка относится к ClientID; каждому пользователю приложения отдельная заявка не нужна. Порядок рассмотрения.

4. Получите токен и подключите скилл

Для локальной работы можно получить токен вручную. Войдите в браузере под пользователем, которому доступен нужный рекламный кабинет, и откройте адрес, заменив CLIENT_ID идентификатором своего приложения:

https://oauth.yandex.ru/authorize?response_type=token&client_id=CLIENT_ID

Разрешите доступ. Яндекс покажет токен: сохраните его непосредственно в локальном config/.env как YANDEX_DIRECT_TOKEN, через редактор, без передачи в чат. ClientID и Client secret не заменяют токен. Поле YANDEX_DIRECT_ACCOUNT и команды проверки описаны в README.md.

Этот способ подходит для собственного скрипта или небольшого числа представителей одного бизнеса. Для приложения с широкой аудиторией нужен удобный процесс авторизации пользователей. Получение токена вручную, варианты авторизации Директа.

При ошибке 58 проверьте одобрение заявки именно для ClientID, к которому относится токен. Остальные ошибки: ERRORS_AND_LIMITS.md.