Для 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 показывает, есть ли записи за пределами текущей выборки.

Общий параметр filter этим эндпоинтом не применяется. По умолчанию API сохраняет прежний ответ HTTP 200 и прежние данные, добавляет заголовок Warning: 299 - "filter is not supported on this endpoint and was ignored", а сервер фиксирует использование неподдерживаемого фильтра в журнале.

Примеры

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 Код Описание
HTTP200 КодWarning: 299 ОписаниеФильтр игнорируется по умолчанию; прежние данные сохраняются, предупреждение передаётся заголовком Warning.
HTTP400 только при включённом строгом режиме КодUNSUPPORTED_FILTER ОписаниеСерверный режим выключен по умолчанию; до его включения эндпоинт сохраняет HTTP 200 и прежние данные.
HTTP400 КодINVALID_ENTITY_TYPE ОписаниеentityType не распознан: неизвестное имя, неканоническая числовая форма, числовой идентификатор выделенной сущности (1, 2, 31 — используйте имя), сущность без истории стадий (3, 4, 5, 7), повторённый параметр либо идентификатор, которого нет на портале. Отдельные query-ключи entityTypeId и entityTypeID также отклоняются; используйте entityType, например ?entityType=128
HTTP400 КодINVALID_FILTER_FIELD ОписаниеПоле фильтра не подходит для указанного entityType — например statusId для deal
HTTP400 Код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 вернул бы выборку шире запрошенной
HTTP403 КодSCOPE_DENIED ОписаниеКлючу не хватает скоупа crm
HTTP401 КодTOKEN_MISSING ОписаниеУ ключа не настроены токены доступа
HTTP401 КодMISSING_API_KEY ОписаниеНе передан заголовок X-Api-Key
HTTP429 Код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 для ключа — после чего перестают проходить и обычные запросы истории по сделкам.

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

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

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