Публичный API: ключи, права и сценарии
Публичный API позволяет управлять продвижением из своей системы: создавать проекты, добавлять страницы, запускать каскады, получать отчёты, а также работать с проверкой позиций, аудитами и сканами безопасности.
Документация
Полный справочник с параметрами и примерами запросов живёт на отдельной странице и всегда соответствует текущей версии. Здесь — только общая картина.
Ключи и права
- Ключ выпускается в кабинете, в разделе «API для разработчиков», и передаётся в заголовке авторизации.
- У ключа есть скоупы — наборы прав. Их четыре: продвижение (promotion), позиции (rank), аудиты (audit), безопасность (shield). Выдавайте только то, что действительно нужно.
- Ключ можно отозвать в любой момент, старые запросы с ним сразу перестанут работать.
- Действует ограничение на частоту запросов; в кабинете видна статистика вызовов и расходов по ключу.
Что доступно через API
| Группа | Возможности | Скоуп |
|---|---|---|
| Аккаунт | Профиль, баланс, персональная скидка, сведения о ключе | не требуется |
| Проекты и ссылки | Создание проектов, добавление и удаление страниц | promotion |
| Продвижение | Тарифы, предрасчёт, запуск каскада, статус и список размещений | promotion |
| Отчёты и бренд | Отчёт в JSON или PDF, настройки white-label (только Pro) | promotion |
| Rank Tracker | Проекты, ключевые слова, постановка проверки позиций | rank |
| SEO Audit | Оценка размера сайта, экспресс и полный обход, итоги с Health Score | audit |
| Shield | Подтверждение домена, запуск сканов, вердикт | shield |
Брендирование отчётов — не отдельный скоуп: оно входит в promotion и требует активной подписки Pro.
Типовой сценарий
- Создать проект и добавить в него страницы.
- Запросить расчёт стоимости для нужной конфигурации каскада.
- Запустить продвижение и сохранить идентификатор запуска.
- Периодически запрашивать статус, а по завершении — отчёт с публикациями.
Предрасчёт возвращает сумму со скидкой и текущий баланс, поэтому цену можно показать до списания; как она устроена — в статье тарифы и цена. Отчёт отдаёт только подтверждённые размещения, как в кабинете: значения статусов разобраны в статье отчёт и статусы.
Лимиты и коды ответов
| Ситуация | Ответ | Что делать |
|---|---|---|
| Ключ не передан, не найден или отозван | 401 | Проверить заголовок авторизации и сам ключ |
| У ключа нет нужного скоупа | 403 | Выпустить ключ с нужными правами |
| Не хватает денег на запуск | 402 | В ответе придут требуемая сумма, баланс, нехватка и ссылка на пополнение |
| Ошибка в параметрах или чужой домен ссылки | 422 | Поле с ошибкой указано в ответе |
| Слишком много запросов | 429 | Повторить через число секунд из ответа; лимит считается на ключ |
| Сервис временно выключен | 503 | Повторить позже: запуск не состоялся, деньги не списаны |
Списки возвращаются постранично — не более 100 элементов на страницу. Полный перечень кодов есть в справочнике.
Частые ошибки интеграции
- Повторный запуск той же ссылки. Пока по ней идёт активный каскад, новый не создаётся — в ответе придёт признак «уже активен». Это не сбой, повторять запрос циклом не нужно.
- Полный аудит без экспресса, скан Shield без подтверждения домена. Оба действия требуют подготовительного шага, иначе вернётся ошибка.
- Слишком частый опрос статуса. Каскад идёт часами: чаще раза в несколько минут спрашивать смысла нет, а в лимит частоты упереться легко.
- Пустой баланс в момент запуска. Предрасчёт мог пройти вчера, а деньги уйти на другие запуски — держите запас, см. баланс и пополнение.
White-label по API
Подписчики Pro могут задать логотип, название компании и цвет — тогда отчёты, полученные через API, будут оформлены под ваш бренд. Подробнее в статье про White-label.
Сервер хранит только хеш ключа, показать выпущенный ключ ещё раз невозможно — сохраните его сразу. Потеряли или засветили в репозитории: отзовите старый и выпустите новый, на уже запущенные каскады это не влияет.