Для AI-агентов: markdown этой страницы — /docs-content/crm-api-modes.md индекс документации — /llms.txt
Режимы CRM API
CRM-маршруты API Вайбкод работают в одном из двух режимов: через прежнюю версию REST API Битрикс24 (v2) или через новую (v3). Адреса маршрутов и имена полей в обоих режимах одинаковые, различается источник данных.
Базовый URL: https://vibecode.bitrix24.tech/v1 | Авторизация: X-Api-Key | Заголовок режима: X-Crm-Api
Что важно знать сразу
- Режим хранится на ключе. Новый ключ получает
v2илиv3в зависимости от режима выдачи новых ключей, установленного для аккаунта Битрикс24. Если ключ наследует режим прежнего ключа, используется унаследованный режим. Режим, в котором портал выдаёт новые ключи, показывает полеnewKeyModeв самоописании ключа. Ключ в режимеv2ведёт себя так же, как до появления режимов. Ключ, выпущенный взамен действующего, получает его режим. Ключ Коворка, выпущенный после отзыва прежнего или для ещё одного устройства, получает режим последнего ключа Коворка того же человека. - Заголовок перекрывает режим ключа. Запрос с заголовком
X-Crm-Api: v2илиX-Crm-Api: v3выполняется в указанном режиме, режим ключа при этом не меняется. - Ответ называет режим. Ответ маршрута, который видит режим, несёт заголовок
X-Crm-Apiсо значениемv2илиv3— режимом, в котором запрос выполнен, — когда запрос сам прислалX-Crm-Apiили ключ работает в режимеv3. Ответ ключу в режимеv2на запрос без заголовкаX-Crm-Apiостаётся прежним, заголовка в нём нет. - В режиме
v3запрос не уходит вv2молча. То, чего режимv3не умеет, получает отказ422 CRM_V3_UNSUPPORTEDс подсказкой повторить тот же запрос с заголовкомX-Crm-Api: v2. Маршруты, которые режим не видят, выполняются через прежнюю версию и отвечают без заголовкаX-Crm-Api. - Режим
v3доступен на любом портале. Он включается заголовкомX-Crm-Api: v3или режимом ключа. Если на портале нет новой версии REST API Битрикс24 — например, на коробке со старым модулем REST, — запрос в режимеv3получает тот же отказ422 CRM_V3_UNSUPPORTEDс подсказкой повторить его в режимеv2.
Какие маршруты видят режим
Режим действует на маршруты сущностей CRM: сделки, контакты, компании, лиды, смарт-процессы, предложения, счета, дела, реквизиты, банковские реквизиты, адреса, воронки и справочники CRM.
Остальные маршруты режим не видят: отвечают одинаково при любом значении заголовка и заголовок X-Crm-Api в ответ не добавляют. Среди них — валюты, типы смарт-процессов, автоматизированные решения и каталог товаров: собственных методов в новой версии REST API Битрикс24 у них нет. У сущностей CRM режим видят основные операции — список, чтение, создание, изменение, удаление, поиск, агрегация, описание полей и импорт, — а также перевод на другую стадию и связи между записями. Остальные маршруты сущностей режим не видят и выполняются через прежнюю версию: товарные строки /v1/{entity}/:id/products, дела записи /v1/{entity}/:id/activities и действия с делами, конвертация лида POST /v1/leads/:id/convert, файлы записей и другие. Заголовок X-Crm-Api на них не разбирается: любое его значение, в том числе ошибочное, ответа не меняет, и в ответ заголовок не добавляется. По отсутствию этого заголовка в ответе видно, что запрос выполнила прежняя версия. Перевод на другую стадию и связи между записями — контакты сделки, лида и компании, компании контакта — режим видят: у сделки они работают в режиме v3 (таблица ниже), у лида, контакта и компании получают отказ 422 CRM_V3_UNSUPPORTED. Импорт записей режим видит: в режиме v3 он получает отказ 422 CRM_V3_UNSUPPORTED с подсказкой повторить запрос с заголовком X-Crm-Api: v2.
В режиме v3 сейчас работают маршруты сделок:
| Маршрут | Как работает в режиме v3 |
|---|---|
МаршрутGET /v1/deals |
Как работает в режиме v3Фильтр, сортировка, limit, offset и meta.total. Записи читаются из Битрикс24 страницами до 1000 штук. Когда последняя прочитанная страница заполнена целиком, meta.total считается отдельным запросом к Битрикс24 |
МаршрутGET /v1/deals/:id |
Как работает в режиме v3Без select приходят все поля, у которых есть пара в новой версии, с select — только названные |
МаршрутPOST /v1/deals/search |
Как работает в режиме v3Диапазон дат в фильтре не делится на окна: autoWindow в режиме v3 не действует |
МаршрутPOST /v1/deals/aggregate |
Как работает в режиме v3Считает по записям, прочитанным в режиме v3. Группировка по stageId и stageSemanticId тоже считается по прочитанным записям, а не отдельным подсчётом на каждую стадию |
МаршрутGET /v1/deals/aggregate |
Как работает в режиме v3Считает так же, как POST /v1/deals/aggregate |
МаршрутPOST /v1/deals |
Как работает в режиме v3Создание сделки. Ответ — созданная сделка, прочитанная в режиме v3 |
МаршрутPATCH /v1/deals/:id |
Как работает в режиме v3Изменение сделки. Ответ — сделка после изменения, прочитанная в режиме v3 |
МаршрутDELETE /v1/deals/:id |
Как работает в режиме v3Удаление сделки |
МаршрутPOST /v1/deals/:id/move |
Как работает в режиме v3Перевод на другую стадию. Ответ — сделка после перевода, прочитанная в режиме v3 |
МаршрутGET /v1/deals/:id/contacts |
Как работает в режиме v3Контакты сделки без sort и roleId. Основной контакт — первый |
МаршрутPOST /v1/deals/:id/contacts |
Как работает в режиме v3Добавляет контакт в конец списка. С isPrimary: true — двумя вызовами Битрикс24 |
МаршрутPUT /v1/deals/:id/contacts |
Как работает в режиме v3Записывает список контактов целиком, основной контакт ставится первым |
МаршрутDELETE /v1/deals/:id/contacts/:relatedId |
Как работает в режиме v3Отвязывает контакт |
МаршрутDELETE /v1/deals/:id/contacts |
Как работает в режиме v3Отвязывает все контакты |
Отличия сделок в этом режиме — в разделе «Режим v3» страницы сделок. Любая другая операция перечисленных сущностей, которая видит режим, в режиме v3 отвечает 422 CRM_V3_UNSUPPORTED. Описание полей GET /v1/{entity}/fields в режиме v3 отдаётся так же, как в режиме v2.
Как выбирается режим
Режим запроса определяется по первому заданному источнику:
| Порядок | Источник | Значения |
|---|---|---|
| Порядок1 | ИсточникЗаголовок запроса X-Crm-Api |
Значенияv2, v3 — без учёта регистра и пробелов по краям |
| Порядок2 | ИсточникРежим ключа | Значенияv2, v3 — блок crmApi в ответе GET /v1/me |
| Порядок3 | ИсточникЗначение по умолчанию | Значенияv2 |
Заголовок с другим значением на маршруте, который видит режим, получает 400 INVALID_PARAMS. Переключателя режима ключа в личном кабинете нет: режим задаётся при создании ключа. Чтобы работать в режиме v3 ключом в режиме v2, присылайте заголовок X-Crm-Api: v3 с каждым запросом.
Как узнать режим ключа
Ответ GET /v1/me ключа, привязанного к порталу, содержит блок data.crmApi.
| Поле | Тип | Описание |
|---|---|---|
Полеmode |
Типstring | ОписаниеРежим ключа: v2 или v3 |
ПолеnewKeyMode |
Типstring | ОписаниеРежим, в котором на этом портале создаются новые ключи: v2 или v3 |
Полеheader |
Типstring | ОписаниеИмя заголовка, которым запрос выбирает режим, — X-Crm-Api |
Полеoverride |
Типstring | ОписаниеПодсказка о заголовке на языке владельца ключа |
{
"success": true,
"data": {
"crmApi": {
"mode": "v3",
"newKeyMode": "v2",
"header": "X-Crm-Api",
"override": "X-Crm-Api: v2|v3 — заголовок запроса к CRM-маршрутам, перекрывает режим ключа."
}
}
}
Примеры
Запрос сделки в режиме v3 по заголовку. Примеры на JavaScript повторяют запрос в режиме v2, если режим v3 ответил отказом CRM_V3_UNSUPPORTED: getDeal(7, 'v3').
curl — личный ключ
curl -i "https://vibecode.bitrix24.tech/v1/deals/7?select=title,amount,stageId" \
-H "X-Api-Key: YOUR_API_KEY" \
-H "X-Crm-Api: v3"
curl — OAuth-приложение
curl -i "https://vibecode.bitrix24.tech/v1/deals/7?select=title,amount,stageId" \
-H "X-Api-Key: YOUR_APP_KEY" \
-H "Authorization: Bearer USER_SESSION_TOKEN" \
-H "X-Crm-Api: v3"
JavaScript — личный ключ
async function getDeal(id, mode) {
const res = await fetch(`https://vibecode.bitrix24.tech/v1/deals/${id}?select=title,amount,stageId`, {
headers: { 'X-Api-Key': 'YOUR_API_KEY', ...(mode ? { 'X-Crm-Api': mode } : {}) },
})
const body = await res.json()
if (res.status === 422 && body.error?.code === 'CRM_V3_UNSUPPORTED') {
return getDeal(id, body.error.details.retryWith.value)
}
console.log('Режим ответа:', res.headers.get('X-Crm-Api'))
return body
}
JavaScript — OAuth-приложение
async function getDeal(id, mode) {
const res = await fetch(`https://vibecode.bitrix24.tech/v1/deals/${id}?select=title,amount,stageId`, {
headers: {
'X-Api-Key': 'YOUR_APP_KEY',
'Authorization': 'Bearer USER_SESSION_TOKEN',
...(mode ? { 'X-Crm-Api': mode } : {}),
},
})
const body = await res.json()
if (res.status === 422 && body.error?.code === 'CRM_V3_UNSUPPORTED') {
return getDeal(id, body.error.details.retryWith.value)
}
console.log('Режим ответа:', res.headers.get('X-Crm-Api'))
return body
}
Отказ CRM_V3_UNSUPPORTED
Отказ приходит со статусом 422. В error.message сказано, чего именно режим v3 не умеет. error.details.retryWith называет заголовок и значение, с которыми тот же запрос выполнится в режиме v2.
{
"success": false,
"error": {
"code": "CRM_V3_UNSUPPORTED",
"message": "Field \"probability\" has no counterpart in Bitrix24 REST v3.",
"hint": "Repeat the same request with the header X-Crm-Api: v2.",
"details": {
"retryWith": { "header": "X-Crm-Api", "value": "v2" }
}
}
}
Повтор с X-Crm-Api: v2 относится только к этому запросу: следующие запросы снова выполняются в режиме ключа.
Ошибки
| HTTP | Код | Описание |
|---|---|---|
| HTTP400 | КодINVALID_PARAMS |
ОписаниеЗаголовок X-Crm-Api на маршруте, который видит режим, задан значением, отличным от v2 и v3 |
| HTTP422 | КодCRM_V3_UNSUPPORTED |
ОписаниеНа портале нет новой версии REST API Битрикс24 или в ней нет метода для этой операции. Ответ несёт X-Crm-Api: v3 |
| HTTP422 | КодCRM_V3_UNSUPPORTED |
ОписаниеРежим v3 не умеет этот запрос: операцию, поле, форму значения, условие фильтра или сортировку. Ответ несёт X-Crm-Api: v3 |
Остальные ошибки в режиме v3 приходят с теми же кодами, что и в режиме v2: запись не найдена — 404 ENTITY_NOT_FOUND, нет прав — 403 BITRIX_ACCESS_DENIED, ошибка в значении поля — 400. Текст ошибки в этом режиме берётся из ответа новой версии REST API Битрикс24. Полный справочник — Коды ошибок.
Чего новая версия REST API Битрикс24 не умеет
Эти запросы в режиме v3 получают отказ 422 CRM_V3_UNSUPPORTED, и выполнить их можно только в режиме v2:
- поиск по подстроке в фильтре,
- фильтр по пустому значению у полей, кроме ссылочных
companyId,contactIdиmycompanyId, - фильтр и сортировка по множественным полям, по меткам
utm*, по полям времени последней коммуникацииlastCommunication*Timeи по пользовательским полям типовcrm,money,file,address,iblock_elementиiblock_section, - поля без пары в новой версии: в
select, в фильтре, в сортировке и при записи. У сделки это, например,probabilityиadditionalInfo, у лида —isReturnCustomer, - создание и изменение дел, общий список дел без владельца,
- статусы и стадии лидов, предложений и смарт-счетов.