Для 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 — личный ключ
curl "https://vibecode.bitrix24.tech/v1/stage-history?entityType=deal&limit=50" \
-H "X-Api-Key: YOUR_API_KEY"
curl — OAuth-приложение
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 — личный ключ
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-приложение
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) — переходы по стадиям воронки:
{
"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) — переходы по статусам:
{
"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) — переходы по стадиям, как у сделки:
{
"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 — поле фильтра не подходит для типа записи:
{
"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 типа и не вычисляется из него.
curl "https://vibecode.bitrix24.tech/v1/smart-processes" \
-H "X-Api-Key: YOUR_API_KEY"
Полученное значение подставляется в entityType:
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 для
ключа — после чего перестают проходить и обычные запросы истории по сделкам.
Известные особенности
Сортировка не настраивается. Параметр сортировки не принимается — порядок записей изменить нельзя.