Отчёты

Отчёты

GET /api/projects/{project}/reports — Список отчётов
POST /api/projects/{project}/reports — Создать отчёт
GET /api/projects/{project}/reports/{report} — Детальный отчёт
GET /api/projects/{project}/reports/{report}/status — Статус готовности
GET /api/projects/{project}/reports/{report}/download — Скачать PDF
GET /api/projects/{project}/reports/blocks — Доступные блоки
Настройки генерации (options)
Блоки отчёта
Полный сценарий: создать → дождаться → скачать PDF
Возможные статусы
Ошибки

API для создания, получения, мониторинга и скачивания отчётов проекта. Все эндпоинты требуют авторизации через API токен (Authorization: Bearer YOUR_API_TOKEN).

GET /api/projects/{project}/reports

Описание: Получить список отчётов проекта (с пагинацией).

Параметры запроса (query)

Параметр	Тип	По умолчанию	Описание
`per_page`	integer	20	Количество записей на странице (макс. 100)
`status`	string	—	Фильтр по статусу: `queued`, `running`, `done`, `failed`

Пример запроса

curl -X GET "https://ai.pixeltools.ru/api/projects/1/reports?per_page=5&status=done" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Ответ (200)

{
  "data": [
    {
      "id": 15,
      "project_id": 1,
      "user_id": 1,
      "status": "done",
      "source_type": "manual",
      "shared_key": "a1b2c3d4e5f6...",
      "created_at": "2026-01-15T12:00:00.000000Z",
      "updated_at": "2026-01-15T12:10:00.000000Z"
    }
  ],
  "links": { "first": "...", "last": "...", "prev": null, "next": null },
  "meta": { "current_page": 1, "last_page": 1, "per_page": 5, "total": 1 }
}

POST /api/projects/{project}/reports

Описание: Создать новый отчёт. Отчёт ставится в очередь и генерируется асинхронно.

Тело запроса (JSON)

Поле	Тип	Обяз.	Описание
`options`	object	да	Настройки генерации (см. ниже)
`status`	string	нет	По умолчанию `queued`
`source_type`	string	нет	По умолчанию `manual`. Варианты: `manual`, `automatic`, `restart`

Быстрый пример: отчёт за 7 дней со всеми блоками

curl -X POST "https://ai.pixeltools.ru/api/projects/1/reports" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "options": {
      "comparison_enabled": false,
      "period_main": "last_7_days",
      "blocks": [
        { "slug": "summary", "checked": true },
        { "slug": "competitors", "checked": true },
        { "slug": "answers", "checked": true },
        { "slug": "traffic", "checked": true },
        { "slug": "sources", "checked": true }
      ]
    }
  }'

Пример: отчёт за 30 дней со сравнением с предыдущим периодом

curl -X POST "https://ai.pixeltools.ru/api/projects/1/reports" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "options": {
      "comparison_enabled": true,
      "period_main": "last_30_days",
      "period_comparison": "prev_period",
      "blocks": [
        { "slug": "summary", "checked": true },
        { "slug": "competitors", "checked": true },
        { "slug": "answers", "checked": true },
        { "slug": "traffic", "checked": true },
        { "slug": "sources", "checked": true }
      ]
    }
  }'

Пример: произвольные даты + сравнение с произвольным периодом

curl -X POST "https://ai.pixeltools.ru/api/projects/1/reports" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "options": {
      "comparison_enabled": true,
      "period_main": "custom",
      "period_main_dates": ["2026-02-01", "2026-02-28"],
      "period_comparison": "custom",
      "period_compare_dates": ["2026-01-01", "2026-01-31"],
      "blocks": [
        { "slug": "summary", "checked": true },
        { "slug": "competitors", "checked": true },
        { "slug": "answers", "checked": true },
        { "slug": "traffic", "checked": true },
        { "slug": "sources", "checked": true }
      ]
    }
  }'

Пример: только блок «Трафик», без сравнения

curl -X POST "https://ai.pixeltools.ru/api/projects/1/reports" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "options": {
      "comparison_enabled": false,
      "period_main": "last_30_days",
      "blocks": [
        { "slug": "traffic", "checked": true }
      ]
    }
  }'

Ответ (201 Created)

{
  "id": 15,
  "shared_key": "a1b2c3d4e5f6...",
  "status": "queued",
  "message": "Report queued successfully"
}

Сохраните id — он нужен для проверки статуса и скачивания PDF.

GET /api/projects/{project}/reports/{report}

