Для AI-агентов: markdown этой страницы — /docs-content/stage-history.md индекс документации — /llms.txt

История стадий

GET /v1/stage-history

Возвращает историю переходов CRM-записей по стадиям и статусам — когда запись попала на каждую стадию воронки. Применяется для отчётов по скорости движения сделок, лидов и элементов смарт-процессов и для анализа конверсии по воронкам.

Битрикс24 API: crm.stagehistory.list Скоуп: crm

Параметры

Набор полей фильтра по стадии зависит от типа записи. Для stage-типов deal, invoice, new-invoice и смарт-процессов доступны stageId, stageSemanticId, categoryId. Для status-типа lead доступны statusId, statusSemanticId. Поле не от своего типа возвращает 400 INVALID_FILTER_FIELD.

Параметр Тип Обяз. По умолч. Описание
entityType (query) string нет deal Тип CRM-записи: deal, lead, invoice — счёт, new-invoice — синоним invoice. Для смарт-процесса передайте числовой идентификатор значением entityType, например ?entityType=128. Отдельные query-ключи entityTypeId и entityTypeID отклоняются с 400 INVALID_ENTITY_TYPE. Список: GET /v1/smart-processes. Передавайте параметр не более одного раза
ownerId (query) number нет — Идентификатор записи, чью историю переходов вернуть. Зависит от entityType. Источники: GET /v1/deals, GET /v1/leads, GET /v1/invoices, для смарт-процессов — GET /v1/items/{entityTypeId}
typeId (query) number нет — Тип перехода: 1 — создание записи, 2 — перевод на промежуточную стадию, 3 — перевод на финальную стадию, 5 — смена воронки
createdAfter (query) string нет — Переходы начиная с указанного момента включительно (ISO 8601)
createdBefore (query) string нет — Переходы до указанного момента включительно (ISO 8601)
stageId (query) string нет — Только stage-типы. Фильтр по стадии. Список для сделок: GET /v1/statuses?filter[entityId]=DEAL_STAGE; для смарт-процесса — GET /v1/statuses?filter[entityId]=DYNAMIC_{entityTypeId}_STAGE_{categoryId}
stageSemanticId (query) string нет — Только stage-типы. Семантика стадии: P — промежуточная, S — успешная, F — провальная
categoryId (query) number нет — Только stage-типы. Идентификатор воронки. Список для сделок: GET /v1/deal-categories; для смарт-процесса — GET /v1/categories/{entityTypeId}
statusId (query) string нет — Только lead. Фильтр по статусу. Список: GET /v1/statuses?filter[entityId]=STATUS
statusSemanticId (query) string нет — Только lead. Семантика статуса: P — промежуточный, S — успешный, F — провальный
limit (query) number нет 50 Количество записей за вызов. Максимум 5000
offset (query) number нет 0 Сдвиг выборки. Округляется вниз до кратного 50

Для limit > 50 Вайбкод автоматически пагинирует запрос на стороне сервера. Максимум — 5000 записей за вызов. Поле meta.hasMore показывает, есть ли записи за пределами текущей выборки.

Примеры

curl — личный ключ

Terminal 
curl "https://vibecode.bitrix24.tech/v1/stage-history?entityType=deal&limit=50" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth-приложение

Terminal 
curl "https://vibecode.bitrix24.tech/v1/stage-history?entityType=deal&limit=50" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — личный ключ

javascript 
const params = new URLSearchParams({ entityType: 'deal', limit: '50' })
const res = await fetch(`https://vibecode.bitrix24.tech/v1/stage-history?${params}`, {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})

const { success, data, meta } = await res.json()

JavaScript — OAuth-приложение

