#Отчёты стратега

Статус: Доступно (чтение). Работают GET /strategist/reports и GET /strategist/reports/{id} (область strategist:read). Отчёты строятся на агрегатах; названия конкурентов скрыты, снимок аналитики, модель и стоимость прогона не отдаются.

Стратег — ИИ-маркетолог Sapport. Он собирает данные вашего сайта и рекламы (трафик, поисковые запросы, статьи, конкуренты, CRM-воронка в счётчиках) и раз в сутки и раз в неделю готовит отчёт: что произошло, что тревожит и что стоит сделать. API отчётов отдаёт этот отчёт вашей системе в виде структуры, а не готового текста для мессенджера.

Доступ: strategist:read. Платно: нет (чтение готового отчёта). ПДн: нет — отчёт строится на агрегатах и счётчиках, персональных данных учеников и лидов в нём нет.

Публичный API отдаёт отчёты стратега двух видов: суточные (daily) и недельные (weekly). Прогоны других модулей, которые лежат в той же таблице отчётов (например, креативы), через API не отдаются.

#Базовый адрес

Ошибки, пагинация, пределы — Соглашения. Ключи и области — Аутентификация. Во всех примерах ключ заведомо ненастоящий.

#Точки

Отчёт создаёт сам стратег по расписанию. Заказать отчёт запросом API нельзя. Список — курсорный (Пагинация).

#Структура отчёта

Отчёт отвечает на три вопроса: что главное, что тревожит и что делать.

#Шапка отчёта (элемент списка)

Список возвращает только шапки: тело отчёта в нём не отдаётся ни при каком наборе прав.

#Отчёт целиком

Ссылки на внутренние объекты (статья, запрос, продукт) в текстах highlights, concerns и rationale заменяются читаемыми подписями.

#Рекомендация (actions[])

Поля target_ref, expected_effect, check_after_days и basis есть в структуре новых отчётов. В отчётах, созданных до их появления, этих полей нет или они пусты (см. «Открытые вопросы»).

#Основание рекомендации (basis)

Рекомендация без единого кейса помечена как hypothesis: стратег называет догадку догадкой.

#Доказательства (evidence)

Для каждой рекомендации прикладывается до трёх доказательств.

Подписи, адреса и цитаты подставляет сервер из данных, которые он сам выдал стратегу; модель присылает только ссылку. Поэтому в доказательствах нет выдуманных адресов.

Проверка доказательств честно ограничена. Сервер проверяет, что ссылка выдана им самим и что цитата взята из источника. Он не проверяет, что кейс действительно подтверждает вывод. Поле evidence.validation.relevance_checked всегда false.

#Срез без сырья конкурентов

В v1 сырьё конкурентов (право competitors.raw) интеграции недоступно, поэтому отчёт всегда урезан: не возвращаются raw_signals (снимок аналитики), модель, стоимость прогона, а в доказательствах скрыты домены конкурентов и модельные детали. Структура блоков при этом сохраняется. Креативные отчёты не отдаются вовсе.

#GET /strategist/reports

{
  "data": [
    {
      "id": "3d8f1b52-6a47-4c9e-b0d3-9e51a2c7f804",
      "report_date": "2026-10-11",
      "report_type": "daily",
      "summary_text": "Трафик из поиска вырос, конверсия в заявку без изменений.",
      "actions_count": 3,
      "data_as_of": { "gsc": "2026-10-09", "tracker": "2026-10-11" },
      "delivered_at": "2026-10-11T06:10:04Z"
    }
  ],
  "next_cursor": null
}

curl "https://formula-cream.pro/api/public/v1/strategist/reports?limit=10" \
  -H "Authorization: Bearer $SAPPORT_API_KEY"
# SAPPORT_API_KEY=sap_ru_test_EXAMPLE0KEYID_… (пример, не настоящий ключ)

const res = await fetch(
  "https://formula-cream.pro/api/public/v1/strategist/reports?limit=10",
  { headers: { Authorization: `Bearer ${process.env.SAPPORT_API_KEY}` } },
);
const { data, next_cursor } = await res.json();

