Аналитика проектов и источников B4

Аналитика проектов показывает показатели проектов за выбранный период. Проект B4 может содержать много источников с разной эффективностью: для их сравнения запустите отдельный расчёт и получите все подходящие источники одним ответом.

Подготовьте доступ и период

Примеры используют Bash и curl. Получите JWT в ALITOS_EXTERNAL_JWT и выберите кабинет по быстрому старту. Замените фиктивный 123456789 точным cabinetId в виде строки, даты — своим периодом.

Для аналитики проектов нужен cabinet:read, для B4 — cabinet:exports:run. Если проходите оба сценария, ключ и JWT должны разрешать оба scope. Пользователю также нужны текущие права на соответствующее действие в кабинете. Добавить scope существующему ключу нельзя — см. авторизацию.

Оба метода принимают от 1 до 5 cabinetIds и даты YYYY-MM-DD. Начало и конец включаются в период; его длина не должна превышать 370 дней.

Аналитика проектов: запрос и ответ

curl --request POST 'https://api.alitos.io/v1/external/analytics/projects/query' \
  --header "Authorization: Bearer ${ALITOS_EXTERNAL_JWT}" \
  --header 'Content-Type: application/json' \
  --data '{
    "cabinetIds": ["123456789"],
    "dateFrom": "2026-09-01",
    "dateTo": "2026-09-30",
    "projectScope": "active",
    "metricPreset": "cabinet_overview",
    "rowMode": "top",
    "maxResults": 50
  }'

Ответ приходит сразу с HTTP 200; создавать или опрашивать операцию не нужно. Этот пример выбирает активные проекты и набор показателей cabinet_overview.

Читайте строки из projects, общие показатели — из totals, если они присутствуют. Сравнивайте totalProjects, returnedProjects и truncated: пример намеренно запрашивает не более 50 строк проектов и не обещает полный список. Обращайте внимание на dataQualityWarnings.

Для работы со статусами прочитайте GET /v1/external/cabinets/{cabinetId}/analytics-config с cabinet:read. В объекте config состав групп указан в summaryGroups, пользовательские названия — в statusLabelOverrides, доступные ключи — в supportedStatusKeys. Не приписывайте историческим именам вроде status12 фиксированный бизнес-смысл и не считайте отсутствие разметки доказательством отсутствия результата.

Другие наборы показателей, фильтры, сортировка и режимы строк описаны в OpenAPI.

B4: запустите расчёт всех подходящих источников

Сформируйте и сохраните новый Idempotency-Key для этого расчёта. Для команды ниже нужен Node.js; если ключ формирует ваша интеграция, используйте его:

IDEMPOTENCY_KEY="$(node -p 'crypto.randomUUID()')"

При повторе запуска не генерируйте ключ заново: сохраняйте исходные ключ, тело и reason. Запуск расчёта:

curl --include --request POST 'https://api.alitos.io/v1/external/analytics/sources/jobs' \
  --header "Authorization: Bearer ${ALITOS_EXTERNAL_JWT}" \
  --header 'Content-Type: application/json' \
  --header "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
  --data '{
    "reason": "Анализ источников B4 за сентябрь",
    "cabinetIds": ["123456789"],
    "dateFrom": "2026-09-01",
    "dateTo": "2026-09-30",
    "projectScope": "active",
    "metricPreset": "b4_source_quality",
    "sourceRowsMode": "all"
  }'

Из ответа 202 Accepted сохраните operationId в OPERATION_ID. Заголовок Retry-After задаёт задержку перед следующим опросом.

sourceRowsMode: "all" возвращает все источники, подходящие под выбранные кабинеты, проекты, период и фильтры. Строки не обрезаются, даже если в запросе дополнительно указан положительный maxResults.

По умолчанию выбираются активные проекты, includeUnidentified=true включает неопознанные строки, а includeDeletedFromHistory=false не добавляет удалённые источники из истории. Для исследования истории выберите нужный projectScope (active, deleted или both) и явно задайте includeDeletedFromHistory=true. Полнота результата не отменяет выбранных условий отбора.

Дождитесь расчёта и получите результат

curl --include \
  "https://api.alitos.io/v1/external/operations/${OPERATION_ID}?view=compact" \
  --header "Authorization: Bearer ${ALITOS_EXTERNAL_JWT}"

При queued или running продолжайте опрос, соблюдая Retry-After и интервал не меньше двух секунд с небольшой случайной задержкой. При failed прочитайте error; правила повторов приведены в операциях и ошибках.

После succeeded получите все строки:

curl \
  "https://api.alitos.io/v1/external/operations/${OPERATION_ID}/result?view=all" \
  --header "Authorization: Bearer ${ALITOS_EXTERNAL_JWT}"

Массив rows содержит все сохранённые строки источников одним ответом, nextCursor равен null. Не передавайте cursor или pageSize: в view=all они запрещены. Этот режим предназначен только для B4. Перед чтением результата сервер заново проверяет доступ ко всем исходным кабинетам.

Для итогов и предупреждений отдельно запросите:

curl \
  "https://api.alitos.io/v1/external/operations/${OPERATION_ID}?view=compact&includeSummary=true" \
  --header "Authorization: Bearer ${ALITOS_EXTERNAL_JWT}"

В result находятся сводные данные, включая totalSources, returnedSources, scannedDeals, truncated и доступные предупреждения dataQualityWarnings. Сами строки источников находятся в ответе /result?view=all.

Когда нужен ограниченный результат

Для намеренного рейтинга используйте sourceRowsMode: "top" и положительный maxResults от 1 до 5000. Для итогов и групп без строк — sourceRowsMode: "none". По умолчанию maxResults=0 и includeSourceRows=true, поэтому без явного режима выбирается all. Для совместимости положительный maxResults без режима при включённых строках означает top, а includeSourceRows=false без переопределяющего режима — none.

Эти режимы выбора строк не заменяют проверку прав и не меняют исходные данные. Хранение результата, обновление JWT и ошибки чтения описаны в правилах операций.