javascript 
const params = new URLSearchParams({ entityType: 'deal', limit: '50' })
const res = await fetch(`https://vibecode.bitrix24.tech/v1/stage-history?${params}`, {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const { success, data, meta } = await res.json()

Поля ответа

Состав полей записи зависит от типа: stage-типы (deal, invoice, new-invoice, смарт-процессы) возвращают stageId, stageSemanticId, categoryId, а status-тип lead — statusId, statusSemanticId.

Поле Тип Описание
success boolean Всегда true при успехе
data array Массив записей истории, от новых к старым
data[].id number Идентификатор записи истории
data[].typeId number Тип перехода: 1 — создание, 2 — промежуточная стадия, 3 — финальная стадия, 5 — смена воронки
data[].ownerId number Идентификатор записи, в которой произошёл переход
data[].createdAt string Момент перехода на стадию (ISO 8601)
data[].stageId string Стадия. Только stage-типы
data[].stageSemanticId string Семантика стадии: P, S, F. Только stage-типы
data[].categoryId number Воронка. Только stage-типы
data[].statusId string Статус. Только lead
data[].statusSemanticId string Семантика статуса: P, S, F. Только lead
meta.total number Общее количество записей под фильтром
meta.hasMore boolean Есть ли записи за пределами текущей выборки

Пример ответа

Сделка (entityType=deal) — переходы по стадиям воронки:

JSON 
{
  "success": true,
  "data": [
    {
      "id": 12857,
      "typeId": 1,
      "ownerId": 7913,
      "createdAt": "2026-06-24T00:03:50+03:00",
      "categoryId": 9,
      "stageSemanticId": "P",
      "stageId": "C9:NEW"
    },
    {
      "id": 12855,
      "typeId": 1,
      "ownerId": 7911,
      "createdAt": "2026-06-23T00:02:34+03:00",
      "categoryId": 9,
      "stageSemanticId": "P",
      "stageId": "C9:NEW"
    }
  ],
  "meta": {
    "total": 2941,
    "hasMore": true
  }
}

Лид (entityType=lead) — переходы по статусам:

JSON 
{
  "success": true,
  "data": [
    {
      "id": 3689,
      "typeId": 1,
      "ownerId": 1001083,
      "createdAt": "2026-06-10T18:03:12+03:00",
      "statusId": "NEW",
      "statusSemanticId": "P"
    }
  ],
  "meta": {
    "total": 296,
    "hasMore": true
  }
}

Смарт-процесс (entityType=164) — переходы по стадиям, как у сделки:

JSON 
{
  "success": true,
  "data": [
    {
      "id": 47,
      "typeId": 1,
      "ownerId": 55,
      "createdAt": "2026-08-04T22:07:23+03:00",
      "categoryId": 27,
      "stageSemanticId": "P",
      "stageId": "DT164_27:NEW"
    }
  ],
  "meta": {
    "total": 1,
    "hasMore": false
  }
}

Пример ответа при ошибке

400 — поле фильтра не подходит для типа записи:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_FILTER_FIELD",
    "message": "\"statusId\" is not a valid filter for entityType \"deal\". entityType \"deal\" is stage-based — use stageId."
  }
}

Ошибки

HTTP Код Описание
400 INVALID_ENTITY_TYPE entityType не распознан: неизвестное имя, неканоническая числовая форма, числовой идентификатор выделенной сущности (1, 2, 31 — используйте имя), сущность без истории стадий (3, 4, 5, 7), повторённый параметр либо идентификатор, которого нет на портале. Отдельные query-ключи entityTypeId и entityTypeID также отклоняются; используйте entityType, например ?entityType=128
400 INVALID_FILTER_FIELD Поле фильтра не подходит для указанного entityType — например statusId для deal
400 INVALID_PARAMS Параметр передан не одним строковым значением — например ?ownerId[]=5 или ?ownerId[x]=1. Скобочные, повторённые и смешанные формы не принимаются: ?ownerId[]=5&ownerId[]=6 и ?ownerId[]=6&ownerId=5 иначе молча отфильтровали бы только по одному значению. Числовые параметры (ownerId, typeId, categoryId, limit, offset) вдобавок принимаются только целым числом, записанным полностью: ?ownerId=1e3 иначе прочитал бы историю владельца 1, а ?ownerId=abc вернул бы выборку шире запрошенной
403 SCOPE_DENIED Ключу не хватает скоупа crm
401 TOKEN_MISSING У ключа не настроены токены доступа
401 MISSING_API_KEY Не передан заголовок X-Api-Key
429 ERROR_LOOP_DETECTED Слишком много подряд отклонённых запросов по этому ключу. Перебор entityTypeId — типичная причина: берите идентификатор из GET /v1/smart-processes, а не подбором

Полный список общих ошибок API — Ошибки.

Как получить `entityTypeId` смарт-процесса

Числовой идентификатор типа возвращает GET /v1/smart-processes — поле entityTypeId каждого элемента. Он не совпадает с id типа и не вычисляется из него.

Terminal 
curl "https://vibecode.bitrix24.tech/v1/smart-processes" \
  -H "X-Api-Key: YOUR_API_KEY"

Полученное значение подставляется в entityType:

Terminal 
curl "https://vibecode.bitrix24.tech/v1/stage-history?entityType=164&limit=50" \
  -H "X-Api-Key: YOUR_API_KEY"

Не подбирайте идентификатор перебором. Каждый запрос с несуществующим entityTypeId доходит до Битрикс24 и отклоняется, а серия таких отказов подряд приводит к 429 ERROR_LOOP_DETECTED для ключа — после чего перестают проходить и обычные запросы истории по сделкам.

Известные особенности

Сортировка не настраивается. Параметр сортировки не принимается — порядок записей изменить нельзя.

Смотрите также