Первый запрос к API

Пройдём полный сценарий на cURL: найдём проект, выберем шаблон, создадим отчёт за август 2026 года и скачаем Word. Идентификаторы в примерах демонстрационные — замените их полученными из своего аккаунта.

Подготовьте ключ и инструменты

Создайте ключ по инструкции во введении с правами projects:read, reports:create и reports:read. Подготовьте проект и источники в кабинете. Для выполнения примеров нужен cURL. Замените {apiKey} в заголовке Authorization своим ключом.

1. Найдите проект

GET/api/projectsprojects:read

curl

curl --fail-with-body -sS "https://seo-reports.ru/api/projects?search=example.ru" \
  -H "Authorization: Bearer {apiKey}"

json

{
  "items": [
    {
      "project_id": "35328",
      "name": "example.ru",
      "url": "https://example.ru",
      "source": "yandex_metrika",
      "default_template_id": "412"
    }
  ],
  "page": 1,
  "page_size": 20,
  "total": 1
}

Выберите проект по названию и адресу, сохраните его project_id. При пустом items попробуйте запрос без поиска или проверьте аккаунт методом https://seo-reports.ru/api/me. В следующих запросах замените демонстрационный ID 35328 полученным project_id.

2. Выберите шаблон

GET/api/projects/{id}/report-optionsprojects:read

curl

curl --fail-with-body -sS "https://seo-reports.ru/api/projects/35328/report-options" \
  -H "Authorization: Bearer {apiKey}"

json

{
  "project_id": "35328",
  "templates": [
    {
      "template_id": "412",
      "name": "SEO-отчёт"
    }
  ],
  "default_template_id": "412",
  "previous_report": null,
  "settings_source": "defaults"
}

Выберите template_id из массива templates. При наличии default_template_id его можно использовать или выбрать другой доступный шаблон. Настройки источников, целей и кампаний наследуются автоматически. Их источник указан в settings_source.

3. Создайте отчёт

POST/api/reports/generatereports:create

Замените идентификаторы в теле запроса своими. Чтобы сравнить месяцы, явно передайте comparison. Без этого поля сравнение не включается.

curl

curl --fail-with-body -sS -X POST "https://seo-reports.ru/api/reports/generate" \
  -H "Authorization: Bearer {apiKey}" \
  -H "Content-Type: application/json" \
  --data '{
  "project_id": "35328",
  "template_id": "412",
  "period": {
    "from": "2026-08-01",
    "to": "2026-08-31"
  },
  "comparison": {
    "from": "2026-07-01",
    "to": "2026-07-31"
  },
  "refresh": false,
  "make_public": false
}'

json

{
  "report_id": "35328.a3f1c9e84b2d7061fe5c8a94d20b3e77",
  "status": "generating",
  "preview_url": "https://seo-reports.ru/p/35328/a3f1c9e84b2d7061fe5c8a94d20b3e77",
  "preview_public": false,
  "warnings": [],
  "poll_after_ms": 2000
}

HTTP 202 означает, что отчёт собирается. Если отчёт с такими параметрами уже готов, может сразу прийти HTTP 200 и status: ready. Сохраните полученный report_id как есть и подставьте его в URL следующих запросов.

4. Дождитесь готовности

GET/api/reports/{id}reports:read

curl

curl --fail-with-body -sS "https://seo-reports.ru/api/reports/35328.a3f1c9e84b2d7061fe5c8a94d20b3e77" \
  -H "Authorization: Bearer {apiKey}"

Пока status равен generating, повторяйте GET через паузу из poll_after_ms — обычно 2000 мс. Не запускайте генерацию заново для проверки статуса. Сам GET может вернуть HTTP 200 даже во время сборки: проверяйте поле status.

Статус	Действие
`generating`	Подождите и повторите чтение.
`ready`	Проверьте `warnings`, откройте `preview_url` или скачайте файл.
`failed`	Прочитайте `error_code` и устраните причину ошибки перед повторной генерацией.

Обратите внимание. Не выдавайте ссылку как готовый результат до status: ready. Непустой warnings означает, что отчёт требует внимания, например из-за потерянного доступа к источнику.

5. Скачайте Word или PDF

GET/api/reports/{id}/export/wordreports:read

curl

curl --fail-with-body -sS "https://seo-reports.ru/api/reports/35328.a3f1c9e84b2d7061fe5c8a94d20b3e77/export/word" \
  -H "Authorization: Bearer {apiKey}" \
  --output report.docx

Для PDF замените word на pdf и имя файла на report.pdf. Экспорт возвращает файл и тоже требует ключ. Его сборка может занять десятки секунд.

Обратите внимание. При ошибке cURL с --fail-with-body завершается с ненулевым кодом, но JSON-ошибка может попасть в файл --output. Проверяйте код завершения и не отправляйте такой файл клиенту.

Ссылка preview_url предназначена для просмотра. При preview_public: false отчёт доступен только после входа владельца в кабинет. Не добавляйте ключ к ссылке. Для гостей предусмотрен явный make_public: true при генерации.

Превью готового отчёта по ссылке preview_url: содержание отчёта, кнопки скачивания в Word и PDF, заголовок и отчётный период.

Что автоматизировать дальше

Параметры запросов — в справочнике методов. Для уведомлений о сборке и правках отчёта настройте вебхук. При ошибках откройте диагностику и статистику обращений.

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

← ПредыдущаяВведение в API Следующая →Справочник методов API

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