Описание: Получить детальную информацию об отчёте, включая данные результата (когда отчёт готов).

Пример запроса

curl -X GET "https://ai.pixeltools.ru/api/projects/1/reports/15" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Ответ (200)

Поле	Тип	Описание
`id`	integer	ID отчёта
`project_id`	integer	ID проекта
`user_id`	integer\|null	ID пользователя, создавшего отчёт
`status`	string	`queued` / `running` / `done` / `failed`
`source_type`	string	`manual` / `automatic` / `restart`
`shared_key`	string	Ключ для публичного доступа к отчёту
`options`	object	Настройки генерации: периоды, блоки, email-уведомления, тип файла
`created_at`	datetime	Дата создания
`updated_at`	datetime	Дата последнего обновления
`result`	array\|null	Данные отчёта. Присутствует только при `status = "done"`. Массив объектов по блокам.

Пример ответа (status = done)

{
  "data": {
    "id": 15,
    "project_id": 1,
    "user_id": 1,
    "status": "done",
    "source_type": "manual",
    "shared_key": "a1b2c3d4e5f6...",
    "options": {
      "comparison_enabled": true,
      "period_main": "last_7_days",
      "period_comparison": "prev_period",
      "period_main_dates": null,
      "period_compare_dates": null,
      "blocks": [
        { "id": 1, "slug": "summary", "title": "Сводка", "checked": true, "visible": "all", "block_order": 50 },
        { "id": 2, "slug": "competitors", "title": "Конкуренты", "checked": true, "visible": "all", "block_order": 100 },
        { "id": 3, "slug": "answers", "title": "Позиции и упоминания", "checked": true, "visible": "all", "block_order": 200 },
        { "id": 4, "slug": "traffic", "title": "Трафик", "checked": true, "visible": "all", "block_order": 300 },
        { "id": 5, "slug": "sources", "title": "Источники", "checked": true, "visible": "all", "block_order": 400 }
      ],
      "report_email": [],
      "report_email_notifications": [],
      "file_type": "none"
    },
    "created_at": "2026-01-15T12:00:00.000000Z",
    "updated_at": "2026-01-15T12:10:00.000000Z",
    "result": [
      {
        "id": 1,
        "project_report_id": 15,
        "block_slug": "summary",
        "block_data": { "...данные блока..." },
        "created_at": "2026-01-15T12:05:00.000000Z",
        "updated_at": "2026-01-15T12:05:00.000000Z"
      },
      {
        "id": 2,
        "project_report_id": 15,
        "block_slug": "traffic",
        "block_data": { "...данные блока..." },
        "created_at": "2026-01-15T12:06:00.000000Z",
        "updated_at": "2026-01-15T12:06:00.000000Z"
      }
    ]
  }
}

Пример ответа (status ≠ done)

{
  "data": {
    "id": 15,
    "project_id": 1,
    "user_id": 1,
    "status": "running",
    "source_type": "manual",
    "shared_key": "a1b2c3d4e5f6...",
    "options": { "..." },
    "created_at": "2026-01-15T12:00:00.000000Z",
    "updated_at": "2026-01-15T12:01:00.000000Z"
  }
}

Поле result отсутствует, пока статус не станет done.

GET /api/projects/{project}/reports/{report}/status

Описание: Проверить статус готовности отчёта. Лёгкий эндпоинт для поллинга — возвращает только статус без данных отчёта.

Пример запроса

curl -X GET "https://ai.pixeltools.ru/api/projects/1/reports/15/status" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Ответ (200)

{
  "id": 15,
  "status": "running",
  "updated_at": "2026-01-15T12:05:00.000000Z"
}

Опрашивайте этот эндпоинт с интервалом 10–30 секунд, пока status не станет "done" или "failed".

Возможные значения `status`

Статус	Описание	Что делать
`queued`	Отчёт в очереди, ещё не начал генерироваться	Ждать, продолжить поллинг
`running`	Отчёт генерируется	Ждать, продолжить поллинг
`done`	Отчёт готов	Можно запросить данные (GET /{report}) или скачать PDF (GET /{report}/download)
`failed`	Ошибка при генерации	Попробуйте создать отчёт заново

GET /api/projects/{project}/reports/{report}/download

Описание: Скачать отчёт в формате PDF. Если PDF ещё не сгенерирован, запускается генерация в фоне.

Пример запроса

curl -X GET "https://ai.pixeltools.ru/api/projects/1/reports/15/download" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Ответ: PDF готов (200)

