# Режимы CRM API

CRM-маршруты API Вайбкод работают в одном из двух режимов: через прежнюю версию REST API Битрикс24 (`v2`) или через новую (`v3`). Адреса маршрутов и имена полей в обоих режимах одинаковые, различается источник данных.

**Базовый URL:** `https://vibecode.bitrix24.tech/v1` | **Авторизация:** `X-Api-Key` | **Заголовок режима:** `X-Crm-Api`

## Что важно знать сразу

1. **Режим хранится на ключе.** Новый ключ получает `v2` или `v3` в зависимости от режима выдачи новых ключей, установленного для аккаунта Битрикс24. Если ключ наследует режим прежнего ключа, используется унаследованный режим. Режим, в котором портал выдаёт новые ключи, показывает поле `newKeyMode` в [самоописании ключа](#как-узнать-режим-ключа). Ключ в режиме `v2` ведёт себя так же, как до появления режимов. Ключ, выпущенный взамен действующего, получает его режим. Ключ Коворка, выпущенный после отзыва прежнего или для ещё одного устройства, получает режим последнего ключа Коворка того же человека.
2. **Заголовок перекрывает режим ключа.** Запрос с заголовком `X-Crm-Api: v2` или `X-Crm-Api: v3` выполняется в указанном режиме, режим ключа при этом не меняется.
3. **Ответ называет режим.** Ответ маршрута, который [видит режим](#какие-маршруты-видят-режим), несёт заголовок `X-Crm-Api` со значением `v2` или `v3` — режимом, в котором запрос выполнен, — когда запрос сам прислал `X-Crm-Api` или ключ работает в режиме `v3`. Ответ ключу в режиме `v2` на запрос без заголовка `X-Crm-Api` остаётся прежним, заголовка в нём нет.
4. **В режиме `v3` запрос не уходит в `v2` молча.** То, чего режим `v3` не умеет, получает отказ `422 CRM_V3_UNSUPPORTED` с подсказкой повторить тот же запрос с заголовком `X-Crm-Api: v2`. Маршруты, которые режим не видят, выполняются через прежнюю версию и отвечают без заголовка `X-Crm-Api`.
5. **Режим `v3` доступен на любом портале.** Он включается заголовком `X-Crm-Api: v3` или режимом ключа. Если на портале нет новой версии REST API Битрикс24 — например, на коробке со старым модулем REST, — запрос в режиме `v3` получает тот же отказ `422 CRM_V3_UNSUPPORTED` с подсказкой повторить его в режиме `v2`.

## Какие маршруты видят режим

Режим действует на маршруты сущностей CRM: [сделки](./entities/deals.md), [контакты](./entities/contacts.md), [компании](./entities/companies.md), [лиды](./entities/leads.md), [смарт-процессы](./entities/items.md), [предложения](./entities/quotes.md), [счета](./entities/invoices.md), [дела](./entities/activities.md), [реквизиты](./entities/requisites.md), [банковские реквизиты](./entities/bank-details.md), [адреса](./entities/addresses.md), [воронки](./entities/categories.md) и [справочники CRM](./entities/statuses.md).

Остальные маршруты режим не видят: отвечают одинаково при любом значении заголовка и заголовок `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` | Фильтр, сортировка, `limit`, `offset` и `meta.total`. Записи читаются из Битрикс24 страницами до 1000 штук. Когда последняя прочитанная страница заполнена целиком, `meta.total` считается отдельным запросом к Битрикс24 |
| `GET /v1/deals/:id` | Без `select` приходят все поля, у которых есть пара в новой версии, с `select` — только названные |
| `POST /v1/deals/search` | Диапазон дат в фильтре не делится на окна: `autoWindow` в режиме `v3` не действует |
| `POST /v1/deals/aggregate` | Считает по записям, прочитанным в режиме `v3`. Группировка по `stageId` и `stageSemanticId` тоже считается по прочитанным записям, а не отдельным подсчётом на каждую стадию |
| `GET /v1/deals/aggregate` | Считает так же, как `POST /v1/deals/aggregate` |
| `POST /v1/deals` | Создание сделки. Ответ — созданная сделка, прочитанная в режиме `v3` |
| `PATCH /v1/deals/:id` | Изменение сделки. Ответ — сделка после изменения, прочитанная в режиме `v3` |
| `DELETE /v1/deals/:id` | Удаление сделки |
| `POST /v1/deals/:id/move` | Перевод на другую стадию. Ответ — сделка после перевода, прочитанная в режиме `v3` |
| `GET /v1/deals/:id/contacts` | Контакты сделки без `sort` и `roleId`. Основной контакт — первый |
| `POST /v1/deals/:id/contacts` | Добавляет контакт в конец списка. С `isPrimary: true` — двумя вызовами Битрикс24 |
| `PUT /v1/deals/:id/contacts` | Записывает список контактов целиком, основной контакт ставится первым |
| `DELETE /v1/deals/:id/contacts/:relatedId` | Отвязывает контакт |
| `DELETE /v1/deals/:id/contacts` | Отвязывает все контакты |

Отличия сделок в этом режиме — в разделе [«Режим v3»](./entities/deals.md#режим-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 | Подсказка о заголовке на языке владельца ключа |

```json
{
  "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 — личный ключ

```bash
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-приложение

```bash
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 — личный ключ

```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-приложение

```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_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`.

```json
{
  "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 | Код | Описание |
|------|-----|----------|
| 400 | `INVALID_PARAMS` | Заголовок `X-Crm-Api` на маршруте, который видит режим, задан значением, отличным от `v2` и `v3` |
| 422 | `CRM_V3_UNSUPPORTED` | На портале нет новой версии REST API Битрикс24 или в ней нет метода для этой операции. Ответ несёт `X-Crm-Api: v3` |
| 422 | `CRM_V3_UNSUPPORTED` | Режим `v3` не умеет этот запрос: операцию, поле, форму значения, условие фильтра или сортировку. Ответ несёт `X-Crm-Api: v3` |

Остальные ошибки в режиме `v3` приходят с теми же кодами, что и в режиме `v2`: запись не найдена — `404 ENTITY_NOT_FOUND`, нет прав — `403 BITRIX_ACCESS_DENIED`, ошибка в значении поля — `400`. Текст ошибки в этом режиме берётся из ответа новой версии REST API Битрикс24. Полный справочник — [Коды ошибок](./errors.md).

## Чего новая версия 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`,
- создание и изменение дел, общий список дел без владельца,
- статусы и стадии лидов, предложений и смарт-счетов.

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

- [Самоописание ключа](./keys-auth/me.md)
- [Сделки](./entities/deals.md) — раздел «Режим v3»
- [Список сделок](./entities/deals/list.md)
- [Поиск сделок](./entities/deals/search.md)
- [Агрегация сделок](./entities/deals/aggregate.md)
- [Регулярные сделки](./entities/recurring-deals.md)
- [Синтаксис фильтрации](./filtering.md)
- [Коды ошибок](./errors.md)
