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