Справочники CRM

Стадии сделок, источники, типы контактов, отрасли и другие классификаторы. Центральная сущность для enum-значений всей CRM.

Bitrix24 API: crm.status.* Скоуп: crm

Для получения конкретного типа используйте фильтр: ?filter[entityId]=DEAL_STAGE

Создать запись справочника

POST /v1/statuses

Создаёт новую запись в справочнике CRM. Обязательные поля: entityId, statusId, name.

Параметры тела запроса

Параметр Тип Обязат. Описание
entityId string да Тип справочника (DEAL_STAGE, SOURCE и др.)
statusId string да Символьный код значения
name string да Название
sort number Порядок сортировки
color string Цвет в HEX, напр. #22B9FF. Решётку можно опустить
semantics string Семантика: S — успех, F — провал

Примеры

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

Terminal 
curl -X POST "https://vibecode.bitrix24.tech/v1/statuses" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"entityId": "SOURCE", "statusId": "PARTNER", "name": "Партнёр", "sort": 50}'

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

Terminal 
curl -X POST "https://vibecode.bitrix24.tech/v1/statuses" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"entityId": "SOURCE", "statusId": "PARTNER", "name": "Партнёр", "sort": 50}'

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/statuses', {
  method: 'POST',
  headers: { 'X-Api-Key': 'YOUR_API_KEY', 'Content-Type': 'application/json' },
  body: JSON.stringify({ entityId: 'SOURCE', statusId: 'PARTNER', name: 'Партнёр', sort: 50 }),
})
const { success, data } = await res.json()
console.log('ID:', data.id)

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/statuses', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ entityId: 'SOURCE', statusId: 'PARTNER', name: 'Партнёр', sort: 50 }),
})
const { success, data } = await res.json()

Поля ответа

Поле Тип Описание
id number ID записи
entityId string Тип справочника
statusId string Символьный код
name string Название
nameInit string/null Исходное название
sort number Сортировка
system boolean Системное значение. Только для чтения
categoryId number/null ID воронки. Заполняется для справочников вида DEAL_STAGE_N, иначе 0 или null
color string/null Цвет в HEX с ведущей #
semantics string/null Семантика: S — успех, F — провал. null — стадия «в работе» или справочник без семантики
extra object/null Дополнительные данные стадийных справочников DEAL_STAGE, QUOTE_STATUS, DEAL_STAGE_N — вложенные ключи SEMANTICS и COLOR. Только для чтения, у остальных справочников отсутствует

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

JSON 
{
  "success": true,
  "data": {
    "id": 801,
    "entityId": "SOURCE",
    "statusId": "PARTNER",
    "name": "Партнёр",
    "nameInit": null,
    "sort": 50,
    "system": false,
    "categoryId": 0,
    "color": null,
    "semantics": null
  }
}

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

422 — дублирование кода:

JSON 
{
  "success": false,
  "error": { "code": "BITRIX_ERROR", "message": "Указанный идентификатор статуса, уже существует." }
}

Ошибки

HTTP Код Описание
422 BITRIX_ERROR Ошибка Битрикс24 (дублирование statusId и др.)
403 SCOPE_DENIED API-ключ не имеет скоупа crm
401 TOKEN_MISSING Не передан API-ключ

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

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