{
  "id": 15,
  "status": "success",
  "file": "https://ai.pixeltools.ru/storage/pdf/reports/otchet_o_prodvizhenii_brenda_..._15.pdf",
  "message": "PDF is ready"
}

Поле file содержит прямую ссылку для скачивания PDF-файла.

Ответ: PDF генерируется (200)

{
  "id": 15,
  "status": "in_progress",
  "file": null,
  "message": "PDF generation started"
}

Генерация PDF запущена. Повторите запрос через 15–30 секунд.

Ответ: отчёт ещё не готов (400)

{
  "message": "Report is not ready yet",
  "status": "running"
}

Отчёт ещё генерируется. Дождитесь статуса done через эндпоинт /status, затем повторите запрос на скачивание.

GET /api/projects/{project}/reports/blocks

Описание: Получить список доступных блоков для отчёта. Используйте этот эндпоинт, чтобы узнать актуальные slug блоков перед созданием отчёта.

Пример запроса

curl -X GET "https://ai.pixeltools.ru/api/projects/1/reports/blocks" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Ответ (200)

{
  "data": [
    { "id": 1, "slug": "summary", "name": "Сводка", "description": "Оценка видимости бренда и анализ тональности ИИ", "block_order": 50, "visible": "all" },
    { "id": 2, "slug": "competitors", "name": "Конкуренты", "description": "Видимость конкурентов в ИИ-системах", "block_order": 100, "visible": "all" },
    { "id": 3, "slug": "answers", "name": "Позиции и упоминания", "description": "Позиции и упоминания бренда в ответах ИИ", "block_order": 200, "visible": "all" },
    { "id": 4, "slug": "traffic", "name": "Трафик", "description": "Трафик из ИИ-систем (ChatGPT, Perplexity, Claude, Gemini и др.)", "block_order": 300, "visible": "all" },
    { "id": 5, "slug": "sources", "name": "Источники", "description": "Страницы, используемые как источники ИИ-системами", "block_order": 400, "visible": "all" }
  ]
}

Настройки генерации (options)

Объект options передаётся в теле POST-запроса при создании отчёта.

Поле	Тип	Обяз.	Описание
`comparison_enabled`	boolean	да	Включить сравнение с другим периодом. Если `false`, поля `period_comparison` и `period_compare_dates` игнорируются.
`period_main`	string	да	Основной период отчёта. Допустимые значения: `last_7_days` — последние 7 дней `last_30_days` — последние 30 дней `last_calendar_month` — предыдущий календарный месяц `custom` — произвольный диапазон (требуется `period_main_dates`)
`period_main_dates`	[string, string]	при custom	Массив из двух дат `["YYYY-MM-DD", "YYYY-MM-DD"]`. Первая дата ≤ второй. Обязателен, когда `period_main = "custom"`.
`period_comparison`	string	при сравнении	Период сравнения. Обязателен, когда `comparison_enabled = true`. Допустимые значения: `last_7_days`, `last_30_days`, `last_calendar_month`, `custom` — аналогично `period_main` `prev_period` — предыдущий период той же длительности (например, если основной 7 дней, сравнение — предшествующие 7 дней)
`period_compare_dates`	[string, string]	нет	Массив из двух дат для произвольного периода сравнения. Обязателен, когда `period_comparison = "custom"`.
`blocks`	array	да	Массив блоков отчёта. Каждый элемент — объект с полем `slug`. См. Блоки отчёта.
`report_email`	string\|array	нет	Email-адрес(а) для уведомления об успешной генерации. Строка через запятую или массив.
`report_email_notifications`	string\|array	нет	Email-адрес(а) для уведомления об ошибке генерации.
`file_type`	string	нет	`none` (по умолчанию) или `pdf`. Если `pdf` — PDF автоматически генерируется после завершения отчёта.

Блоки отчёта

Передавайте нужные блоки в options.blocks. Минимально — объект с полем slug. По умолчанию checked = true.

slug	Название	Описание
`summary`	Сводка	Оценка видимости бренда и анализ тональности ИИ
`competitors`	Конкуренты	Видимость конкурентов в ИИ-системах
`answers`	Позиции и упоминания	Позиции и упоминания бренда в ответах ИИ
`traffic`	Трафик	Трафик из ИИ-систем (ChatGPT, Perplexity, Claude, Gemini и др.)
`sources`	Источники	Страницы, используемые как источники ИИ-системами

Чтобы включить все блоки, передайте все пять:

"blocks": [
  { "slug": "summary" },
  { "slug": "competitors" },
  { "slug": "answers" },
  { "slug": "traffic" },
  { "slug": "sources" }
]

