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

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

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/null ОписаниеОписание записи. Приходит не на всех порталах Битрикс24 — на таком портале поле приходит как null
Поле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 Код Описание
HTTP422 КодBITRIX_ERROR ОписаниеВ справочнике уже есть запись с таким statusId. Сообщение — Указанный идентификатор статуса, уже существует.
HTTP422 КодBITRIX_ERROR ОписаниеНе передан entityId или statusId. Сообщение называет поле: The field ENTITY_ID is required.
HTTP422 КодBITRIX_ERROR ОписаниеНе передан name. Сообщение — Не заполнено обязательное поле "Заголовок"
HTTP403 КодWRITE_BLOCKED_READONLY_KEY ОписаниеКлюч только для чтения — см. права доступа
HTTP403 КодSCOPE_DENIED ОписаниеAPI-ключ не имеет скоупа crm
HTTP401 КодMISSING_API_KEY ОписаниеНе передан заголовок X-Api-Key

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

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