Воронки

Универсальное управление воронками CRM для любого типа сущности: сделок, смарт-процессов и других. Каждая воронка содержит свой набор стадий. В отличие от воронок сделок, этот эндпоинт работает для всех типов CRM через единый путь.

Битрикс24 API: crm.category.* Скоуп: crm

Путь содержит динамический параметр :entityTypeId — ID типа CRM-сущности. Для сделок это 2, для счетов — 31, для смарт-процессов — значение из GET /v1/smart-processes. Основная воронка сделок доступна здесь по id 0.

Создать воронку

POST /v1/categories/:entityTypeId

Создаёт новую воронку для указанного типа CRM-сущности. Поля передаются плоско в корне JSON — без обёртки fields.

Параметры

Параметр Тип Обяз. Описание
entityTypeId (path) number да ID типа CRM-сущности. Для сделок 2, для счетов 31, для смарт-процесса — значение из GET /v1/smart-processes

Поля запроса (body)

Поле Битрикс24 Тип Обяз. Описание
name name string да Название воронки
sort sort number нет Порядок сортировки среди воронок типа

Примеры

В примерах entityTypeId = 2 (сделки) — замените на нужный тип.

curl — личный ключ

Terminal 
curl -X POST "https://vibecode.bitrix24.tech/v1/categories/2" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Воронка партнёров",
    "sort": 500
  }'

curl — OAuth-приложение

Terminal 
curl -X POST "https://vibecode.bitrix24.tech/v1/categories/2" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Воронка партнёров",
    "sort": 500
  }'

JavaScript — личный ключ

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/categories/2', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Воронка партнёров',
    sort: 500,
  }),
})

const { success, data } = await res.json()
console.log('ID воронки:', data.id)

JavaScript — OAuth-приложение

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/categories/2', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Воронка партнёров',
    sort: 500,
  }),
})

const { success, data } = await res.json()

Поля ответа

Возвращается полный объект созданной воронки с присвоенным id.

Поле Тип Описание
id number Идентификатор созданной воронки
entityTypeId number ID типа CRM-сущности, повторяет параметр пути
name string Название воронки
sort number Порядок сортировки
isDefault boolean Признак основной воронки типа
originId string Внешний идентификатор источника, пустая строка при отсутствии
originatorId string Идентификатор внешней системы, пустая строка при отсутствии

Пример ответа

JSON 
{
  "success": true,
  "data": {
    "id": 15,
    "name": "Воронка партнёров",
    "sort": 500,
    "entityTypeId": 2,
    "isDefault": false,
    "originId": "",
    "originatorId": ""
  }
}

Пример ответа при ошибке

422 — не передано обязательное поле name:

JSON 
{
  "success": false,
  "error": {
    "code": "BITRIX_ERROR",
    "message": "Field 'NAME' is required."
  }
}

Ошибки

HTTP Код Описание
400 READONLY_FIELD Передано поле только для чтения — code или isDefault. Сообщение называет конкретное поле
422 BITRIX_ERROR Не передано обязательное поле name — сообщение Field 'NAME' is required.
404 ENTITY_NOT_FOUND entityTypeId не соответствует существующему типу — сообщение Смарт-процесс не найден
422 BITRIX_ERROR Тип сущности не поддерживает воронки, например предложения 7 — сообщение Сущность CRM Предложение не поддерживается
403 SCOPE_DENIED API-ключ не имеет скоупа crm
401 TOKEN_MISSING API-ключ не имеет настроенных токенов

Полный список общих ошибок API — Ошибки.

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

Поля code и isDefault — только чтение. Передача code или isDefault в теле запроса возвращает 400 READONLY_FIELD — уберите эти поля из запроса. Основная воронка типа назначается в интерфейсе Битрикс24.

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