API x10seo: автоматизация для агентств

В этом туториале вы научитесь подключать API x10seo к рабочим процессам агентства: создавать кампании пакетно, забирать отчёты в собственный BI, отправлять клиентам уведомления о ходе работ. Тема критична для SEO-команд в Рунете, которые ведут 10+ проектов под Яндекс одновременно и тратят часы на ручное копирование данных между кабинетом x10seo и клиентскими отчётами. По отраслевым публикациям SEO-сектора на Хабре, доля автоматизированных процессов в агентствах в 2025 году выросла на 40% — без API масштабирование портфеля становится невозможным. Разберём пошагово: получение токена, первый запрос, обработку webhook, типовые ошибки. К концу статьи у вас будет рабочий скрипт-каркас, готовый к адаптации под ваш стек.

Что такое API x10seo и зачем он агентствам?

API x10seo — программный интерфейс платформы для управления ПФ-кампаниями через HTTP-запросы без входа в веб-кабинет. Через него агентство может создавать кампании, добавлять ключевые фразы, пополнять баланс, забирать отчёты по поведенческим факторам и подключать внешние сервисы — CRM, Power BI, Telegram-бота, Google Sheets.

Главный сценарий для агентств — централизованная панель управления десятками клиентов. Без API менеджер тратит 15–20 минут в день на каждого клиента: зайти в кабинет, скопировать метрики, вставить в отчёт, проверить остаток. Для портфеля из 30 проектов это до 7,5 часов ручного труда ежедневно. С API эта рутина сворачивается в несколько cron-скриптов и одну дашборд-страницу.

Платформа x10seo создавалась с расчётом на B2B-клиентов: 2 814+ сайтов в работе, 10M+ кликов отгружено, 0 банов клиентов с 2023 года — статистика, на которой агентства строят SLA своим заказчикам. API даёт техническую возможность это масштабировать без потери качества.

Что понадобится для подключения?

Перед стартом убедитесь, что у вас есть всё необходимое — это сэкономит минимум полчаса на возврате к недостающим компонентам.

• Активный аккаунт x10seo с правами администратора рабочего пространства.
• HTTP-клиент: curl, Postman, Insomnia или библиотека языка (axios, requests, fetch).
• Базовое знание REST: GET/POST/PUT, заголовки авторизации, JSON.
• Публичный URL для приёма webhook (HTTPS обязателен) или туннель ngrok/cloudflared для локальных тестов.
• Секрет-стораж: переменные окружения, Vault, AWS Secrets Manager — куда положить токен.
• Время: 30 минут на сценарий «получить отчёты», 60 минут с обработкой webhook.

Шаг 1: Получить API-ключ в кабинете x10seo

Ключ доступа — это токен, который заменяет логин-пароль во всех запросах. Никогда не храните его в публичных репозиториях GitHub: автоматические сканеры утечек скомпрометируют ключ за минуты.

1. Войдите в кабинет по адресу app.x10seo.ru под учётной записью с ролью администратора.
2. Откройте боковое меню и перейдите в «Настройки» → «Интеграции».
3. Нажмите кнопку «Создать API-ключ» в правом верхнем углу.
4. Введите осмысленное название, например «CRM-агентства» или «BI-выгрузка», чтобы потом отличать ключи между собой.
5. Выберите scope: read для отчётов, write для управления кампаниями, full для всего сразу.
6. Скопируйте ключ — он показывается ровно один раз. Сразу положите в менеджер секретов.
7. Добавьте переменную окружения X10SEO_API_KEY в .env вашего сервиса.
8. Если потеряли ключ — отзовите его и создайте новый, восстановить старый невозможно.

Лимит активных ключей — 10 на рабочее пространство, лимит запросов — 100 в минуту на ключ. Для нагрузочных сценариев заведите отдельные ключи под разные сервисы: дашборд, cron-выгрузку, webhook-консьюмер. Это упростит ротацию при компрометации.

Шаг 2: Сделать первый запрос и получить список проектов

Проверьте, что ключ работает. Минимальный пример на curl:

curl -H 'Authorization: Bearer $X10SEO_API_KEY' https://app.x10seo.ru/api/v1/projects

В ответ придёт JSON-массив проектов с полями id, domain, status, balance_clicks, created_at. Если получили 401 — проверьте префикс Bearer и отсутствие лишних пробелов в ключе. Если 403 — у токена не тот scope. Если 429 — превышен rate-limit, добавьте экспоненциальный backoff.

Для production-кода используйте библиотеку: на Node.js это axios с интерцептором ретраев, на Python — httpx с настроенным tenacity. Не пишите retry-логику с нуля — на ней легко допустить ошибку, которая взорвёт rate-limit и затронет все ваши проекты.

Шаг 3: Создать кампанию через API

Самый частый агентский сценарий — пакетное создание проектов из CRM-карточки клиента. POST-запрос на /api/v1/projects принимает тело со следующими полями:

• domain — домен сайта без протокола (example.ru).
• region_id — числовой код региона Яндекса (213 — Москва, 2 — СПб).
• phrases — массив ключевых фраз с целевыми URL и приоритетом.
• daily_clicks — целевой объём кликов в сутки.
• schedule — окно работы по МСК (например, с 9:00 до 22:00).
• strategy — safe, balanced или aggressive.

