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

Обновить запись справочника

PATCH /v1/statuses/:id

Обновляет поля записи справочника CRM по ID.

Параметры пути

Параметр Тип Описание
Параметрid Типnumber ОписаниеID записи справочника

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

Параметр Тип Описание
Параметрname Типstring ОписаниеНазвание
Параметрdescription Типstring ОписаниеОписание записи. Поле есть не на всех порталах Битрикс24
Параметрsort Типnumber ОписаниеПорядок сортировки
Параметрcolor Типstring ОписаниеЦвет в HEX, напр. #22B9FF. Решётку можно опустить

Поля entityId, statusId и semantics задаются только при создании записи, а categoryId определяется справочником entityId. Ни одно из этих четырёх полей вызов не меняет.

Примеры

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

Terminal
curl -X PATCH "https://vibecode.bitrix24.tech/v1/statuses/42" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Предоплата получена", "sort": 35}'

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

Terminal
curl -X PATCH "https://vibecode.bitrix24.tech/v1/statuses/42" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Предоплата получена", "sort": 35}'

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

javascript
const res = await fetch('https://vibecode.bitrix24.tech/v1/statuses/42', {
  method: 'PATCH',
  headers: { 'X-Api-Key': 'YOUR_API_KEY', 'Content-Type': 'application/json' },
  body: JSON.stringify({ name: 'Предоплата получена', sort: 35 }),
})
const { success, data } = await res.json()

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

javascript
const res = await fetch('https://vibecode.bitrix24.tech/v1/statuses/42', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ name: 'Предоплата получена', sort: 35 }),
})
const { success, data } = await res.json()

Поля ответа

Возвращается обновлённая запись целиком.

Поле Тип Описание
Полеsuccess Типboolean ОписаниеВсегда true при успехе
Полеdata Типobject ОписаниеОбновлённая запись справочника (все поля — см. Поля справочника)
Полеmeta.warnings Типarray ОписаниеЕсть, когда в теле переданы поля, которых нет в GET /v1/statuses/fields, например имя с опечаткой. Код предупреждения UNRECOGNIZED_WRITE_FIELD: такое поле могло не сохраниться. Ответ приходит с кодом 200

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

JSON
{
  "success": true,
  "data": {
    "id": 42,
    "entityId": "DEAL_STAGE",
    "statusId": "PREPAYMENT_INVOICE",
    "name": "Предоплата получена",
    "nameInit": null,
    "sort": 35,
    "system": false,
    "categoryId": null,
    "color": "#39A8EF",
    "semantics": null,
    "description": null,
    "extra": {
      "SEMANTICS": "process",
      "COLOR": "#39A8EF"
    }
  }
}

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

404 — запись не найдена:

JSON
{
  "success": false,
  "error": { "code": "ENTITY_NOT_FOUND", "message": "Status is not found." }
}

Ошибки

HTTP Код Описание
HTTP400 КодREADONLY_FIELD ОписаниеВ теле передано поле только для чтения: id, system или extra
HTTP400 КодEMPTY_UPDATE_BODY ОписаниеТело запроса пустое — передайте хотя бы одно поле
HTTP404 КодENTITY_NOT_FOUND ОписаниеЗапись с указанным id не найдена
HTTP403 КодSCOPE_DENIED ОписаниеAPI-ключ не имеет скоупа crm
HTTP401 КодMISSING_API_KEY ОписаниеНе передан заголовок X-Api-Key

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

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

Неизменяемые поля в теле не дают ошибки. Если передать entityId, statusId, semantics или categoryId, ответ придёт с кодом 200 и success: true, а эти поля сохранят прежние значения. Значение semantics вне набора S, F, null тоже не отклоняется. Поэтому success: true не означает, что поле изменилось: сверяйте результат по data ответа.

Как перевести стадию в другую группу. Группу существующей стадии через API не сменить, поэтому стадию заменяют новой:

  1. Создайте стадию в том же справочнике через POST /v1/statuses. Без semantics она станет промежуточной, с semantics: "F" — финальной стадией провала. Успешная стадия в воронке одна, вторую создать нельзя.
  2. Перенесите элементы на новую стадию, передав её код в stageId: для сделок — PATCH /v1/deals/:id, для элементов смарт-процесса — PATCH /v1/items/:entityTypeId/:id.
  3. Удалите старую стадию через DELETE /v1/statuses/:id. Пока на ней остаются элементы, удаление отвечает 422 BITRIX_ERROR.

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