Чтобы выбрать только нужные, передайте их подмножество:

"blocks": [
  { "slug": "traffic" },
  { "slug": "sources" }
]

Актуальный список блоков можно получить через GET /api/projects/{project}/reports/blocks.

Полный сценарий: создать → дождаться → скачать PDF

Пошаговый пример получения отчёта за 7 дней со всеми блоками в формате PDF.

Шаг 1. Создать отчёт

curl -X POST "https://ai.pixeltools.ru/api/projects/1/reports" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "options": {
      "comparison_enabled": false,
      "period_main": "last_7_days",
      "blocks": [
        { "slug": "summary" },
        { "slug": "competitors" },
        { "slug": "answers" },
        { "slug": "traffic" },
        { "slug": "sources" }
      ]
    }
  }'

# Ответ: { "id": 15, "status": "queued", ... }
# Запомните id = 15

Шаг 2. Дождаться готовности (поллинг)

# Повторяйте каждые 15–30 секунд, пока status не станет "done"
curl -X GET "https://ai.pixeltools.ru/api/projects/1/reports/15/status" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

# Ответ (ещё генерируется): { "id": 15, "status": "running", "updated_at": "..." }
# Ответ (готов):             { "id": 15, "status": "done", "updated_at": "..." }

Шаг 3. Скачать PDF

curl -X GET "https://ai.pixeltools.ru/api/projects/1/reports/15/download" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

# Если PDF готов:
# { "id": 15, "status": "success", "file": "https://ai.pixeltools.ru/storage/pdf/reports/....pdf", "message": "PDF is ready" }

# Если PDF ещё генерируется (первый запрос запускает генерацию):
# { "id": 15, "status": "in_progress", "file": null, "message": "PDF generation started" }
# → Повторите запрос через 15–30 секунд

Шаг 4. Скачать файл по ссылке

# Используйте URL из поля "file" для скачивания
curl -o report.pdf "https://ai.pixeltools.ru/storage/pdf/reports/....pdf"

Возможные статусы отчёта

Статус	Описание
`queued`	В очереди — отчёт создан, ожидает обработки
`running`	Генерируется — идёт сбор данных по блокам
`done`	Готов — данные доступны, можно скачать PDF
`failed`	Ошибка — что-то пошло не так при генерации

Ошибки

401 Unauthorized

{
  "message": "Invalid API token"
}

400 Report is not ready

Возвращается при попытке скачать PDF до завершения генерации отчёта.

{
  "message": "Report is not ready yet",
  "status": "running"
}

422 Validation Error

Ошибка валидации параметров при создании отчёта.

{
  "message": "The given data was invalid.",
  "errors": {
    "options.period_main": ["Поле период отчёта обязательно."],
    "options.blocks": ["Поле options.blocks обязательно."]
  }
}

404 Not Found

Проект не найден или отчёт не принадлежит указанному проекту.

Другие разделы

Авторизация

Проекты

Рейтинги

Рейтинг статьи

0 (0 оценок)

Задайте вопрос или оставьте комментарий

GET /api/projects/{project}/reports

Параметры запроса (query)

Пример запроса

Ответ (200)

POST /api/projects/{project}/reports

Тело запроса (JSON)

Быстрый пример: отчёт за 7 дней со всеми блоками

Пример: отчёт за 30 дней со сравнением с предыдущим периодом

Пример: произвольные даты + сравнение с произвольным периодом

Пример: только блок «Трафик», без сравнения

Ответ (201 Created)

GET /api/projects/{project}/reports/{report}

Пример запроса

Ответ (200)

Пример ответа (status = done)

Пример ответа (status ≠ done)

GET /api/projects/{project}/reports/{report}/status

Пример запроса

Ответ (200)

Возможные значения status

GET /api/projects/{project}/reports/{report}/download

Пример запроса

Ответ: PDF готов (200)

Ответ: PDF генерируется (200)

Ответ: отчёт ещё не готов (400)

GET /api/projects/{project}/reports/blocks

Пример запроса

Ответ (200)

Настройки генерации (options)

Блоки отчёта

Полный сценарий: создать → дождаться → скачать PDF

Шаг 1. Создать отчёт

Шаг 2. Дождаться готовности (поллинг)

Шаг 3. Скачать PDF

Шаг 4. Скачать файл по ссылке

Возможные статусы отчёта

Ошибки

401 Unauthorized

400 Report is not ready

422 Validation Error

404 Not Found

Другие разделы

Возможные значения `status`