API Яндекс Вебмастера 4.1 даёт программный доступ к сайтам пользователя, статистике, важным URL, поисковым запросам, ссылкам и отдельным операциям управления. Это REST API с OAuth 2.0. Для большинства методов сначала получают user-id, затем host-id конкретного сайта.
Что можно автоматизировать
API позволяет получать список сайтов, сведения и сводную статистику, данные важных страниц, поисковых запросов и внешних ссылок. Через отдельные методы можно добавлять и удалять сайты, запускать подтверждение прав и работать с очередью переобхода. Набор операций нужно сверять в обзоре ресурсов текущей версии.
Для массовой отправки URL удобна собственная очередь с повторами и журналом. API Index-Now.ru уже объединяет несколько каналов отправки и хранит статусы задач, но факт приёма API всё равно нужно отделять от последующего обхода.
Что подготовить до начала
- Приложение зарегистрировано в Яндекс OAuth и имеет утверждённый client_id.
- Запрошены только необходимые scopes, например webmaster:hostinfo и webmaster:verify.
- Токен хранится в секретах сервера, а не в браузерном коде и репозитории.
- Определены лимиты, журнал запросов и сценарий обновления токена.
Первый запрос к API
- Создайте OAuth-приложение и получите согласие пользователя на нужные права.
- Передайте токен в заголовке Authorization: OAuth
. - Вызовите GET https://api.webmaster.yandex.net/v4/user и сохраните user-id.
- Получите список сайтов через /v4/user/{user-id}/hosts и выберите host-id.
- Вызовите нужный ресурс сайта, обработайте HTTP-код, JSON и ограничения метода.
Базовые ресурсы API
Путь строится вокруг пользователя и конкретного host-id.
| Сигнал или статус | Что он означает | Что делать |
|---|---|---|
| GET /v4/user | Возвращает ID текущего пользователя | Выполняйте после авторизации и кешируйте безопасно |
| GET /hosts | Список доступных сайтов | Сопоставляйте host-id с каноническим адресом |
| GET /summary | Сводные показатели сайта | Храните дату среза и не смешивайте разные периоды |
| POST /recrawl/queue | Добавляет URL в очередь переобхода | Сначала проверяйте квоту и валидность URL |
Ошибки интеграции
Большинство сбоев связано с токеном, областью прав или неправильным host-id.
| Проблема | Вероятная причина | Исправление |
|---|---|---|
| 401 Unauthorized | Токен отсутствует, истёк или неверен | Обновите OAuth и проверьте формат заголовка |
| 403 Forbidden | Нет scope или доступа к сайту | Запросите минимально нужное право и проверьте владельца |
| 404 для ресурса | Неверный user-id, host-id или версия пути | Получайте ID заново из текущего API |
| 429 или квота | Слишком частые запросы | Добавьте очередь, backoff и кеширование |
Контроль результата и приёмка работы
Перед контрольным прогоном подготовьте всё, от чего зависит результат: Приложение зарегистрировано в Яндекс OAuth и имеет утверждённый client_id; Запрошены только необходимые scopes, например webmaster:hostinfo и webmaster:verify; Токен хранится в секретах сервера, а не в браузерном коде и репозитории; Определены лимиты, журнал запросов и сценарий обновления токена. Проверьте не только основной пример, но и второй URL или ресурс того же типа. В отчёте сохраните время, адрес проверяемого объекта, аккаунт и роль, фактический статус в интерфейсе, а для технической операции — HTTP-код и конечный URL.
GET /v4/user означает: возвращает id текущего пользователя. Контрольное действие: выполняйте после авторизации и кешируйте безопасно. GET /hosts означает: список доступных сайтов. Контрольное действие: сопоставляйте host-id с каноническим адресом. GET /summary означает: сводные показатели сайта. Контрольное действие: храните дату среза и не смешивайте разные периоды. POST /recrawl/queue означает: добавляет url в очередь переобхода. Контрольное действие: сначала проверяйте квоту и валидность url.
Если воспроизводится «401 Unauthorized», проверьте гипотезу «Токен отсутствует, истёк или неверен» и выполните следующее: обновите oauth и проверьте формат заголовка. Если воспроизводится «403 Forbidden», проверьте гипотезу «Нет scope или доступа к сайту» и выполните следующее: запросите минимально нужное право и проверьте владельца. Если воспроизводится «404 для ресурса», проверьте гипотезу «Неверный user-id, host-id или версия пути» и выполните следующее: получайте id заново из текущего api. Если воспроизводится «429 или квота», проверьте гипотезу «Слишком частые запросы» и выполните следующее: добавьте очередь, backoff и кеширование.
Порядок приёмки для «API Яндекс Вебмастера: возможности, авторизация и примеры запросов»: Разделить OAuth-токены пользователей и системные журналы; Не записывать токен в URL, клиентские логи и сообщения об ошибках; Сохранять метод, host-id, код ответа и время, но маскировать секреты; Проверять изменения версии API и модели данных перед обновлением интеграции. Отдельно укажите, что уже подтверждено live-проверкой, а что появится только после следующего обхода или обновления отчёта. Это не даст повторять отправку ради одного статуса в панели и сохранит воспроизводимую историю изменений.
Безопасная эксплуатация
- Разделить OAuth-токены пользователей и системные журналы.
- Не записывать токен в URL, клиентские логи и сообщения об ошибках.
- Сохранять метод, host-id, код ответа и время, но маскировать секреты.
- Проверять изменения версии API и модели данных перед обновлением интеграции.
Частые вопросы
Какая версия API актуальна?
Официальный портал сейчас указывает версию 4.1. Перед разработкой проверьте заголовок и историю документации.
Можно ли через API гарантировать индексацию?
Нет. API передаёт заявки и данные Вебмастера. Решение об обходе и поиске остаётся у Яндекса.
Нужен ли сервисный аккаунт?
API работает от имени пользователя через Яндекс OAuth. Модель доступа отличается от сервисных аккаунтов Google Cloud.
Что читать дальше
Источники
Факты, названия разделов и ограничения сверены с документацией. Интерфейсы, тарифы и лимиты сервисов могут меняться.