В ответ придёт project_id и черновик кампании. До запуска проверьте поля через GET и только потом активируйте PATCH-запросом со статусом active. Двухшаговая активация защищает от случайного запуска кривой конфигурации с лишними нулями.

Шаг 4: Настроить webhook для уведомлений

Polling списка проектов раз в минуту — антипаттерн: тратите rate-limit, видите изменения с задержкой. Webhook решает обе проблемы и снимает нагрузку с обеих сторон.

1. В разделе «Интеграции» нажмите «Добавить webhook».
2. Укажите HTTPS-URL вашего эндпоинта (например, https://api.agency.com/x10seo/hook).
3. Выберите события: project.completed, balance.low, task.failed, report.ready.
4. Сгенерируйте секрет — им будет подписан каждый запрос через HMAC-SHA256.
5. Сохраните секрет в переменной X10SEO_WEBHOOK_SECRET на стороне приёмника.
6. Реализуйте проверку подписи: HMAC от сырого тела запроса должен совпадать с заголовком X-X10seo-Signature.
7. Возвращайте HTTP 200 за 5 секунд — иначе платформа сделает 3 ретрая с экспоненциальной задержкой.

Для отладки используйте сервис webhook.site — публичный приёмник, который показывает payload и заголовки любого запроса. Удобно для первой проверки до подключения боевого хендлера.

Какие сценарии автоматизации работают лучше всего?

За полтора года поддержки API мы видим повторяющиеся успешные паттерны у агентств. Вот пятёрка топ-сценариев, которые окупаются за первый месяц:

• Агентский дашборд в Retool/Metabase — единая таблица всех клиентов с метриками Яндекс Метрики и x10seo рядом, обновление раз в час.
• Авто-пополнение баланса при остатке 20% — webhook balance.low триггерит платёжный шлюз клиента и присылает чек.
• Telegram-боты для проджектов — мгновенные алерты о задачах, требующих вмешательства (паузы, низкий CTR, низкий сигнал ранжирования).
• Еженедельные отчёты в Google Sheets — cron на воскресенье забирает данные через API и формирует sheet для каждого клиента.
• Связка с API Яндекс Метрики — корреляция ПФ-сигналов с динамикой позиций для аналитики ROI.

Если ваш сценарий не из этого списка — скорее всего, его уже реализовал кто-то из агентств на платформе. Спросите у поддержки x10seo шаблон: команда часто шарит обезличенные конфиги.

Возможные проблемы и решения

Топ-5 граблей, на которые наступают при первой интеграции:

• 401 Unauthorized без видимой причины — проверьте, что не поставили заголовок Authorization: Token ... вместо Bearer.
• 429 Too Many Requests — кешируйте /projects на 60 секунд, не дёргайте при каждом рендере дашборда.
• Webhook не приходит — посмотрите логи в разделе «Интеграции» → «История доставок», там видны коды ответов и причины ретраев.
• Подпись HMAC не сходится — убедитесь, что считаете её от сырого body, а не от распарсенного и пересобранного JSON (порядок ключей меняется).
• Кампания создалась, но не запускается — проверьте баланс клиента и параметр schedule: окно может уже быть в прошлом по МСК.

При повторении любой ошибки трижды пишите в саппорт x10seo с request-id из заголовка X-Request-Id. По этому id команда поднимает полный лог запроса за секунды и подскажет фикс.

Часто задаваемые вопросы

Какой лимит запросов у API x10seo?

100 запросов в минуту на один токен. Если нужен больший лимит — заведите несколько ключей под разные процессы (дашборд, cron, webhook-handler). Для нагруженных кейсов напишите в саппорт: индивидуальный лимит обсуждается, в том числе для агентств с большими портфелями.

Можно ли управлять балансом клиента через API?

Да, поддерживается чтение баланса через GET /api/v1/balance и запрос на пополнение через интеграцию с платёжным провайдером. Прямое списание средств без подтверждения клиента невозможно — это требование закона о персональных данных и платёжных систем.

Поддерживается ли OAuth для интеграций?

На текущий момент API использует Bearer-токены. OAuth 2.0 находится в roadmap на третий квартал 2026 года. Если для вашего кейса критичен OAuth — напишите в саппорт: такие запросы влияют на приоритет в роадмапе и могут ускорить выпуск.

Какие языки и SDK поддерживаются?

API — REST/JSON, поэтому работает с любым языком, поддерживающим HTTP. Официальные обёртки команда выкладывает на GitHub-аккаунт x10seo для Python и Node.js. Сообщество поддерживает обёртки для PHP и Go — ссылки в документации API.

Что делать, если webhook не приходит?

Проверьте раздел «История доставок» в кабинете — там видны попытки и коды ответов. Если ваш эндпоинт вернул не-200 трижды, доставка останавливается на 1 час. После исправления нажмите «Повторить» вручную или дождитесь автоматического возобновления.

Влияет ли работа через API на безопасность аккаунта в Яндексе?

Нет. API меняет только способ управления кампаниями x10seo, но не саму технологию работы. Алгоритмы безопасной эмуляции поведенческих факторов остаются прежними — те же fingerprint-профили и режимы. С 2023 года у клиентов x10seo 0 банов, и API на это не влияет.