Для AI-агентов: markdown этой страницы — /docs-content/entities/statuses.md индекс документации — /llms.txt

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

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

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

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

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

POST /v1/statuses

Создаёт новую запись в справочнике CRM.

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

Поле Тип Обяз. Описание
entityId string да Тип справочника, например SOURCE или DEAL_STAGE. Список: GET /v1/statuses/entity-types
statusId string да Символьный код значения, уникальный внутри справочника
name string да Название
description string нет Описание записи. Поле есть не на всех порталах Битрикс24
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()

Поля ответа

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

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

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

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

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

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

Ошибки

HTTP Код Описание
422 BITRIX_ERROR В справочнике уже есть запись с таким statusId. Сообщение — Указанный идентификатор статуса, уже существует.
422 BITRIX_ERROR Не передан entityId или statusId. Сообщение называет поле: The field ENTITY_ID is required.
422 BITRIX_ERROR Не передан name. Сообщение — Не заполнено обязательное поле "Заголовок"
403 WRITE_BLOCKED_READONLY_KEY Ключ только для чтения — см. права доступа
403 SCOPE_DENIED API-ключ не имеет скоупа crm
401 MISSING_API_KEY Не передан заголовок X-Api-Key

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

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