Для AI-агентов: markdown этой страницы — /docs-content/userfields/tasks/update.md индекс документации — /llms.txt
Обновить поле
PATCH /v1/userfields/tasks/:id
Метод Б24: task.item.userfield.update. Скоуп: task.
Принимаются только label, mandatory, sort, settings, items. fieldName, userTypeId, multiple дают 400 IMMUTABLE_FIELD; неизвестные ключи и пустой объект — 400 INVALID_PARAMS. label — строка или карта языков, mandatory — boolean, sort — целое число.
Вариант с id обязательно несёт непустой value; для удаления передайте del:true. Иначе Б24 удалил бы вариант молча. Неупомянутые варианты остаются. Без xmlId обёртка сохраняет текущее значение; новый вариант без id добавляется. Пример: {"items":[{"id":8,"value":"Новое имя"},{"id":9,"del":true}]}.
Перед записью поле читается; системные поля дают 403 SYSTEM_FIELD_PROTECTED. Ответ содержит перечитанное поле. Б24 при любой правке может нормализовать settings и подписи неустановленных языков.
Ошибки и доступ
Нет скоупа: 403 SCOPE_DENIED. Без тарифной фичи TASK_CUSTOM_FIELDS: 403 TASK_CUSTOM_FIELDS_UNAVAILABLE, включая чтение. Поле не найдено: 404 ENTITY_NOT_FOUND. Невалидный ввод: 400; бизнес-отказ Б24: 422. Нет прав Б24 на запись: 403. Чтения доступны READONLY-ключу; записи требуют READWRITE и прав администратора портала. Записи автоматически не повторяются. После таймаута исход неизвестен: перечитайте поле перед новой записью.
Сортировка варианта items.sort должна быть положительной: Б24 игнорирует ноль. Для снятия def:true у одиночного списка выберите другой вариант с def:true в том же PATCH; иначе 400 INVALID_PARAMS. После подтверждённой записи ошибка перечитывания даёт 502 TASK_USERFIELD_READBACK_FAILED с error.fieldId и error.writeConfirmed:true: повторите GET, не запись.