API Referencev1

Документация API

HTTP API для загрузки HTML-отчётов из n8n-воркфлоу. Все endpoints идемпотентны — повторный вызов перезаписывает данные без дублирования.

Источники данных (n8n воркфлоу)

team-capacity-metrics

→ /api/ingest/sprintСводка спринта (sprint_summary)

infra-metrics

→ /api/ingest/infraИнфраструктурные метрики (infra_metrics)

Team Sprint by Code

→ /api/ingest/codeЗадачи и качество кода команды (code_quality)

→ /api/ingest/employeeОтчёт по каждому сотруднику (code_and_tasks)

sprint-comparison (новый воркфлоу)

→ /api/ingest/comparisonСравнительный анализ по спринтам

Порядок вызовов из n8n

POST /api/ingest/sprint— создаёт спринт; вызвать первым

POST /api/ingest/infra— инфраструктурные метрики (опционально)

POST /api/ingest/code— командный отчёт по задачам и коду (опционально)

POST /api/ingest/employee— для каждого сотрудника

POST /api/ingest/comparison— сравнительный анализ нескольких спринтов (независимо)

Спринт должен существовать до отправки отчётов infra, code и employee (кроме /api/ingest/code — он сам создаст спринт при необходимости).

POST/api/ingest/sprint

Создаёт спринт и сохраняет сводный HTML-отчёт команды (Сводка спринта). Источник — воркфлоу team-capacity-metrics. При повторном вызове обновляет название спринта и перезаписывает HTML.

Параметры

Поле	Тип	Описание
sprint_number*	number	Уникальный номер спринта
sprint_name*	string	Название, отображаемое в сайдбаре
html*	string	Полный HTML-документ (<!DOCTYPE html> со встроенными стилями)

Пример

{
  "sprint_number": 83,
  "sprint_name": "Sprint 83 — 30.03–12.04",
  "html": "<!DOCTYPE html><html>...</html>"
}

Ответ 200

{ "ok": true, "sprintId": "cmo42v8wk0000...", "reportId": "cmo42v8yd0001..." }

POST/api/ingest/infra

Сохраняет HTML-отчёт по инфраструктурным метрикам (Prometheus, K8s). Источник — воркфлоу infra-metrics. Отображается на вкладке Инфраструктура. Спринт должен быть создан заранее через /api/ingest/sprint.

Параметры

Поле	Тип	Описание
sprint_number*	number	Номер существующего спринта
html*	string	Полный HTML-документ с метриками инфраструктуры

Пример

{
  "sprint_number": 83,
  "html": "<!DOCTYPE html><html>...</html>"
}

Ответ 200

{ "ok": true, "sprintId": "cmo42v8wk0000...", "reportId": "cmo42v8yd0001..." }

POST/api/ingest/code

Сохраняет командный HTML-отчёт по задачам и качеству кода. Источник — воркфлоу Team Sprint by Code (нода Send Team Report). Отображается на вкладке Задачи и качество кода. Если спринт не существует — создаётся автоматически.

Параметры

Поле	Тип	Описание
sprint_number*	number	Номер спринта (создаётся если не существует)
sprint_name	string	Название спринта (используется при создании)
html*	string	Полный HTML-отчёт по командному анализу задач и кода

Пример

{
  "sprint_number": 83,
  "sprint_name": "Sprint 83 — 30.03–12.04",
  "html": "<!DOCTYPE html><html>...</html>"
}

Ответ 200

{ "ok": true, "sprintId": "cmo42v8wk0000...", "reportId": "cmo42v8yd0001..." }

POST/api/ingest/employee

Сохраняет HTML-отчёт по сотруднику в рамках спринта. Источник — воркфлоу Team Sprint by Code (нода Send Employee Report). Сотрудник создаётся автоматически по имени при первом вызове. Спринт должен существовать.

Параметры

Поле	Тип	Описание
sprint_number*	number	Номер существующего спринта
employee_name*	string	Полное имя сотрудника — используется как стабильный идентификатор
type*	enum	Тип отчёта: `metrics` `commits` `code_analysis` `code_and_tasks`
html*	string	Полный HTML-документ

Примеры

Метрики производительности (team-capacity-metrics)

{
  "sprint_number": 83,
  "employee_name": "Иван Петров",
  "type": "metrics",
  "html": "<!DOCTYPE html><html>...</html>"
}

Задачи и качество кода (Team Sprint by Code)

{
  "sprint_number": 83,
  "employee_name": "Иван Петров",
  "type": "code_and_tasks",
  "html": "<!DOCTYPE html><html>...</html>"
}

Ответ 200

{ "ok": true, "reportId": "cmo42vh2v0003..." }

POST/api/ingest/comparison

Сохраняет HTML-отчёт сравнительного анализа нескольких спринтов. Отображается в разделе Сравнительный анализ в сайдбаре. Идентифицируется по title — повторная отправка с тем же title перезаписывает HTML. Не привязан к конкретному спринту.

Параметры

Поле	Тип	Описание
title*	string	Уникальный заголовок отчёта, напр. "Сравнение Sprint 81–83"
html*	string	Полный HTML-документ сравнительного анализа

Пример

{
  "title": "Сравнение Sprint 81–83",
  "html": "<!DOCTYPE html><html>...</html>"
}

Ответ 200

{ "ok": true, "comparisonId": "cmo42v8wk0000..." }

Коды ошибок

Код	Причина
400	Отсутствует обязательное поле или неверный `type`
404	Спринт с таким `sprint_number` не найден (только для `/infra` и `/employee`)
500	Внутренняя ошибка сервера — проверь логи Next.js

Справочник типов отчётов

type	Endpoint	Вкладка / место	Источник
sprint_summary	/api/ingest/sprint	Спринт → Сводка спринта	team-capacity-metrics
infra_metrics	/api/ingest/infra	Спринт → Инфраструктура	infra-metrics
code_quality	/api/ingest/code	Спринт → Задачи и качество кода	Team Sprint by Code
metrics	/api/ingest/employee	Сотрудник → вкладка Метрики	team-capacity-metrics
code_and_tasks	/api/ingest/employee	Сотрудник → вкладка Код и задачи	Team Sprint by Code
commits	/api/ingest/employee	Сотрудник → вкладка Коммиты	(резерв)
code_analysis	/api/ingest/employee	Сотрудник → вкладка Код	(резерв)
—	/api/ingest/comparison	Раздел Сравнительный анализ (sidebar)	sprint-comparison

Пример HTTP-ноды в n8n

В каждой ноде HTTP Request используй следующие настройки:

Method	POST
URL	https://<ngrok-or-host>/api/ingest/<endpoint>
Body Content Type	JSON
Body	Поля согласно документации выше
Error handling	continueOnFail: false (чтобы видеть ошибки)