Введение в API

API позволяет вашим решениям находить проекты, создавать и читать отчёты, менять их структуру и скачивать Word или PDF. Для начала создайте персональный ключ в кабинете и передавайте его в каждом запросе.

Базовый адрес и возможности

text

https://seo-reports.ru/api

Все методы начинаются с /api, например https://seo-reports.ru/api/projects. Все запросы собраны в справочнике методов.

Возможности:

Поиск проектов и доступных шаблонов.
Просмотр истории отчётов проекта.
Генерация отчёта за период, сравнение периодов.
Чтение карточки отчёта и данных блоков.
Сохранение комментариев, изменение порядка и настроек блоков.
Выгрузка Word и PDF. Открытие превью гостям по явному запросу.

Важно. Проекты, источники и шаблоны создаются и настраиваются в кабинете. Методов создания или удаления проектов, подключения источников и управления шаблонами пока нет.

Обратите внимание. Для работы с данными нужен действующий тариф или демо-доступ и соблюдение лимита проектов.

Создайте ключ доступа

Откройте «API & MCP» → API и нажмите «Создать ключ» или «Создать» над таблицей.
Укажите название, например «CRM» или «Ежемесячная выгрузка».
Выберите срок: 30 дней, 90 дней, год или бессрочно.
Оставьте только необходимые права и нажмите «Создать».
Сразу скопируйте ключ и сохраните его в защищённом хранилище: полное значение второй раз не показывается.

Создание ключа на вкладке API: название, срок действия и права, затем однократный показ ключа и таблица ключей.

Право	Что разрешает
`projects:read`	Просмотр проектов и шаблонов генерации
`reports:read`	Просмотр отчётов, данных блоков и выгрузка файлов
`reports:create`	Создание и пересчёт отчётов
`reports:write`	Изменение структуры и комментариев

Совет. Для сценария «найти проект → создать отчёт → скачать файл» нужны projects:read, reports:create и reports:read. Для чтения по известному report_id достаточно reports:read. Право reports:write добавляйте только для редактирования.

Права независимы: создание отчётов не даёт автоматически права их читать. Ключ определяет владельца аккаунта. Другой user_id в запросе не меняет доступ.

Авторизация в каждом запросе

text

Authorization: Bearer <ваш ключ>

Передавайте ключ в HTTP-заголовке, не в URL или теле запроса. Вход в кабинет и cookie браузера не заменяют этот заголовок.

bash

curl --fail-with-body -sS "https://seo-reports.ru/api/me" \
  -H "Authorization: Bearer <ваш ключ>"

Этот запрос проверяет владельца, права и срок ключа, но не раскрывает его секрет. Отдельное право и действующий тариф для него не требуются. Поля ответа — в справочнике.

Формат запросов и ответов

GET принимает параметры в URL. POST и PUT принимают JSON с заголовком Content-Type: application/json. Идентификаторы передавайте строками, флаги — логическими true и false, даты — в формате YYYY-MM-DD.

json

{
  "project_id": "35328",
  "template_id": "412",
  "period": {
    "from": "2026-08-01",
    "to": "2026-08-31"
  },
  "refresh": false,
  "make_public": false
}

Обычно ответ содержит JSON. Исключение — экспорт: успешный ответ возвращает файл Word или PDF, а ошибка — JSON. Идентификатор отчёта сохраняйте как непрозрачную строку: не разбирайте и не составляйте его самостоятельно.

HTTP-статус	Значение
200	Запрос выполнен. При чтении отчёта дополнительно проверяйте `status`.
202	Генерация принята, отчёт ещё собирается.
401 / 403	Ключ не принят, не хватает прав или доступ ограничен состоянием аккаунта.
404 / 409 / 422	Объект не найден, конфликт состояния или ошибка параметров.
429	Превышен лимит, выдержите `Retry-After`.
500 / 503	Ошибка сервиса, очереди или экспорта.

Ошибка имеет объект error с полями code, message и иногда details и request_id. Ориентируйтесь на машинный код, а не текст сообщения. Подробности — ошибки и лимиты.

Хранение, замена и отзыв ключа

Храните ключ на сервере или в хранилище секретов, не в публичном JavaScript страницы.
Не публикуйте ключ в репозитории, скриншотах, логах и чатах.
Потерянный ключ восстановить нельзя — создайте новый.
При плановой замене сначала создайте новый ключ, обновите интеграцию и проверьте её, затем отзовите старый.
Если ключ раскрыт посторонним, отзовите его сразу.

Для отзыва откройте вкладку API, найдите ключ и нажмите «Отозвать». Последующие прямые запросы с ним вернут 401 unauthorized. Срок персонального ключа не продлевается использованием.

Важно. Ключ даёт доступ в пределах выданных прав. Не публикуйте команды с настоящим ключом и не записывайте Authorization в отладочные логи.

Куда дальше

Выполните первый запрос, откройте справочник методов или скачайте OpenAPI. Для уведомлений о сборке и правках отчёта настройте вебхук.

Помогла статья?

Следующая →Первый запрос к API

← В категорию «API & MCP»В справочный центр