r = httpx.get(
    "https://formula-cream.pro/api/public/v1/strategist/reports",
    params={"limit": 10},
    headers={"Authorization": f"Bearer {os.environ['SAPPORT_API_KEY']}"},
)
page = r.json()

$ch = curl_init("https://formula-cream.pro/api/public/v1/strategist/reports?limit=10");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ["Authorization: Bearer " . getenv("SAPPORT_API_KEY")],
]);
$page = json_decode(curl_exec($ch), true);

#GET /strategist/reports/{id}

Чужой или несуществующий отчёт — 404 not_found.

{
  "id": "3d8f1b52-6a47-4c9e-b0d3-9e51a2c7f804",
  "report_date": "2026-10-11",
  "report_type": "daily",
  "summary_text": "Трафик из поиска вырос, конверсия в заявку без изменений.",
  "data_as_of": { "gsc": "2026-10-09", "tracker": "2026-10-11" },
  "highlights": [
    "Переходы из поиска выросли на странице про увлажняющие кремы"
  ],
  "concerns": [
    "Нет новых статей уже 12 дней"
  ],
  "actions": [
    {
      "title": "Выпустить статью про выбор увлажняющего крема",
      "priority": "high",
      "rationale": "Запрос растёт, статьи по теме на сайте нет.",
      "target_ref": "keyword:EXAMPLE",
      "expected_effect": { "metric": "переходы из поиска", "delta": "+10%", "horizon_days": 30 },
      "check_after_days": 21,
      "basis": "own_measured"
    }
  ],
  "evidence": {
    "actions": [
      {
        "index": 0,
        "status": "supported",
        "basis": "own_measured",
        "items": [
          { "ref": "own:EXAMPLE", "kind": "own", "label": "Поисковые запросы за 28 дней" }
        ]
      }
    ]
  }
}

curl "https://formula-cream.pro/api/public/v1/strategist/reports/$REPORT_ID" \
  -H "Authorization: Bearer $SAPPORT_API_KEY"

const res = await fetch(
  `https://formula-cream.pro/api/public/v1/strategist/reports/${reportId}`,
  { headers: { Authorization: `Bearer ${process.env.SAPPORT_API_KEY}` } },
);
const report = await res.json();
for (const action of report.actions) {
  console.log(action.priority, action.title);
}

r = httpx.get(
    f"https://formula-cream.pro/api/public/v1/strategist/reports/{report_id}",
    headers={"Authorization": f"Bearer {os.environ['SAPPORT_API_KEY']}"},
)
report = r.json()
for action in report["actions"]:
    print(action["priority"], action["title"])

$ch = curl_init("https://formula-cream.pro/api/public/v1/strategist/reports/" . $reportId);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ["Authorization: Bearer " . getenv("SAPPORT_API_KEY")],
]);
$report = json_decode(curl_exec($ch), true);

#Событие

Нагрузка тонкая: тип события и report_id. Сам отчёт забирайте запросом GET /strategist/reports/{id}. Подпись, повторы и проверка событий — Вебхуки.

#Ошибки

Общий формат и каталог кодов — Соглашения. Для этих точек:

#Открытые вопросы

• Старые отчёты (техническое). Отчёты, созданные до появления структурных полей рекомендации (target_ref, expected_effect, check_after_days, basis), хранят обоснование только текстом. Как отдавать их публично (пустые поля или перевод в новую структуру), не решено.
• Идентификатор рекомендации (техническое). В кабинетной структуре у рекомендации может быть собственный id, но не во всех отчётах. Нужен ли стабильный id в публичном API, не решено.
• Источник data_as_of (техническое). Поле добавляется в DTO отчёта; из каких источников оно собирается (поисковая консоль, счётчик, CRM-счётчики), уточнится при выпуске.
• Окно списка (техническое). Кабинетный список отдаёт шапки за последние days суток (1–365, по умолчанию 90), не более 400 строк и не постраничный; в публичном API он заменяется курсорным.