ydirect: консольный клиент API Яндекс.Директа

18 августа 2026 года в SourceCraft появился репозиторий krivoshein-slon/direct: консольный клиент ydirect к API Яндекс.Директа v5, версия 0.1.0 под лицензией MIT. Он читает кабинет от имени пользователя: кто вошёл, какие клиенты у агентства, какие кампании в работе. Это не веб-кабинет и не биддер, а секреты остаются в .env и в git не попадают.

Зачем клиент, если есть кабинет

Веб-интерфейс Директа удобен, когда объявление правят руками. А когда нужно быстро проверить токен, роль, список клиентов агентства или снять статусы кампаний, проще один раз вызвать API из консоли, чем ходить по вкладкам.

ydirect умеет ровно четыре вещи: OAuth, «кто я», клиенты агентства и список кампаний. Для работы за клиента агентства в запрос добавляется заголовок Client-Login, а расход баллов API клиент печатает из заголовка Units.

Команды

auth открывает страницу OAuth и записывает токен в .env. auth —token сохраняет уже скопированный токен, auth —code меняет код подтверждения на токен. whoami вызывает clients.get и показывает логин, тип и роль. clients вызывает agencyclients.get. campaigns —login ЛОГИН вызывает campaigns.get и печатает Id, State, Status, Type и Name.

Установка и первый запуск

Нужен Python, виртуальное окружение и четыре зависимости из requirements.txt: httpx, pydantic, pydantic-settings и python-dotenv.

git clone https://git.sourcecraft.dev/krivoshein-slon/direct.git
cd direct
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt

В .env кладут идентификатор и секрет приложения Яндекса, потом туда же попадёт токен пользователя. Шаблон лежит в .env.example:

YANDEX_DIRECT_CLIENT_ID=
YANDEX_DIRECT_CLIENT_SECRET=
YANDEX_DIRECT_TOKEN=
YANDEX_DIRECT_SANDBOX=0
YANDEX_DIRECT_CLIENT_LOGIN=

Дальше авторизация и проверка:

.venv/bin/python -m ydirect auth
.venv/bin/python -m ydirect whoami

Без флагов auth открывает oauth.yandex.ru и просит вставить токен. Если браузера на машине нет, флаг —no-browser просто печатает ссылку. Если приложение в oauth.yandex.ru требует Callback URL, README советует включить платформу «Веб-сервисы» и указать адрес для разработки.

Доступ к API и код 58

Ключи приложения ещё не дают доступа к API Директа. Пока заявку в кабинете (Инструменты, затем API) не одобрили, и боевой контур, и песочница отвечают ошибкой 58. Это ограничение Яндекса, а не ошибка клиента.

Если доступ выдан только к песочнице, клиент сам повторит запрос на api-sandbox.direct.yandex.com. В коде за это отвечает call_with_sandbox_fallback: сначала боевой хост, а при кодах 54, 58, 513 и 1000 повтор в песочнице. Включить песочницу принудительно можно через YANDEX_DIRECT_SANDBOX=1.

Как устроен запрос

Клиент отправляет HTTPS POST на /json/v5/{service} с телом из method и params. Заголовки: Authorization: Bearer, Accept-Language: ru и Client-Login, когда работа идёт за клиента агентства. Ответ без JSON или с полем error превращается в DirectAPIError с кодом, описанием и RequestId, по которому потом удобно писать в поддержку.

Кампании печатаются по одной на строку. Если API вернул LimitedBy, клиент предупреждает, что выборка неполная, и первый экран не стоит принимать за весь кабинет.

Где обычно ломается

Нет YANDEX_DIRECT_CLIENT_ID в .env, и auth останавливается сразу. Нет токена, и клиент просит сначала выполнить auth. Заявка на API не одобрена, и оба контура отвечают кодом 58. В агентском кабинете забыли —login или YANDEX_DIRECT_CLIENT_LOGIN, и смотрят кампании не того логина. Токен выписан другому пользователю, и whoami честно показывает чужой логин, хотя API тут ни при чём.

Токен привязан к конкретному пользователю Директа. Не отправляйте его в чат и не коммитьте: .env закрыт в .gitignore, но скопировать его в issue можно и руками. Если нужно освежить работу с git, есть короткая инструкция.

Чего в репозитории нет

Изменения ставок, паузы кампаний, загрузки объявлений и отчётов нет, веб-интерфейса тоже. Сайт direct.krivoshein.site это отдельный лендинг услуги из другого репозитория, не путайте их. Новости самого Директа я собирал в заметке про поисковый автотаргетинг.

Источники и ссылки


Комментарии загружаются…