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

В SourceCraft лежит репозиторий krivoshein-slon/direct: консольный клиент к API Яндекс.Директа v5. Пакет ydirect, версия в коде 0.1.0. Это скрипт управления кабинетом из терминала, а не лендинг услуги и не веб-интерфейс.

Клиент читает кабинет от имени пользователя: кто вошёл, какие клиенты у агентства, какие кампании в работе. README прямо говорит: это не веб-кабинет и не биддер. Секреты остаются в .env и в репозиторий не попадают.

Зачем отдельный клиент, если есть кабинет

Веб-интерфейс Директа удобен, когда нужно поправить объявление руками. Когда нужно быстро проверить токен, роль, список клиентов агентства или снять Id/State/Status кампаний без кликов по вкладкам, короче вызвать 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.

Как поставить и проверить

Клон по HTTPS, виртуальное окружение, зависимости из 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 советует включить «Веб-сервисы» и подставить URL для разработки.

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

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

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

Токен привязан к конкретному пользователю Директа. Его нельзя класть в чат и в репозиторий. .gitignore закрывает .env.

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

Клиент шлёт 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 сразу останавливается;
• нет токена: клиент просит сначала python -m ydirect auth;
• заявка на API не одобрена: код 58 на обоих контурах;
• агентский кабинет без --login / YANDEX_DIRECT_CLIENT_LOGIN: кампании смотрятся не у того логина;
• токен другого пользователя: whoami покажет чужой логин, не «сломанный API».

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

Нет смены ставок, паузы кампаний, загрузки объявлений и отчётов. Нет веб-морды. Страница direct.krivoshein.site это отдельный лендинг услуги, другой репозиторий. Путать их не стоит: у скрипта другой адрес, sourcecraft.dev/krivoshein-slon/direct.

Источники