[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"docs-stage-history":3,"docs-tabs-stage-history":6},{"content":4,"lastmod":5},"# История стадий\n\n`GET \u002Fv1\u002Fstage-history`\n\nВозвращает историю переходов CRM-записей по стадиям и статусам — когда запись попала на каждую стадию воронки. Применяется для отчётов по скорости движения сделок и лидов и для анализа конверсии по воронкам.\n\nБитрикс24 API: `crm.stagehistory.list`\nСкоуп: `crm`\n\n## Параметры\n\nНабор полей фильтра по стадии зависит от типа записи. Для stage-типов `deal` и `invoice` доступны `stageId`, `stageSemanticId`, `categoryId`. Для status-типа `lead` доступны `statusId`, `statusSemanticId`. Поле не от своего типа возвращает `400 INVALID_FILTER_FIELD`.\n\n| Параметр | Тип | Обяз. | По умолч. | Описание |\n|----------|-----|:-----:|-----------|----------|\n| `entityType` (query) | string | нет | `deal` | Тип CRM-записи: `deal`, `lead`, `invoice` — счёт |\n| `ownerId` (query) | number | нет | — | Идентификатор записи, чью историю переходов вернуть. Зависит от `entityType`. Источники: `GET \u002Fv1\u002Fdeals`, `GET \u002Fv1\u002Fleads`, `GET \u002Fv1\u002Finvoices` |\n| `typeId` (query) | number | нет | — | Тип перехода: `1` — создание записи, `2` — перевод на промежуточную стадию, `3` — перевод на финальную стадию, `5` — смена воронки |\n| `createdAfter` (query) | string | нет | — | Переходы начиная с указанного момента включительно (ISO 8601) |\n| `createdBefore` (query) | string | нет | — | Переходы до указанного момента включительно (ISO 8601) |\n| `stageId` (query) | string | нет | — | Только `deal`, `invoice`. Фильтр по стадии. Список: `GET \u002Fv1\u002Fstatuses?filter[entityId]=DEAL_STAGE` |\n| `stageSemanticId` (query) | string | нет | — | Только `deal`, `invoice`. Семантика стадии: `P` — промежуточная, `S` — успешная, `F` — провальная |\n| `categoryId` (query) | number | нет | — | Только `deal`, `invoice`. Идентификатор воронки. Список: `GET \u002Fv1\u002Fdeal-categories` |\n| `statusId` (query) | string | нет | — | Только `lead`. Фильтр по статусу. Список: `GET \u002Fv1\u002Fstatuses?filter[entityId]=STATUS` |\n| `statusSemanticId` (query) | string | нет | — | Только `lead`. Семантика статуса: `P` — промежуточный, `S` — успешный, `F` — провальный |\n| `limit` (query) | number | нет | `50` | Количество записей за вызов. Максимум `5000` |\n| `offset` (query) | number | нет | `0` | Сдвиг выборки. Округляется вниз до кратного `50` |\n\nДля `limit > 50` Вайбкод автоматически пагинирует запрос на стороне сервера. Максимум — 5000 записей за вызов. Поле `meta.hasMore` показывает, есть ли записи за пределами текущей выборки.\n\n## Примеры\n\n### curl — личный ключ\n\n```bash\ncurl \"https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fstage-history?entityType=deal&limit=50\" \\\n  -H \"X-Api-Key: YOUR_API_KEY\"\n```\n\n### curl — OAuth-приложение\n\n```bash\ncurl \"https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fstage-history?entityType=deal&limit=50\" \\\n  -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\"\n```\n\n### JavaScript — личный ключ\n\n```javascript\nconst params = new URLSearchParams({ entityType: 'deal', limit: '50' })\nconst res = await fetch(`https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fstage-history?${params}`, {\n  headers: { 'X-Api-Key': 'YOUR_API_KEY' },\n})\n\nconst { success, data, meta } = await res.json()\n```\n\n### JavaScript — OAuth-приложение\n\n```javascript\nconst params = new URLSearchParams({ entityType: 'deal', limit: '50' })\nconst res = await fetch(`https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fstage-history?${params}`, {\n  headers: {\n    'X-Api-Key': 'YOUR_APP_KEY',\n    'Authorization': 'Bearer USER_SESSION_TOKEN',\n  },\n})\n\nconst { success, data, meta } = await res.json()\n```\n\n## Поля ответа\n\nСостав полей записи зависит от типа: stage-типы `deal` и `invoice` возвращают `stageId`, `stageSemanticId`, `categoryId`, а status-тип `lead` — `statusId`, `statusSemanticId`.\n\n| Поле | Тип | Описание |\n|------|-----|----------|\n| `success` | boolean | Всегда `true` при успехе |\n| `data` | array | Массив записей истории, от новых к старым |\n| `data[].id` | number | Идентификатор записи истории |\n| `data[].typeId` | number | Тип перехода: `1` — создание, `2` — промежуточная стадия, `3` — финальная стадия, `5` — смена воронки |\n| `data[].ownerId` | number | Идентификатор записи, в которой произошёл переход |\n| `data[].createdAt` | string | Момент перехода на стадию (ISO 8601) |\n| `data[].stageId` | string | Стадия. Только `deal`, `invoice` |\n| `data[].stageSemanticId` | string | Семантика стадии: `P`, `S`, `F`. Только `deal`, `invoice` |\n| `data[].categoryId` | number | Воронка. Только `deal`, `invoice` |\n| `data[].statusId` | string | Статус. Только `lead` |\n| `data[].statusSemanticId` | string | Семантика статуса: `P`, `S`, `F`. Только `lead` |\n| `meta.total` | number | Общее количество записей под фильтром |\n| `meta.hasMore` | boolean | Есть ли записи за пределами текущей выборки |\n\n## Пример ответа\n\nСделка (`entityType=deal`) — переходы по стадиям воронки:\n\n```json\n{\n  \"success\": true,\n  \"data\": [\n    {\n      \"id\": 12857,\n      \"typeId\": 1,\n      \"ownerId\": 7913,\n      \"createdAt\": \"2026-06-24T00:03:50+03:00\",\n      \"categoryId\": 9,\n      \"stageSemanticId\": \"P\",\n      \"stageId\": \"C9:NEW\"\n    },\n    {\n      \"id\": 12855,\n      \"typeId\": 1,\n      \"ownerId\": 7911,\n      \"createdAt\": \"2026-06-23T00:02:34+03:00\",\n      \"categoryId\": 9,\n      \"stageSemanticId\": \"P\",\n      \"stageId\": \"C9:NEW\"\n    }\n  ],\n  \"meta\": {\n    \"total\": 2941,\n    \"hasMore\": true\n  }\n}\n```\n\nЛид (`entityType=lead`) — переходы по статусам:\n\n```json\n{\n  \"success\": true,\n  \"data\": [\n    {\n      \"id\": 3689,\n      \"typeId\": 1,\n      \"ownerId\": 1001083,\n      \"createdAt\": \"2026-06-10T18:03:12+03:00\",\n      \"statusId\": \"NEW\",\n      \"statusSemanticId\": \"P\"\n    }\n  ],\n  \"meta\": {\n    \"total\": 296,\n    \"hasMore\": true\n  }\n}\n```\n\n## Пример ответа при ошибке\n\n400 — поле фильтра не подходит для типа записи:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"INVALID_FILTER_FIELD\",\n    \"message\": \"\\\"statusId\\\" is not a valid filter for entityType \\\"deal\\\". entityType \\\"deal\\\" is stage-based — use stageId.\"\n  }\n}\n```\n\n## Ошибки\n\n| HTTP | Код | Описание |\n|------|-----|----------|\n| 400 | `INVALID_ENTITY_TYPE` | Неизвестный `entityType`. Сообщение содержит список поддерживаемых значений |\n| 400 | `INVALID_FILTER_FIELD` | Поле фильтра не подходит для указанного `entityType` — например `statusId` для `deal` |\n| 403 | `SCOPE_DENIED` | Ключу не хватает скоупа `crm` |\n| 401 | `TOKEN_MISSING` | У ключа не настроены токены доступа |\n| 401 | `MISSING_API_KEY` | Не передан заголовок `X-Api-Key` |\n\nПолный список общих ошибок API — [Ошибки](\u002Fdocs\u002Ferrors).\n\n## Известные особенности\n\n**Сортировка не настраивается.** Параметр сортировки не принимается — порядок записей изменить нельзя.\n\n## Смотрите также\n\n- [Сделки](\u002Fdocs\u002Fentities\u002Fdeals)\n- [Лиды](\u002Fdocs\u002Fentities\u002Fleads)\n- [Статусы и стадии](\u002Fdocs\u002Fentities\u002Fstatuses)\n- [Воронки сделок](\u002Fdocs\u002Fentities\u002Fdeal-categories)\n- [Справочник сущностей](\u002Fdocs\u002Fentity-api)\n- [Ошибки](\u002Fdocs\u002Ferrors)\n","2026-06-25",{}]